# Generate a standalone summary

Submit plain text, transcript segments, or an existing minutes task ID in the same region. Exactly one input is required. Returns a complete structured report synchronously without uploading audio, running speech recognition, or charging ASR duration.

model defaults to deepseek-v4-flash and currently accepts only that model. The caller's visible channel and effective input/output/cache token prices apply. Funds are reserved before generation and observed usage is settled once, even if output is malformed or truncated. No automatic generation retry. If usable usage is absent, the reservation is released; usage.available=false means unknown usage. Use request_id to reconcile billing_status=pending instead of regenerating.

task_id must identify a readable minutes task with completed transcription: either status=succeeded, or status=failed with nonempty report v2 segments and quality.status=unavailable. Historical standard transcripts are supported. Summarizing again does not rerun ASR or change the original task. Running, cancelled or ASR-failed tasks return 409; inaccessible or missing tasks return 404.

report.version=2 includes overview, nested sections, chapters, todos, decisions, quotes, review items, visual semantics, speakers and source segments. Caller source IDs and speaker references remain stable; unknown timing is not invented. markdown exports the core summary only.

This is synchronous and creates no pollable summary task. Model generation has a 30-minute limit. Set a client timeout of at least 1920 seconds (32 minutes) and retain the result. Long requests send valid leading JSON whitespace after 45 seconds and every 15 seconds thereafter. A model timeout returns error.code=summary_timeout. After HTTP 200 has been committed, subsequent failure is indicated by status=failed, error and report.quality.status=unavailable; always inspect the response body. Client disconnection does not cancel observed-usage settlement.

Limits: 2 MiB request body, 524288 UTF-8 bytes of source text, 10000 segments, 1000 speakers. Body upload and preparation share a 30-second budget; upload timeouts return HTTP 408. Upstream context overflow fails explicitly without truncation or chunked retries.

## POST /v1/summaries

> Generate a standalone summary

Submit plain text, transcript segments, or an existing minutes task ID in the same region. Exactly one input is required. Returns a complete structured report synchronously without uploading audio, running speech recognition, or charging ASR duration.

model defaults to deepseek-v4-flash and currently accepts only that model. The caller's visible channel and effective input/output/cache token prices apply. Funds are reserved before generation and observed usage is settled once, even if output is malformed or truncated. No automatic generation retry. If usable usage is absent, the reservation is released; usage.available=false means unknown usage. Use request_id to reconcile billing_status=pending instead of regenerating.

task_id must identify a readable minutes task with completed transcription: either status=succeeded, or status=failed with nonempty report v2 segments and quality.status=unavailable. Historical standard transcripts are supported. Summarizing again does not rerun ASR or change the original task. Running, cancelled or ASR-failed tasks return 409; inaccessible or missing tasks return 404.

report.version=2 includes overview, nested sections, chapters, todos, decisions, quotes, review items, visual semantics, speakers and source segments. Caller source IDs and speaker references remain stable; unknown timing is not invented. markdown exports the core summary only.

This is synchronous and creates no pollable summary task. Model generation has a 30-minute limit. Set a client timeout of at least 1920 seconds (32 minutes) and retain the result. Long requests send valid leading JSON whitespace after 45 seconds and every 15 seconds thereafter. A model timeout returns error.code=summary_timeout. After HTTP 200 has been committed, subsequent failure is indicated by status=failed, error and report.quality.status=unavailable; always inspect the response body. Client disconnection does not cancel observed-usage settlement.

Limits: 2 MiB request body, 524288 UTF-8 bytes of source text, 10000 segments, 1000 speakers. Body upload and preparation share a 30-second budget; upload timeouts return HTTP 408. Upstream context overflow fails explicitly without truncation or chunked retries.

### Authentication

`Authorization: Bearer tr-xxx`

### Request Body

Content-Type: `application/json`

- **model** ``deepseek-v4-flash`` (default: `deepseek-v4-flash`)  
  
- **text** `string`  
  Plain text, limited to 524288 UTF-8 bytes. Split into source segments at newlines without rewriting text.
- **segments** `object[]`  
  Stable caller IDs are preserved. Total text is limited to 524288 UTF-8 bytes.
