瀏覽文件目錄

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