將字幕翻譯
整合至你的工作流程。

快速開始

建立金鑰後，下載 Node.js 範例。它會估算費用、提交任務、輪詢狀態，並儲存翻譯後的 SRT。需要 Node.js 20 或更新版本，無須安裝其他套件。

export AST_BASE_URL='https://your-website-origin'
export AST_API_KEY='ast_YOUR_API_KEY'
node translate-subtitle.mjs input.srt zh plus translated.srt my-job-001
# 在最後加上 true 參數可下載雙語字幕：
node translate-subtitle.mjs input.srt zh plus bilingual.srt my-job-001 true

將基底 URL 替換為本站網址，並將下載的指令碼放在 SRT 檔案旁。必須明確選擇 basic 或 plus。網路故障後重試時，請沿用相同的任務鍵、輸入內容與選項。使用相同任務鍵再次下載會沿用既有翻譯；請選擇尚不存在的輸出檔名。

身分驗證

開啟控制台 → 安全設定 → API 金鑰。為金鑰命名並建立，之後可隨時重新檢視和複製完整金鑰，也可在同一頁面撤銷。

Authorization: Bearer ast_YOUR_API_KEY

以本站網址作為基底 URL。全部 6 個端點皆需要有效金鑰。每個帳戶最多可有 5 個有效金鑰。API 金鑰可存取該帳戶透過 API 建立的翻譯任務及積分餘額。

請使用你自己帳戶的金鑰，妥善保管，不要將共用金鑰打包進發佈的外掛程式。端點不接受 Cookie 身分驗證，也不接受 URL 查詢參數中的金鑰。

六個端點

JSON 成功回應將結果放在 { "data": ... } 中。成功下載翻譯結果時，回應一律為 SRT。

估算與提交

兩個 POST 端點接受相同的 JSON 請求本文。請傳送 Content-Type: application/json。

{
  "fileName": "interview.srt",
  "subtitle": "1\n00:00:01,000 --> 00:00:03,000\nHello!\n",
  "targetLanguage": "zh",
  "modelTier": "plus"
}

subtitle、targetLanguage 與 modelTier 為必填欄位。必須明確選擇 basic 或 plus；省略 modelTier 會回傳 400 INVALID_REQUEST。來源語言會自動偵測。目標語言代碼可從 /api/v1/capabilities 取得。

選填的 glossary 項目包含 source 與 target。選填的 characters 項目還可包含 gender（male 或 female）及 aliases（別名列表）。確切的資料結構請參閱 OpenAPI 規格。未知欄位會被拒絕。

先向 /api/v1/translations/estimate 傳送 POST 請求。回應包含 creditCost、availableCredits、sufficientCredits 與字幕條目數量。估算不會建立任務或預留積分。

建立任務

curl "$AST_BASE_URL/api/v1/translations" \
  -H "Authorization: Bearer $AST_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: premiere-sequence-123-zh-v1' \
  --data-binary @request.json

將 JSON 請求本文儲存為 request.json。將兩個環境變數分別設為本站網址與你的 API 金鑰。

新任務回傳 202 Accepted，包含 data.id、data.creditCost、data.statusUrl 與 data.resultUrl。Location 回應標頭指向任務狀態端點。

{
  "data": {
    "id": "6f476119-c02f-49a9-b61f-2b3327bd318c",
    "status": "pending",
    "fileName": "interview.srt",
    "modelTier": "plus",
    "targetLanguage": "zh",
    "creditCost": "1.00",
    "statusUrl": "/api/v1/translations/6f476119-c02f-49a9-b61f-2b3327bd318c",
    "resultUrl": "/api/v1/translations/6f476119-c02f-49a9-b61f-2b3327bd318c/result"
  }
}

每次預計執行的新翻譯都應產生一個 Idempotency-Key，重試時保持不變。相同請求會回傳同一任務，HTTP 狀態碼為 200。使用同一鍵傳送不同請求本文會回傳 409。冪等鍵屬於帳戶，更換 API 金鑰後仍有效。

此請求標頭允許 1–128 個字母、數字、點、底線、冒號或連字號。重複請求所對應的任務若已過期或刪除，會回傳 410。只有在確定要建立另一個計費任務時，才使用新鍵。

進度與結果

每隔5 秒輪詢一次狀態 URL。狀態為 pending、processing、completed 或 failed。progress 為百分比，無法取得時為 null；errorCode 說明任務失敗原因。

curl --fail "$AST_BASE_URL/api/v1/translations/$TASK_ID" \
  -H "Authorization: Bearer $AST_API_KEY"

將 TASK_ID 設為提交回應中的 data.id。進度回應包含上述任務欄位，以及 progress 和 errorCode，這兩項皆可能為 null。狀態為 failed 時應停止輪詢並顯示錯誤。只有確定要重新翻譯時，才使用新任務鍵。

