兩種端點類型

本服務以「路徑前綴」區分認證類型，您一眼就能從 URL 知道是否需要金鑰。

公開端點（無前綴）

不需金鑰，用於整合前查詢服務支援的語言、模型等資訊。可在前端直接呼叫，不會洩漏任何敏感資料。

• GET /translations/languages — 翻譯模組支援的語言清單。
• GET /translations/models — 翻譯模組可用模型清單。
• GET /audio/languages — 語音辨識模組支援的語言清單。

金鑰端點（/api/v1）

需在 HTTP Header 帶入 X-API-Key 才能存取。涵蓋核心業務操作：文字翻譯、語音辨識、字庫管理等。

• POST /api/v1/translations/text — 文字翻譯，可選擇是否串流。
• POST /api/v1/audio/transcriptions — 語音辨識，支援 Base64 與檔案上傳兩種輸入方式。
• /api/v1/dictionaries/* — 字庫管理（術語表、強制替換字庫、批次操作）。
• GET /api/v1/usage — 查詢當期帳戶與金鑰兩層用量百分比；不消耗額度。

共通回應結構

成功時回傳 data（payload）與 usage（用量）；失敗時回傳 error 物件，包含 code、message、details 與 request_id。每次呼叫都會帶 request_id，用於問題回報時對應到伺服器端紀錄。

您會反覆看到的常見上限

• 文字翻譯單次輸入上限 5000 字元；超過會回 400 validation_error。
• 語音辨識依上傳方式限制不同：JSON（Base64）路徑 raw 音訊 ≤ 1 MB（超過回 413 audio_too_long）；multipart 檔案上傳 ≤ 15 MB（超過回 413 file_too_large）。
• 字庫批次操作單次上限 250 筆。