身份验证

所有 API 请求都必须使用您的唯一 API 密钥进行身份验证。请在请求标头中加入该密钥：

x-api-key: YOUR_API_KEY

您可以在以下部分生成和管理 API 密钥： KolWrite 控制台（需先创建账号）。

快速入门

通过这些基础示例快速上手。

1. 开始转写

向 `/transcribe` 端点发送 POST 请求，并提供要转写的音频文件 URL。

请求：

POST https://app.kolwrite.com/transcribe
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "audio_url": "https://salford.figshare.com/ndownloader/files/14630270"
}

响应：

API 会返回 `jobId`，您将使用它获取转写结果。

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57"
}

2. 获取转写结果

Send a GET request 至 the `/transcribe/{jobId}` endpoint using the `jobId` received from the previous step.

请求：

GET https://app.kolwrite.com/transcribe/34c63d45-4cb5-473b-bc60-25c175e69c57
x-api-key: YOUR_API_KEY

响应（示例）：

当任务状态为 COMPLETED，响应将包含转写详情。

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "result": {
    "language": "en",
    "segments": [
      {
        "start": 0.5,
        "end": 3.2,
        "text": "Hello everyone, welcome to today's meeting.",
        "speaker": "Speaker 1",
        "words": [
          {
            "start": 0.5,
            "end": 0.8,
            "word": "Hello"
          },
          {
            "start": 0.9,
            "end": 1.4,
            "word": "everyone"
          },
          {
            "start": 1.5,
            "end": 1.9,
            "word": "welcome"
          }
        ]
      }
    ]
  }
}

模型与用量额度

模型用量按秒以用量额度计量，不设最低收费。结账页面、收据和税务文件会显示购买时实际使用的付款货币。

1 个用量额度是 API 的计费单位，此前在 API 控制台中显示为 $1.00。

符合条件的以色列账单账号以 ILS 购买用量额度，净价为每额度 ILS 3.60（增值税前）。付款前，结账页面会显示用量额度、净额、增值税和最终 ILS 总额。除非另有订单条款，其他账号均按每额度 USD 1.20 以 USD 购买用量额度。

模型	API 值	额度/小时	最适合
Base	`base`	0.40	低成本转写、词级时间戳和说话人分离
Oracle Mini	`oracle_mini`	0.80	快速 Oracle 转录，可选翻译到任何支持的目标语言、说话人分离和声道分离；价格最低的 Oracle 翻译选项
Oracle	`oracle`	1.20	生产转写和多语言工作流
Oracle Pro	`oracle_pro`	1.40	高级生产质量
Oracle Max	`oracle_max`	3.00	为高难度或高风险音频提供最高质量
Core	`core`	1.00	旧版通用转写
Edge	`edge`	1.20	旧版高准确率转写

附加项： 标准说话人分离和 standard 声道分离均已包含。Pro 说话人分离另加 每音频小时 0.20 额度. overlap 声道分离按所选模型费率计费，按录音时长与其各物理声道中检测到的语音总时长中的较大者计算；两种声道模式都不收取额外的说话人分离费用。选择说话人分离或声道分离时，Oracle Mini 会自动启用时间戳对齐。

API 端点

POST /upload

上传本地音频或视频，并使用返回的 fileUrl 作为 audio_url 用于 POST /transcribe。小文件请选择内联 Base64 上传，较大文件请选择直接上传到存储。

内联 Base64 上传（最大 4 MiB）

对于不超过以下大小的文件： 4 MiB（4,194,304 字节），在一个 API 请求中以 Base64 形式发送媒体字节。

POST /upload
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "filename": "clip.mp3",
  "contentType": "audio/mpeg",
  "content": "<base64-encoded media bytes>"
}

contentType 为可选项；省略时会根据文件名推断。请在以下字段中发送原始 Base64 媒体字节： content，不要包含 data:...;base64, 前缀。4 MiB 限制适用于解码后的媒体文件。

响应包含 fileUrl。请将其用作 audio_url 创建转写任务时使用。

直接上传到存储（最大 100 MiB）

对于较大的文件，请为我们的 S3 兼容存储请求签名表单，直接上传文件，然后创建转写任务。最大上传大小： 100 MiB（104,857,600 字节）。签名表单的有效期为 60 分钟。返回的读取 URL 有效期为 24 小时，足以让转写服务获取媒体。

1. 请求签名上传表单

POST /upload
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "filename": "meeting.mp3",
  "contentType": "audio/mpeg"
}

contentType 为可选项；省略时会根据文件名推断。API 会返回 uploadUrl, uploadFields, fileUrl，以及 uploadExpiresIn.

使用 uploadUrl 将文件上传到我们的 S3 兼容存储。然后使用 fileUrl 作为 audio_url 创建转写任务时使用。

2. 将文件直接上传到存储

// upload is the JSON response from POST /upload
const form = new FormData();
for (const [name, value] of Object.entries(upload.uploadFields)) {
  form.append(name, value);
}
form.append('file', file, file.name);
await fetch(upload.uploadUrl, { method: 'POST', body: form });