完成後，向結果 URL 傳送 GET 請求，將回應文字儲存為 SRT 檔案。回應類型為 application/x-subrip; charset=utf-8。省略 includeOriginal 或將其設為 false 時僅回傳譯文。加上 ?includeOriginal=true 可取得雙語字幕，每條字幕先顯示原文，再顯示譯文。

curl --fail "$AST_BASE_URL/api/v1/translations/$TASK_ID/result?includeOriginal=true" \
  -H "Authorization: Bearer $AST_API_KEY" \
  --output translated-bilingual.srt

不支援 format 參數，傳入會回傳 400 INVALID_REQUEST。錯誤回應為 JSON。過早請求結果會回傳 409 TRANSLATION_NOT_READY，並附上 Retry-After: 5。翻譯失敗時回傳 409 TRANSLATION_FAILED。

請及時下載已完成的結果。網站的刪除與保留規則也適用於 API 任務。任務不存在或無權存取時回傳 404。API 任務也會顯示在你的字幕歷史紀錄中。

積分與限制

API 翻譯使用帳戶現有積分，並遵循網站的模型等級定價與最低扣費規則，沒有額外的 API 附加費。請為每個檔案呼叫估算端點；估算不會鎖定價格。任務被接受後的 creditCost 即為預留積分數量。

任務等待或處理中會預留積分，成功完成後只計費一次。即使排隊期間超過積分原有效期限，已預留積分仍可用於該任務。任務失敗或刪除後會釋放預留：未過期積分恢復為可用餘額，已過期積分不會恢復有效。失敗任務不收取翻譯費用。餘額端點以十進位字串回傳 availableCredits、reservedCredits 與 totalCredits（可用積分加預留積分）。

{ "data": { "availableCredits": "9.00", "reservedCredits": "1.00", "totalCredits": "10.00" } }

• 每個帳戶每 60 秒視窗最多 60 次請求，所有金鑰共用配額。
• 每個視窗最多 10 次 POST 請求，估算與提交共用配額。
• 最多同時有 3 個等待或處理中的 API 任務。
• 每個任務只能提交一個檔案與一種目標語言。
• UTF-8 字幕文字最大 1 MiB；JSON 請求本文最大 2 MiB；最多 5,000 條字幕。
• 單條字幕的文字長度遵循網站設定，預設最多 500 個字元。
• 最多 200 個術語項目、100 個角色，每個角色最多 20 個別名。術語與名稱最多 200 個字元。

從 /api/v1/capabilities 取得目前限制。回應包含 X-RateLimit-Limit、X-RateLimit-Remaining 與 X-RateLimit-Reset（Unix 秒時間戳記）。收到 429 回應時，請遵循 Retry-After。翻譯完成時間取決於佇列與輸入內容。

錯誤與重試

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Your account does not have enough available credits."
  },
  "requestId": "..."
}

400：輸入無效。401：金鑰無效或已撤銷。402：積分不足。404：任務不存在或無權存取。409：冪等鍵衝突、翻譯未完成或失敗。410：重複請求所對應的任務已過期。413：輸入過大。415：需要 JSON。422：字幕被拒絕。429：超過請求次數或進行中任務限制。502：結果不完整。503：服務、模型或佇列無法使用。

遇到網路錯誤或暫時性伺服器故障時，請使用相同的 Idempotency-Key 與請求本文重試。若回應包含 Retry-After，請等待指定時間。翻譯任務進入最終失敗狀態後，如需重新翻譯，應使用新鍵。聯絡支援時請提供 X-Request-Id 與任務 ID。

Premiere Pro 工作流程

1. 選擇或匯出 SRT 檔案。
2. 估算費用，並使用選定的目標語言提交任務。
3. 顯示任務進度，然後儲存翻譯後的 SRT。
4. 將檔案匯入 Premiere，並放到字幕軌道上。

在 UXP 資訊清單的網路權限中宣告本站網址，並為 SRT 讀寫申請檔案存取權限。公開端點支援使用 Bearer 身分驗證的 CORS 請求，無須 Cookie。

使用帶編號的 SRT 字幕條目，時間戳記格式為 HH:MM:SS,mmm，文字不可為空，條目之間以空白行分隔。既有字幕清理規則仍適用：會移除格式標籤、重新編號，並可能篩除重疊的次要疊加文字。保留條目的時間戳記不會改變。SRT 不保留 Premiere 的樣式。

自動存取既有字幕軌道的能力需要針對你的 Premiere 版本另行驗證。API 接受字幕文字；提交音訊內容前，請先將其轉錄為字幕。