# 生成独立摘要

直接提交文本、转写分段，或同区已有妙记任务 ID，同步返回完整结构化报告。三个输入必须且只能选择一个。无需上传音频，不触发语音识别，也不收取识别时长费用。

model 可省略，当前固定使用 deepseek-v4-flash，按账号可见渠道及实际输入、输出、缓存 token 计费。提交前预冻，完成后结算；格式失败或输出截断仍结算已报告的用量，不自动重试。未取得可用用量时释放预冻；usage.available=false 表示用量未知。billing_status=pending 时用 request_id 核对账务，不要自动重复生成。

task_id 必须是当前账号有权读取且转写已完成的妙记任务：支持 status=succeeded，或 status=failed 且 report v2 保留非空转写、quality.status=unavailable 的摘要失败任务。支持 report v2 或历史标准转写数组；其他原始提供方格式返回 400。重新提炼摘要不重跑识别、不修改原任务。处理中、已取消或转写失败任务返回 409，越权或不存在返回 404。

返回 report.version=2，包含核心速览、分层总结、章节、待办、决策、金句、核对项、图形语义、说话人及原文。原文 ID 和人物引用保持稳定；未知时间不编造。markdown 仅是核心摘要导出。

这是同步接口，不创建可轮询的摘要任务。模型调用上限为 30 分钟，建议客户端超时至少 1920 秒（32 分钟），保存返回结果。 长请求在第 45 秒开始发送合法 JSON 前导空白，此后每 15 秒保活；模型等待超时返回 error.code=summary_timeout。一旦已发出 HTTP 200，后续失败通过 status=failed、error 和 report.quality.status=unavailable 表示，因此始终检查响应体。客户端断开后服务仍完成本次调用并结算观测用量。

请求体最多 2 MiB；原文合计最多 524288 UTF-8 字节、10000 段、1000 位说话人。上传请求体及生成前准备合计最多 30 秒，上传超时返回 HTTP 408。 超出上游上下文能力时明确失败，不截断或分块重试。

## 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