文字翻譯 API
將一段文字翻譯為目標語言,支援背景資訊和術語表。
在 API 控制台 建立 API Key,透過 Authorization: Bearer <API_KEY> 標頭驗證。執行範例前,在伺服器環境設定 LECSYNC_API_KEY。API Key 應保存在伺服器端。
發起請求
POST /v1/translate
請求參數
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
text | string | 是 | 非空文字字串,最多 2,000 個 Unicode 字元。 |
target_lang | string | 是 | 目標語言代碼,例如 zh、en、ja。 |
source_lang | string | 否 | 來源語言,預設 auto。短文字或含義不明確時建議指定。 |
context | string | 否 | 背景資訊,最多 2,000 個 Unicode 字元。 |
terms | object[] | 否 | 最多 20 對 {source, target} 術語,每側最多 120 個 Unicode 字元。 |
model | string | 否 | 可選模型識別碼,預設使用表中列出的值。 translate-default. |
回應
以下範例展示主要回應欄位,實際回應還可能包含用量中繼資料。
| 欄位 | 說明 |
|---|---|
request_id | 請求識別碼,用於查詢狀態與排查問題,請保存。 |
status | accepted、processing、succeeded、failed 或 cancelled。 |
text | 翻譯後的文字。 |
source_lang | 來源語言,預設 auto。短文字或含義不明確時建議指定。 |
target_lang | 目標語言代碼,例如 zh、en、ja。 |
unchanged | 來源與目標語言相同時為 true,text 原樣回傳。 |
result_expires_at | ISO 8601 格式的結果到期時間;結果尚未產生時可為 null。 |
結果查詢與重試
每次新呼叫傳入 Idempotency-Key,值為 1–128 個可見 ASCII 字元。保存此鍵;回應遺失時,使用相同鍵與相同參數重試。同鍵不同參數回傳 409 IDEMPOTENCY_CONFLICT。請求仍在處理時,重複呼叫只回傳既有狀態。使用新鍵會建立新請求。
成功結果預設保留 24 小時。透過 GET /v1/requests/{request_id} 查詢,保存的正文位於 result 欄位;重複提交已成功的 POST 也使用此結構。到期後回傳 410 RESULT_EXPIRED,實際到期時間以 result_expires_at 為準。
限制與用量
依來源文字字元數計量,背景資訊和術語不計入用量。同語言請求仍依來源文字計量。
usage.charge_cents 為本次費用,以美分十進位字串表示。
透過 GET /v1/models 查詢目前可用的模型、語言、限制、價格及結果保留時間。
錯誤處理
HTTP 錯誤回應包含 error、request_id,回應標頭也有 X-Request-Id。排查問題時請提供此識別碼。
| HTTP | error | 處理方式 |
|---|---|---|
| 401 | UNAUTHORIZED | 檢查 API Key 是否有效。 |
| 402 | INSUFFICIENT_BALANCE | 檢查 API 餘額後重試。 |
| 503 | ADMISSION_DISABLED | 目前帳號暫不可使用此服務。 |
| 409 | IDEMPOTENCY_CONFLICT | 查詢既有請求;不同輸入請使用新鍵。 |
| 410 | RESULT_EXPIRED | 結果已到期,需要時重新提交。 |
| 422 | INVALID_INPUT / INVALID_IDEMPOTENCY_KEY / PARAMETER_CONFLICT / CAPABILITY_UNAVAILABLE | 檢查欄位名稱、類型與必填參數。 |
| 422 | UNSUPPORTED_LANGUAGE / LANGUAGE_UNDETERMINED | 使用支援的語言;自動偵測失敗時指定 source_lang。 |
| 429 | RESOURCE_LIMIT | 依 Retry-After 等待後重試。 |
| 503 | MODEL_UNAVAILABLE / SERVICE_UNAVAILABLE | 查詢既有請求狀態,再決定是否重試。 |
| 504 | DEADLINE_EXCEEDED | 先查詢請求狀態,再決定是否建立新請求。 |