浏览文档目录

异步转写 API

提交录音任务,查询处理进度,并分页获取转写结果。

在 API 控制台 创建 API Key,通过 Authorization: Bearer <API_KEY> 请求头认证。运行示例前,在服务端环境中设置 LECSYNC_API_KEY。API Key 应保存在服务端。

1. 提交录音

支持 AAC(ADTS)、MP3、Ogg Opus、WAV,以及含音轨的 MP4 文件。

bash
curl "https://api.lecsync.com/v1/audio/transcription-jobs" \  -H "Authorization: Bearer $LECSYNC_API_KEY" \  -H "Idempotency-Key: job-example-001" \  -H "Content-Type: application/json" \  -d '{  "input": {    "file_url": "https://example.com/recording.mp3"  },  "language": "en",  "timestamps": "none",  "diarization": false}'

创建成功返回 HTTP 202 和 job_id,表示任务已接收,转写尚未完成。

以下示例展示主要响应字段,实际响应还可能包含用量元数据。

json
{  "job_id": "req_example",  "request_id": "req_example",  "status": "accepted",  "progress": 0,  "result_url": "/v1/audio/transcription-jobs/req_example/result"}

请求参数

字段类型必填说明
input.file_urlstring二选一可直接访问的 HTTPS 音频地址,无需额外请求头。与 input.upload_id 二选一。
input.upload_idstring二选一上传接口返回的文件标识,与 input.file_url 二选一。
modelstring否可选模型标识,默认使用表中列出的值。 stt-async-default.
languagestring否音频语言代码,例如 zh、en;默认 auto,自动识别。
timestampsstring否none(默认)、segment 或 word。word 同时返回词级和段级时间戳。GPU 转录仅支持 none 且 diarization=false;其他组合需要运营方允许 Soniox 回退,否则请求以 CAPABILITY_UNAVAILABLE 失败。
diarizationboolean否是否返回说话人标签,默认 false。
hotwordsstring[]否识别提示词,最多 50 项,每项最多 120 个 Unicode 字符。
webhook_idstring否通过 POST /v1/webhooks 注册的回调地址标识。

2. 查询任务状态

bash
curl "https://api.lecsync.com/v1/audio/transcription-jobs/JOB_ID" \  -H "Authorization: Bearer $LECSYNC_API_KEY"

建议每隔 3 秒查询一次。status 为 accepted 或 processing 时继续等待,succeeded 时读取结果。failed 或 cancelled 表示任务已结束,可通过 error 查看原因。progress 为 0–100 的估算进度。

字段说明
statusaccepted、processing、succeeded、failed 或 cancelled。
result_expires_atISO 8601 格式的结果到期时间;结果尚未生成时可为 null。

3. 读取结果

bash
curl "https://api.lecsync.com/v1/audio/transcription-jobs/JOB_ID/result?cursor=0" \  -H "Authorization: Bearer $LECSYNC_API_KEY"

从 cursor=0 开始,使用响应中的 next_cursor 读取下一页,直到其为 null。按页顺序拼接 result.text,并分别合并 words、segments 数组。文本与时间戳列表独立分页。任务完成前读取结果返回 409 RESULT_NOT_READY。

json
{  "job_id": "req_example",  "request_id": "req_example",  "language": "en",  "result": {    "text": "Hello world."  },  "cursor": 0,  "next_cursor": null,  "page_count": 1}

时间戳单位为毫秒,从录音起点计算。开启说话人识别后,时间戳条目可包含 speaker。词列表不单列标点,完整转写文本保留标点。

结果默认保留 7 天,具体以 result_expires_at 为准。到期后返回 410 RESULT_EXPIRED。

上传本地文件

本地文件先申请上传地址,请求中填写准确的字节数和小写十六进制 SHA-256。响应包含 upload_id、upload_url、headers、expires_at。使用全部返回的请求头,将文件 PUT 到 upload_url,然后在 15 分钟内用 input.upload_id 创建任务。向上传地址发送文件时,无需附带 API Key。下面的完整示例需要 curl、jq 和 shasum。