请严格按返回内容提交这些字段，不要为存储 POST 添加自定义授权标头。

3. 创建转写任务

POST /transcribe
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "audio_url": "<fileUrl returned by POST /upload>",
  "model": "oracle"
}

POST /transcribe

提交音频文件进行异步转写，可选择启用说话人分离。

请求正文参数

参数	类型	必填	说明
audio_url	string	必填	要转写的音频或视频文件的公开访问 URL。
language	string	可选	语言代码提示（例如“he”“en”“es”）。如未提供，将自动检测语言。 Default: "auto"
translate_to	string	可选	要将转写翻译成目标语言，请提供其语言代码（例如“en”“es”“fr”）。提供后，输出文本将使用指定语言。注意：此参数仅适用于 Oracle 模型系列。
word_timestamps	boolean	可选	当所选模型支持词级对齐时，是否在 JSON 或 SRT 中包含词级时间戳。Oracle Mini 会自动为说话人分离和声道分离启用对齐；普通 Oracle Mini 转录返回片段级时间戳。不会影响 TXT 输出。默认值：true
model	string	可选	指定要使用的转写模型：当前模型： • `base`：低成本转写，含词级时间戳和可选说话人分离，0.40 额度/小时 • `oracle_mini`：价格最低的 Oracle 翻译层级，可选说话人处理，每小时 0.80 个用量额度 • `oracle`：生产级 Oracle 层级，1.20 额度/小时 • `oracle_pro`：高级 Oracle 层级，1.40 额度/小时 • `oracle_max`：最高质量的 Oracle 层级，3.00 额度/小时旧版模型： • `core`：速度更快的旧版模型，1.00 额度/小时 • `edge`：准确率更高的旧版模型，1.20 额度/小时 Default: "core"
output_format	string	可选	转写输出所需的格式： • `json`：包含分段和时间戳的详细输出 • `txt`：纯文本转写 • `srt`：SubRip 字幕格式 Default: "json"
include_diarization	boolean	可选	是否启用说话人分离（识别音频中的不同说话人）。启用后，片段将包含说话人标签。Oracle Mini 会自动为此模式启用时间戳对齐。默认值：false
pro_diarization	boolean	可选	启用高级说话人分离模型以获得更高准确度，尤其适用于复杂音频。每音频小时增加 0.20 积分。Oracle Mini 会自动为此模式启用时间戳对齐。默认值：false
num_speakers	integer	可选	音频中的预期说话人数。仅当 `include_diarization` 为 true 时使用。如未指定，系统将自动检测说话人数。默认值：auto
channel_speaker_separation	string	可选	分离立体声或多声道 `audio_url` 按实际音轨进行分离。请使用 `standard` 处理轮流发言的说话人，或使用 `overlap` 用于重叠语音。不能与说话人分离同时使用。Oracle Mini 会自动为任一声道模式启用时间戳对齐。 Default: "off"
channel_labels	object	可选	可选的从零开始的声道索引映射，例如 `{"0":"Agent","1":"Customer"}`。每个分段和词都会返回标签。
webhook_url	string	可选	接收转写任务完成或失败时 POST 请求的公开 HTTPS URL。请返回任意 `2xx` 状态码以确认投递。
webhook_secret	string	可选	用于签署 Webhook 载荷的可选密钥。签名标头格式为 `sha256=<hex digest>`.

请求示例（含说话人分离）：

{
  "audio_url": "https://salford.figshare.com/ndownloader/files/14630270",
  "word_timestamps": true,
  "model": "edge",
  "output_format": "json",
  "include_diarization": true,
  "num_speakers": 2
}

响应：

返回一个包含所提交转写任务 `jobId` 的对象。

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57"
}

GET /transcribe/{jobId}

检索指定转写任务的状态和结果。

路径参数

参数	类型	必填	说明
jobId	string	必填	转写任务 ID，从 POST /transcribe 响应中获取。

响应正文

字段	类型	说明
jobId	string	请求的转写任务 ID。
status	string	当前任务状态： PENDING, IN_PROGRESS, COMPLETED，或 FAILED
result	object \| string	转写输出（仅当状态为 COMPLETED 时存在）。其结构取决于请求的 output_format。
error	string	错误消息（仅当状态为 FAILED 时存在）。

响应示例（含说话人分离的 JSON 输出）：

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "result": {
    "language": "en",
    "segments": [
      {
        "start": 0.5,
        "end": 3.2,
        "text": "Hello everyone, welcome to today's meeting.",
        "speaker": "Speaker 1",
        "words": [
          {
            "start": 0.5,
            "end": 0.8,
            "word": "Hello"
          },
          {
            "start": 0.9,
            "end": 1.4,
            "word": "everyone"
          }
        ]
      },
      {
        "start": 4.1,
        "end": 6.8,
        "text": "Thank you. Let's begin with the quarterly review.",
        "speaker": "Speaker 2",
        "words": [
          {
            "start": 4.1,
            "end": 4.5,
            "word": "Thank"
          },
          {
            "start": 4.6,
            "end": 4.9,
            "word": "you"
          }
        ]
      }
    ]
  }
}

