台語翻譯 API

1. 送出翻譯

先設定環境變數 EZTRANSLATE_API_KEY。以下 Bash 範例用 uuidgen 產生一次重試識別碼；若請求需要重送，請沿用這個值。

REQUEST_ID="$(uuidgen)"

curl -i "https://eztranslate.com.tw/api/v1/hokkien/translations" \
  -H "Authorization: Bearer $EZTRANSLATE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $REQUEST_ID" \
  --data '{"text":"今天天氣很好。","audio":false}'

欄位或標頭	必填	說明
Idempotency-Key	是	UUID；同帳戶同一份工作重試時沿用
text	是	去除頭尾空白後，1–2,000 個 Unicode 字元的中文文字
audio	否	布林值，預設 false；設為 true 會產生所有語音片段

使用 UTF-8 JSON，不支援未知欄位。v1 接受文字輸入，不接受麥克風錄音。

接受後回傳 202 Accepted，Location 是狀態查詢路徑。以下為回應格式範例：

{
  "id": "7c89cba9-6463-4424-9bb2-f76f0d4f0045",
  "statusUrl": "/api/v1/hokkien/translations/7c89cba9-6463-4424-9bb2-f76f0d4f0045",
  "status": "queued",
  "creditCost": 1,
  "refundedCredits": 0,
  "refundPending": false,
  "result": null,
  "error": null,
  "createdAt": "2026-10-26T00:00:00.000Z",
  "completedAt": null,
  "expiresAt": null,
  "resultExpired": false
}

2. 查詢進度與文字

將 JOB_ID 設為接受回應中的 id：

curl "https://eztranslate.com.tw/api/v1/hokkien/translations/$JOB_ID" \
  -H "Authorization: Bearer $EZTRANSLATE_API_KEY"

status 會是 queued、processing、completed 或 failed。尚未完成時，依照 Retry-After 等待後再查詢。

完成後，result 包含以下欄位：

欄位	說明
hanji	台語漢字
tailo	台羅拼音
poj	白話字
spokenCharacterCount	台語漢字輸出的 Unicode 字元數，不影響計費
audioUrls	依播放順序排列的語音下載路徑；未要求語音時為空陣列

輸入最多 2,000 字，輸出最多 3,000 字。僅使用 Plus 點數，依去除頭尾空白後的輸入長度計費，每 500 個 Unicode 字元 1 點，最低 1 點、最高 4 點。接受工作時一次扣足，譯文與台語發音不另收費；Plus 餘額不足時不會建立工作或扣點。詳細規則見 點數計費。

3. 下載語音

若送出時指定 audio: true，工作完成後再依序下載 audioUrls。所有片段都準備好才會顯示完成。

curl "https://eztranslate.com.tw/api/v1/hokkien/translations/$JOB_ID/audio/0" \
  -H "Authorization: Bearer $EZTRANSLATE_API_KEY" \
  --output speech-0.wav

語音是 WAV 檔，每個下載請求都需要金鑰。若有多個片段，請按陣列順序播放；不要直接把多個 WAV 檔的位元組串接成一個檔案。

重試與保存

相同 Idempotency-Key 和相同內容會回到原工作：尚未完成回傳 202，完成或失敗回傳 200。不同內容會回傳 409。

內容可存取至 expiresAt，即完成或失敗後 7 天。到期後狀態仍可查詢，但 result 會是 null；下載或重送舊識別碼會收到 410。請自行保存需要長期使用的文字與語音。

遇到失敗或連線中斷時，依照 錯誤與重試 處理，避免重複建立翻譯。