- **segments[].id** `string`  
  Optional stable ID; defaults to seg-000001 by input position. IDs must be unique.
- **segments[].text** `string` **(required)**  
  
- **segments[].startMs** `integer,null`  
  
- **segments[].endMs** `integer,null`  
  
- **segments[].speakerId** `object`  
  
- **speakers** `object[]`  
  Only with segments. IDs must be unique. Referenced IDs without a supplied name receive a neutral display name.
- **speakers[].id** `string` **(required)**  
  
- **speakers[].displayName** `string` **(required)**  
  
- **task_id** `string`  
  A minutes task readable by the current account in this region with completed transcription. Accepts succeeded tasks or failed summary tasks with nonempty report v2 segments and unavailable quality. Its transcript is reused; the task is not modified.
- **recorded_at** `string,null`  
  Actual recording time with timezone offset; never inferred from task creation time. Overrides task metadata when supplied.
- **timezone** `string,null`  
  IANA timezone, e.g. Asia/Shanghai. Overrides task metadata when supplied.
- **duration_ms** `integer,null`  
  Known recording duration. Leave absent when unknown; supplied times cannot exceed it.

### Response

- **object** `string` **(required)**  
  
- **request_id** `string` **(required)**  
  
- **model** `string` **(required)**  
  
- **status** ``succeeded` | `failed`` **(required)**  
  
- **created_at** `string` **(required)**  
  This summary request start time, not recording time.
- **source_task_id** `string,null` **(required)**  
  
- **report** `object` **(required)**  
  Structured report for new xrtoken-minutes results. Check quality.status before displaying. Source text and speaker IDs are authoritative; generated content still requires semantic review.
- **report.version** ``2`` **(required)**  
  
- **report.metadata** `object` **(required)**  
  
- **report.overview** `object` **(required)**  
  Content with source references. sourced means references passed structural validation, not independent factual verification. Resolve speaker runs using report.speakers at display time.
- **report.keyPoints** `object[]` **(required)**  
  
- **report.sections** `object[]` **(required)**  
  
- **report.chapters** `object[]` **(required)**  
  
- **report.todos** `object[]` **(required)**  
  
- **report.decisions** `object[]` **(required)**  
  
- **report.quotes** `object[]` **(required)**  
  
- **report.reviewItems** `object[]` **(required)**  
  
- **report.visuals** `object[]` **(required)**  
  
- **report.speakers** `object[]` **(required)**  
  
- **report.segments** `object[]` **(required)**  
  
- **report.quality** `object` **(required)**  
  complete: required content parsed and validation passed; partial: content needs review or validation removed invalid items; unavailable: summary generation/format failed, transcript remains available. Minutes tasks with unavailable summary quality are presented as failed while retaining completed transcription.
- **markdown** `string` **(required)**  
  Compatibility/export snapshot derived from the validated overview, key points and nested sections. Use report for all modules and speaker rename linkage.
- **usage** `object` **(required)**  
  
- **usage.prompt_tokens** `integer` **(required)**  
  Total input including cached tokens.
- **usage.completion_tokens** `integer` **(required)**  
  
- **usage.cached_tokens** `integer` **(required)**  
  Subset of prompt_tokens; billed using the applicable cache rate.
- **usage.total_tokens** `integer` **(required)**  
  
- **usage.available** `boolean` **(required)**  
  False means the upstream did not provide usable token counts; zero fields then mean unavailable, not measured zero.
- **usage.billing_status** ``settled` | `released` | `pending`` **(required)**  
  Observed usage is settled once. With no observed usage, the reservation is released. Pending indicates billing finalization needs reconciliation; do not repeat generation automatically.
- **error** `object`  
  
- **error.type** `string` **(required)**  
  
- **error.code** `string` **(required)**  
  
- **error.message** `string` **(required)**  
  

### Error Codes

- `400`: 
- `401`: 
- `402`: 
- `404`: Source minutes task not found or inaccessible
- `408`: Request body upload exceeded 30 seconds
- `409`: Source minutes task has no completed transcription
- `413`: Request body exceeds 2 MiB
- `429`: 
- `502`: Summary generation/validation failed; source report and observed usage are included
- `503`: Channel, source storage, pricing or billing unavailable