瀏覽文件目錄

語音打字 API

語音打字:將短錄音轉為可填入輸入框、訊息或文件的文字。

適用於編輯器、聊天輸入框、表單與語音鍵盤。透過 HTTP 或 WebSocket 提交一段短語音,取得 text 後由呼叫方寫入目前輸入位置。介面負責產生文字,文字插入由用戶端實作。只做語音轉文字,原樣回傳辨識結果,不做潤飾、詞條替換或翻譯。WebSocket 在 end 後回傳最終文字,不提供逐字字幕。

在 API 控制台 建立 API Key,透過 Authorization: Bearer <API_KEY> 標頭驗證。執行範例前,在伺服器環境設定 LECSYNC_API_KEY。API Key 應保存在伺服器端。

發起請求

POST /v1/voicetyping

支援 AAC(ADTS)、MP3、Ogg Opus、WAV,不支援 MP4 與影片檔案。

bash
curl "https://api.lecsync.com/v1/voicetyping" \  -H "Authorization: Bearer $LECSYNC_API_KEY" \  -H "Idempotency-Key: voicetyping-example-001" \  -F "file=@recording.wav" \  -F "language=en" \  -F 'terms=["LecSync"]'

請求參數

使用 multipart/form-data,由 HTTP 用戶端產生 boundary。表單中的 hotwords、terms 以 JSON 字串傳入,布林欄位使用 true 或 false。

欄位類型必填說明
filefile是音訊檔案。
languagestring否音訊語言代碼,例如 zh、en;預設 auto,自動辨識。
termsarray否最多 50 個熱詞(字串,每個最多 120 字元),用於提高人名、術語的辨識準確率。

回應

以下範例展示主要回應欄位,實際回應還可能包含用量中繼資料。

json
{  "request_id": "req_example",  "status": "succeeded",  "text": "hello world",  "language": "en"}
欄位說明
request_id請求識別碼,用於查詢狀態與排查問題,請保存。
text辨識出的文字。
language辨識到的語言;無法確定時為 null。

WebSocket 接入

在伺服器端建立連線,使用與 HTTP 相同的 JSON 參數,不含 file。回應提供 websocket_url、protocol、ticket、expires_at 與 limits。請在票據有效期內(60 秒)建立連線,每張票據只能使用一次。

bash
curl "https://api.lecsync.com/v1/voicetyping/connect" \  -H "Authorization: Bearer $LECSYNC_API_KEY" \  -H "Idempotency-Key: voicetyping-ws-example-001" \  -H "Content-Type: application/json" \  -d '{  "language": "en",  "terms": [    "LecSync"  ]}'

以 [protocol, ticket] 作為 WebSocket 子協定。收到 ready 後,傳送 16 kHz、單聲道、小端 PCM16 二進位音訊,不含 WAV 標頭。每幀非空、位元組數為偶數且不超過 65,536。最後一幀後傳送 {"type":"end"},等待 result 或 error。結果在說話結束後一次回傳,不提供中間字幕。閒置逾時為 60 秒。

javascript
const ws = new WebSocket(connection.websocket_url, [  connection.protocol,  connection.ticket,]);ws.onmessage = ({ data }) => {  const message = JSON.parse(data);  if (message.type === "ready") {    // pcmFrames: 16 kHz mono PCM16 ArrayBuffer[]    for (const frame of pcmFrames) ws.send(frame);    ws.send(JSON.stringify({ type: "end" }));  } else if (message.type === "result") {    console.log(message.text);  } else if (message.type === "error") {    console.error(message.error);  }};

結果查詢與重試

每次新呼叫傳入 Idempotency-Key,值為 1–128 個可見 ASCII 字元。保存此鍵;回應遺失時,使用相同鍵與相同參數重試。同鍵不同參數回傳 409 IDEMPOTENCY_CONFLICT。請求仍在處理時,重複呼叫只回傳既有狀態。使用新鍵會建立新請求。

收到回應後請立即保存 text。語音打字正文不支援再次取得:GET /v1/voicetyping/requests/{request_id} 與重複請求只回傳狀態和用量,result_replay_supported=false。

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

限制與用量

  • 檔案大小上限: 20 MiB
  • 音訊時長上限: 120 s

依最終文字字元數計量,不計空白字元。

usage.charge_cents 為本次費用,以美分十進位字串表示。

錯誤處理

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