瀏覽文件目錄

同步轉寫 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先查詢請求狀態,再決定是否建立新請求。