面向应用和 SaaS 产品的转写

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

获取 API 密钥 快速开始 支持的语言

最后更新: · Markdown

生产环境流程

  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。

任务请求：

{
  "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

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 美元。

相关页面