# 转写 API 总览

> 把音频提交给 iKho 转写引擎,异步拿回带说话人与逐句时间戳的结构化逐字稿。

开发者平台处于内测阶段,接口契约以联调时提供的正式文档为准。当前 base URL 为 `https://ikho.cn/developer/api`,凭证由对接工程师开通,见[联系我们](/docs/mcp-cli/contact/)。

## 能力

  
- 说话人分离:自动区分并标注不同发言人,可选返回声纹向量。
  
- 逐句时间戳:每个片段带毫秒级起止时间,便于回放定位。
  
- 中英混说:同一句话中英文夹杂也能正确识别。
  
- 自动语种识别:不指定语言时自动判定,支持按片段或章节回报语种。

## 转写模型

| 模型 | 取向 | 适用场景 |
|---|---|---|
| `ikho-asr-pro` | 精度优先 | 会议纪要、医疗随访、销售拜访、访谈等对准确度要求高的长音频 |
| `ikho-asr-fast` | 时延优先 | 需要尽快拿到结果的场景,如门店巡检速记 |

## 异步轮询

转写是异步任务:提交音频后立即拿到 `transcription_id` 与初始状态,随后按此标识轮询任务,直到进入终态。

  
    1

    提交音频
调用 `POST /open/partner/ai/transcriptions/`,传入 `file_url` 与参数,返回 `transcription_id`。

  

  
    2

    轮询任务
调用 `GET /open/partner/ai/transcriptions/{transcription_id}` 查询状态。`PENDING`、`RECEIVED`、`STARTED`、`PROGRESS` 表示进行中,继续轮询;`SUCCESS` 表示结果就绪;`FAILURE`、`REVOKED` 为终态失败。

  

## 结果获取:轮询与回调

### 轮询节奏建议

  
- 短音频(几分钟以内):每 2 到 5 秒查询一次,通常很快进入终态。
  
- 长音频(半小时以上):从 10 到 30 秒的间隔起步,并配合指数退避逐步拉长,不必高频查询。
  
- 收到 `SUCCESS`、`FAILURE` 或 `REVOKED` 即停止轮询,不要对已终态的任务继续重查。

### 完成回调(Webhook)

规划中,尚未上线。后续版本计划支持在提交任务时登记回调地址,任务进入终态后由平台主动推送通知,收到通知再拉取一次完整结果即可,免去持续轮询。以下为拟定的回调 payload 示意,字段以正式发布为准:

  拟定回调 payload(规划中,字段以正式发布为准)
    
  

  
```
{
  "event": "transcription.completed",
  "transcription_id": "task_exec_5c8a2f",
  "status": "SUCCESS",
  "completed_at": "2026-07-24T10:32:08+08:00",
  "result_url": "https://ikho.cn/developer/api/open/partner/ai/transcriptions/task_exec_5c8a2f"
}
```

错误结构与错误码见[错误码参考](/docs/embedded/errors/)。