浏览文档目录

同步转写 API

上传短音频,在同一次 HTTP 响应中取得转写结果。

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

发起请求

POST /v1/audio/transcriptions

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

bash
curl "https://api.lecsync.com/v1/audio/transcriptions" \  -H "Authorization: Bearer $LECSYNC_API_KEY" \  -H "Idempotency-Key: transcription-example-001" \  -F "file=@recording.wav" \  -F "language=en" \  -F "timestamps=none" \  -F "diarization=false" \  -F 'hotwords=["LecSync"]'

请求参数

使用 multipart/form-data,由 HTTP 客户端生成 boundary。表单中的 hotwords、terms 以 JSON 字符串传入,布尔字段使用 true 或 false。

字段类型必填说明
filefile是音频文件。
modelstring否可选模型标识,默认使用表中列出的值。 stt-sync-default.
languagestring否音频语言代码,例如 zh、en;默认 auto,自动识别。
timestampsstring否none(默认)、segment 或 word。word 同时返回词级和段级时间戳。GPU 转录仅支持 none 且 diarization=false;其他组合需要运营方允许 Soniox 回退,否则请求以 CAPABILITY_UNAVAILABLE 失败。
diarizationboolean否是否返回说话人标签,默认 false。
hotwordsstring[]否识别提示词,最多 50 项,每项最多 120 个 Unicode 字符。

响应

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

json
{  "request_id": "req_example",  "status": "succeeded",  "model": "stt-sync-default",  "text": "Hello world.",  "language": "en"}
字段说明
request_id请求标识,用于查询状态和排查问题,请保存。
statusaccepted、processing、succeeded、failed 或 cancelled。
text完整转写文本。
language识别到的语言;无法确定时为 null。
segments段落列表,每项包含 text、start_ms、end_ms。
words词列表,每项包含 text、start_ms、end_ms;timestamps=word 时返回。
result_expires_atISO 8601 格式的结果到期时间;结果尚未生成时可为 null。

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

结果查询与重试

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

成功结果默认保留 24 小时。通过 GET /v1/requests/{request_id} 查询,保存的正文位于 result 字段中;重复提交已成功的 POST 也使用这一结构。到期后返回 410 RESULT_EXPIRED,具体到期时间以 result_expires_at 为准。

bash
curl "https://api.lecsync.com/v1/requests/REQUEST_ID" \  -H "Authorization: Bearer $LECSYNC_API_KEY"

限制与用量

  • 文件大小上限: 20 MiB
  • 音频时长上限: 120 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先查询请求状态,再决定是否新建请求。