说话人分离

说话人分离是识别并区分音频录音中不同说话人的过程。启用后，KolWrite 会分析音频，检测说话人切换，并相应标记每个分段。

所有列出的模型均支持说话人分离和声道分离。每次选择说话人模式时，Oracle Mini 都会自动启用时间戳对齐。

如何启用说话人分离

要启用说话人分离，请在转写请求中将 include_diarization 参数设为 true 即可：

{
  "audio_url": "https://example.com/meeting-audio.mp3",
  "include_diarization": true,
  "num_speakers": 3
}

说话人数优化

为获得最佳结果，请使用 num_speakers 参数指定预期说话人数。如果您不知道确切人数，可以：

省略此参数（系统将自动检测）
根据您的最佳估计设置范围

Pro 说话人分离

如需提高说话人识别准确率，尤其是在声学条件复杂时，可启用 Pro 说话人分离。此功能需额外支付 每音频小时 0.20 额度.

要使用此功能，请将 pro_diarization 参数设为 true。此参数可与以下参数结合使用： include_diarization.

{
  "audio_url": "https://example.com/panel-discussion.mp3",
  "include_diarization": true,
  "pro_diarization": true
}

声道说话人分离

声道分离会分别转写每条实际音轨，并为返回的分段和词标注其实际声道字段 channel 以及 speaker。它需要在以下参数中指定一个双至八声道音频源： audio_url 且不能与常规或 Pro 说话人分离同时使用。Oracle Mini 会自动为任一声道模式启用时间戳对齐。

使用 standard 处理说话人轮流发言；收取一次所选模型的音频费率。请使用 overlap 处理说话人重叠发言；按所选模型费率计费，按录音时长与其各物理声道中检测到的语音总时长中的较大者计算。

{
  "audio_url": "https://example.com/stereo-call.wav",
  "model": "oracle",
  "channel_speaker_separation": "overlap",
  "channel_labels": {"0": "Agent", "1": "Customer"}
}

完成 Webhook

设置 webhook_url 以接收 transcription.completed 以及 transcription.failed 事件。投递失败时会重试，但客户端仍应支持 GET /transcribe/{jobId} 作为权威依据。

{
  "audio_url": "https://example.com/meeting-audio.mp3",
  "output_format": "json",
  "webhook_url": "https://example.com/kolwrite-webhook",
  "webhook_secret": "replace-with-your-secret"
}

每次投递均包含 X-KolWrite-Event, X-KolWrite-Job-Id, X-KolWrite-Delivery-Id，以及 X-KolWrite-Timestamp。每次事件至少投递一次；重试会复用相同的投递 ID，因此请使用以下字段对事件去重： X-KolWrite-Delivery-Id。配置密钥后，请基于以下内容计算 HMAC-SHA256： timestamp + "." + raw_request_body 并与 X-KolWrite-Signature.

{
  "event": "transcription.completed",
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "createdAt": "2026-07-10T09:30:00+00:00",
  "model": "base",
  "output_format": "json",
  "result_available": true,
  "result_omitted": false,
  "result_size_bytes": 12480,
  "result": { "language": "en", "segments": [] }
}

对于 output_format: "json"，Webhook 的 result 字段为 JSON 对象。TXT 和 SRT 结果以字符串形式返回。

较大的结果可能会将 result_omitted 设为 true；请从以下位置获取完整结果： GET /transcribe/{jobId}。失败事件包含 error 字段。

含说话人分离的输出格式

启用说话人分离后，JSON 输出中的每个分段都会包含一个 speaker 字段，用于标识说话人（例如“Speaker 1”“Speaker 2”等）。

输出格式

JSON 格式

详细输出，包含分段、时间戳和可选词级数据。

TXT 格式

带说话人标签的纯文本转写（启用说话人分离时）。

SRT 格式

带时间戳的 SubRip 字幕格式，兼容视频播放器和字幕编辑器。

服务状态

请参阅公开的 KolWrite API 状态页面，查看实时可用性、正常运行时间历史记录和服务级别事件。

GET /health 无需 API 密钥，并返回当前 API、任务接收和转写处理状态。响应 200 表示服务正常运行或处于降级状态；响应 503 表示当前状态未知或不可用。两种响应都包含 JSON 状态详情。

GET /health/history?period=24h 返回精简的可用性历史记录。支持的时间段为 24h, 7d，以及 30d.

状态码

状态	说明
PENDING	任务正在队列中等待处理。
IN_PROGRESS	我们的转写服务正在处理此任务。
COMPLETED	任务已成功完成。结果可在响应中查看。
FAILED	任务处理失败。请查看错误消息了解详情。

KolWrite API 文档