# 面向应用和 SaaS 产品的转写

> 用异步 REST API 为产品加入语音笔记、会议记录、字幕或可搜索的音频：上传、创建任务、接收 webhook、保存分段。

最后更新: 2026-10-08 · HTML: https://console.kolwrite.com/zh/use-cases/developers

## 生产环境流程

1. 后端为用户文件调用 `POST /upload`，把签名表单返回给客户端，或由后端自行上传（最大 100 MiB）。
2. 用返回的 `fileUrl` 作为 `audio_url`，并带上你的 `webhook_url` 创建任务。
3. 验证 webhook 签名，按 `X-KolWrite-Delivery-Id` 去重；如果 `result_omitted` 为 true，再调用 `GET /transcribe/{jobId}`。
4. 保存 `segments`（文本、时间、说话人）并展示；按需导出 `srt` 或 `txt`。

任务请求：

```json
{
  "audio_url": "<fileUrl from POST /upload>",
  "model": "oracle",
  "language": "auto",
  "include_diarization": true,
  "output_format": "json",
  "webhook_url": "https://api.example.com/hooks/kolwrite",
  "webhook_secret": "<random secret>"
}
```

## 验证 webhook

```javascript
import crypto from "node:crypto";

// Express-style handler; rawBody is the exact request body as received.
export function verifyKolWrite(req, rawBody, secret) {
  const timestamp = req.headers["x-kolwrite-timestamp"];
  const expected = "sha256=" + crypto.createHmac("sha256", secret)
    .update(timestamp + "." + rawBody).digest("hex");
  const given = req.headers["x-kolwrite-signature"] || "";
  return given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}
```

投递至少一次，失败会重试。`GET /transcribe/{jobId}` 始终是权威来源。

## 按任务选择模型

| 产品需求 | 设置 | 原因 |
| --- | --- | --- |
| 大量清晰音频，低成本 | `model: "base"` | 每小时 0.40 额度（0.48 美元） |
| 用户上传文件的默认选择 | `model: "oracle"` | 生产级质量，支持翻译 |
| 输出另一种语言的文本 | Oracle 模型 + `translate_to` | 一个任务，得到译文 |
| 谁说了什么 | `include_diarization: true` | 包含在价格中 |
| 字幕 | `output_format: "srt"` | 可直接用于视频播放器 |

## 需要考虑的限制

- 内联 Base64 上传：解码后媒体最多 4 MiB。签名上传：最多 100 MiB。
- 签名上传表单 60 分钟后过期，读取 URL 24 小时后过期。
- 任务是异步的：用 `PENDING` 和 `IN_PROGRESS` 显示进度。
- `channel_speaker_separation` 不能与说话人分离同时使用。

## 常见问题

### 有 SDK 吗？

API 就是普通的 HTTPS 和 JSON，任何 HTTP 客户端都能用。/openapi.json 上的 OpenAPI 3.1 文件可用于代码生成器。

### 如何避免重复处理 webhook？

按 `X-KolWrite-Delivery-Id` 去重；重试会沿用同一个 ID。

### 如何计费？

按音频秒数和模型的额度费率计费，无最低消费。1 额度 = 1.20 美元。

## 相关页面

- [AI 智能体与氛围编程](https://console.kolwrite.com/zh/use-cases/ai-agents)
- [呼叫中心与销售电话](https://console.kolwrite.com/zh/use-cases/call-centers)
- [企业](https://console.kolwrite.com/zh/use-cases/enterprise)
- [支持的语言](https://console.kolwrite.com/zh/languages/)

---
获取 API 密钥: https://console.kolwrite.com/auth?lang=zh · API 文档: https://console.kolwrite.com/zh/public_api_docs · llms.txt: https://console.kolwrite.com/llms.txt