bash
FILE=recording.wavSIZE=$(wc -c < "$FILE" | tr -d ' ')SHA256=$(shasum -a 256 "$FILE" | cut -d ' ' -f 1)UPLOAD=$(curl --fail-with-body "https://api.lecsync.com/v1/audio/uploads" \  -H "Authorization: Bearer $LECSYNC_API_KEY" \  -H "Idempotency-Key: upload-example-001" \  -H "Content-Type: application/json" \  -d "{\"size_bytes\":$SIZE,\"sha256\":\"$SHA256\"}")
curl --fail-with-body -X PUT "$(printf '%s' "$UPLOAD" | jq -r '.upload_url')" \  -H "Content-Type: $(printf '%s' "$UPLOAD" | jq -r '.headers["content-type"]')" \  -H "Content-Length: $(printf '%s' "$UPLOAD" | jq -r '.headers["content-length"]')" \  -H "x-amz-checksum-sha256: $(printf '%s' "$UPLOAD" | jq -r '.headers["x-amz-checksum-sha256"]')" \  --data-binary "@$FILE"
UPLOAD_ID=$(printf '%s' "$UPLOAD" | jq -r '.upload_id')curl "https://api.lecsync.com/v1/audio/transcription-jobs" \  -H "Authorization: Bearer $LECSYNC_API_KEY" \  -H "Idempotency-Key: uploaded-job-example-001" \  -H "Content-Type: application/json" \  -d "{\"input\":{\"upload_id\":\"$UPLOAD_ID\"},\"timestamps\":\"none\"}"

取消或删除任务

POST /v1/audio/transcription-jobs/{job_id}/cancel 发起取消。继续查询状态,直到任务结束;如有退款,会在处理停止后完成。DELETE /v1/audio/transcription-jobs/{job_id} 立即移除结果访问权限,删除后查询返回 404。

bash
curl -X POST "https://api.lecsync.com/v1/audio/transcription-jobs/JOB_ID/cancel" \  -H "Authorization: Bearer $LECSYNC_API_KEY"
curl -X DELETE "https://api.lecsync.com/v1/audio/transcription-jobs/JOB_ID" \  -H "Authorization: Bearer $LECSYNC_API_KEY"

完成通知

注册可公网访问的 HTTPS 回调地址,保存返回的 secret,创建任务时传入 webhook_id。事件类型为 transcription.succeeded、transcription.failed 或 transcription.cancelled,包含 job_id、status、result_url,不含转写正文。

bash
curl "https://api.lecsync.com/v1/webhooks" \  -H "Authorization: Bearer $LECSYNC_API_KEY" \  -H "Idempotency-Key: webhook-example-001" \  -H "Content-Type: application/json" \  -d '{  "url": "https://example.com/webhooks/transcription"}'

用 secret 对 LecSync-Timestamp + "." + 原始请求体 计算 HMAC-SHA256,核对 LecSync-Signature 中的 v1=<hex>。拒绝与当前时间相差超过 5 分钟的请求,按 LecSync-Event-Id 去重。密钥轮换后,通过 LecSync-Secret-Version 选择验签密钥。接收成功请返回 2xx。网络错误、429、5xx 会在 24 小时内重试,其他 4xx 停止投递。

通过 GET /v1/webhooks/{id}/deliveries 查看投递记录,POST /v1/webhooks/deliveries/{id}/resend 重发通知,POST /v1/webhooks/{id}/rotate-secret 轮换密钥。重发和轮换请求需要各自的 Idempotency-Key。

结果查询与重试

每次新调用传入 Idempotency-Key,值为 1–128 个可见 ASCII 字符。保存该键;响应丢失时,使用相同键和相同参数重试。同键不同参数返回 409 IDEMPOTENCY_CONFLICT。请求仍在处理时,重复调用只返回已有状态。使用新键会创建新请求。

限制与用量

  • 文件大小上限: 200 MiB
  • 音频时长上限: 7200 s

按音频实际时长计量,不向上取整到整分钟。

usage.charge_cents 为本次费用,以美分十进制字符串表示。

通过 GET /v1/models 查询当前可用的模型、语言、限制、价格及结果保留时长。

错误处理

HTTP 错误响应包含 error、request_id,响应头中也有 X-Request-Id。排查问题时请提供该标识。

json
{  "error": "INVALID_INPUT",  "request_id": "req_example"}
HTTPerror处理方式
401UNAUTHORIZED检查 API Key 是否有效。
402INSUFFICIENT_BALANCE检查 API 余额后重试。
503ADMISSION_DISABLED当前账号暂不可使用该服务。
409IDEMPOTENCY_CONFLICT查询已有请求;不同输入请使用新键。
410RESULT_EXPIRED结果已过期,需要时重新提交。
413BODY_TOO_LARGE / AUDIO_TOO_LONG缩小文件或缩短音频。
415UNSUPPORTED_AUDIO_FORMAT转换为支持的音频格式。
422INVALID_INPUT / INVALID_IDEMPOTENCY_KEY / PARAMETER_CONFLICT / CAPABILITY_UNAVAILABLE检查字段名称、类型及必填参数。
422UNSUPPORTED_LANGUAGE检查字段名称、类型及必填参数。
429RESOURCE_LIMIT按 Retry-After 等待后重试。
503MODEL_UNAVAILABLE / SERVICE_UNAVAILABLE查询已有请求状态,再决定是否重试。
504DEADLINE_EXCEEDED先查询请求状态,再决定是否新建请求。