30306 · 無效的 API 金鑰

確認金鑰是否完整複製（含 ft_ 前綴）。已刪除的金鑰同樣回傳這個碼。

30307 · 金鑰已停用

在開發者中心重新啟用，或改用另一把金鑰。

30308 · 金鑰已過期

把到期時間往後調，或建立新的金鑰。

30309 · 呼叫 IP 不在白名單內

把伺服器的對外 IP 加入該金鑰白名單，或直接清空白名單。

30312 · 金鑰遭管理員封鎖

請聯絡客服處理，這一項無法在開發者中心自行解除。

Belin Doc · 開放平台

翻譯 API 文件

Q: 30308 · 金鑰已過期

把到期時間往後調，或建立新的金鑰。

下列每個端點都是網頁端同名功能的開放版——一樣的模型、一樣的額度、一樣的成果，差別只在於用 API 金鑰取代登入狀態。

快速開始改用 MCP 接入

請求前綴: https://belindoc.com/api
驗證標頭: X-Api-Key
請求方式: POST · application/json
端點數: 21
更新於: 2026-09-04

開始使用

快速開始

從一份 PDF 到一份譯文，四步完成。影片翻譯的呼叫方式也一樣。

01
建立金鑰
登入 belindoc.com，點右上角頭像 → 開發者中心 → 新增金鑰。金鑰以 ft_ 開頭，完整值只在建立成功那一次顯示。

上傳檔案

先取得一個預簽上傳網址，再用 PUT 直接把檔案傳上去。網址 10 分鐘內有效，回傳的 objectKey 下一步會用到。

bash

# 1. 取得預簽名上傳位址（10 分鐘內有效）
curl -X POST https://belindoc.com/api/external/translate/batchPresignedUploadUrl \
  -H "X-Api-Key: $BELINDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileNameList": ["contract.pdf"]}'

# → data[0].persignedUploadUrl / data[0].objectKey

# 2. 用 PUT 將檔案直傳到該位址
curl -X PUT "<persignedUploadUrl>" --upload-file contract.pdf

送出翻譯

fileList、sourceLanguage、targetLanguage、model 為必填。來源語言傳 AnyLanguage 即自動偵測；模型名稱不要寫死，以 getModelList 回傳的為準。

bash

curl -X POST https://belindoc.com/api/external/translate/batchSubmitTranslateTask \
  -H "X-Api-Key: $BELINDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileList": [{ "fileName": "contract.pdf", "fileObjectKey": "<objectKey>" }],
    "sourceLanguage": "AnyLanguage",
    "targetLanguage": "zh-CN",
    "model": "Gemini-2.5-Flash"
  }'

# → { "code": "200", "data": { "batchNo": "...", "fileList": [ ... ] } }

輪詢並下載

以 batchNo 輪詢至 status 為 3，再取下載網址。該端點回傳的是 SSE 串流，連結在 [DONE] 事件中。

bash

# 輪詢任務：status = 3 表示譯文已就緒
curl -X POST https://belindoc.com/api/external/translate/searchTranslateFileByBatchNo \
  -H "X-Api-Key: $BELINDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"batchNo": "<batchNo>"}'

# 取譯文下載位址：SSE 回應，下載連結在 [DONE] 事件裡
curl -N -X POST https://belindoc.com/api/external/translate/getTranslateS3DownloadUrl \
  -H "X-Api-Key: $BELINDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"translateOrderNo": "<translateOrderNo>", "urlType": 2}'

# event:[DONE]
# data:{"url":"https://..."}

開始使用

驗證方式

開放端點都掛在 /external/ 底下，僅憑金鑰辨識呼叫方。其餘的參數、預設值與回應結構都與網頁端一致。

http

POST /api/external/translate/getModelList HTTP/1.1
Host: belindoc.com
Content-Type: application/json
X-Api-Key: ft_xxxxxxxxxxxxxxxxxxxxxxxx
language: zh

{}

json

{
  "code": "200",
  "msg": null,
  "requestId": "8f1c…",
  "data": { }
}

X-Api-Key 標頭: 每次請求都要帶上金鑰。金鑰缺漏、被停用、已過期或呼叫 IP 不在白名單內，都會在進入業務邏輯前被擋下。
language 標頭: 選填，決定回應中 msg 的語言，不帶預設為 en。可用值為站台支援的 9 種語言：en、zh、zh-Hant、ja、ko、fr、ru、de、ar。
金鑰只作用於個人帳號: 金鑰永遠解析成建立它的那個個人帳號。檔案走平台儲存，任務扣的是該帳號自己的額度——組織的私有空間不透過 API 存取。
統一回應結構: 所有端點都使用同一層包裝。code 為 200 代表成功，其餘皆為業務錯誤，msg 內是對應語言的提示文字。
不需要 JWT，也不需要簽章: 網頁端那套 token 與簽章過濾器對 /external/ 全數放行。金鑰是唯一憑證，請視同密碼，只放在伺服器端。

/external/translate9 個端點

文件翻譯

文件翻譯主流程的全部端點：上傳、送出、輪詢、下載，另有模型與語言列舉——模型名稱與語言碼請從這裡取，別寫死在程式裡。

status：0 待處理 · 1 解析中 · 2 翻譯中 · 3 已完成 · 4 失敗 · 5 已取消
urlType：1 原檔 · 2 譯文 · 3 左右對照 · 4 上下對照 · -1 EPUB 預覽

取得上傳網址

POST

/external/translate/batchPresignedUploadUrl

批次取得檔案的預簽上傳網址。

入參

參數名	型別	必填	說明
fileNameList	array[string]	必填	要取得上傳網址的檔名

回應 · data

參數名	型別	說明
persignedUploadUrl	string	預簽 PUT 網址，10 分鐘內有效
objectKey	string	送出翻譯時要回傳的儲存鍵
fileName	string	原始檔名
storageType	number	該檔案所在的儲存類型

範例

請求

{
  "fileNameList": ["contract.pdf"]
}

回應

{
  "code": "200",
  "data": [
    {
      "persignedUploadUrl": "https://s3.../contract.pdf?X-Amz-Signature=…",
      "objectKey": "translate/10086/2026/contract.pdf",
      "fileName": "contract.pdf",
      "storageType": 1
    }
  ]
}

辨識掃描檔

POST

/external/translate/isOcr

送出前判斷上傳的檔案是不是掃描檔，只在真的需要時才開 OCR。

入參

參數名	型別	必填	說明
fileObjectKey	string	必填	預簽端點回傳的 objectKey
storageType	number	必填	該檔案所在的儲存類型

回應 · data

參數名	型別	說明
isOcr	number	1 表示該檔案是掃描檔
isDoubleDeck	number	1 表示該掃描檔已帶文字層

範例

請求

{
  "fileObjectKey": "translate/10086/2026/contract.pdf",
  "storageType": 1
}

回應

{
  "code": "200",
  "data": { "isOcr": 1, "isDoubleDeck": 0 }
}

送出翻譯任務

POST

/external/translate/batchSubmitTranslateTask

送出批次翻譯任務，回傳 batchNo 與每個檔案的訂單號。

入參

參數名	型別	必填	說明
fileList	array	必填	待翻譯檔案清單
fileName	string	必填	原始檔名
fileObjectKey	string	必填	預簽端點回傳的 objectKey
isOcrFile	number	—	1 表示該檔案以掃描檔處理，取自 isOcr 介面
sourceLanguage	string	必填	來源語言碼，AnyLanguage 為自動偵測
targetLanguage	string	必填	目標語言碼
model	string	必填	模型版本號，取自 getModelList
isOcr	number	—	1 走 OCR，預設 0
isMath	number	—	1 保留公式排版，預設 0
translateStyle	number	—	翻譯風格預設值
terminologyCollectionId	string	—	要套用的術語庫 ID；術語庫目前只能在網頁端建立與管理，介面側暫不提供

回應 · data

參數名	型別	說明
batchNo	string	送出時回傳的批次號
fileList	array	待翻譯檔案清單
balanceHint	number	1 表示剩餘額度已不多

範例

請求

{
  "fileList": [
    { "fileName": "contract.pdf", "fileObjectKey": "translate/10086/2026/contract.pdf" }
  ],
  "sourceLanguage": "AnyLanguage",
  "targetLanguage": "zh-CN",
  "model": "Gemini-2.5-Flash",
  "isOcr": 0,
  "terminologyCollectionId": "66f1c2a4b8d3e5f7a9c1b2d3"
}

回應

{
  "code": "200",
  "data": {
    "batchNo": "B20260828173001",
    "fileList": [
      { "fileName": "contract.pdf", "fileObjectKey": "translate/10086/2026/contract.pdf" }
    ],
    "balanceHint": 0
  }
}

依批次號查任務

POST

/external/translate/searchTranslateFileByBatchNo

依批次號查詢該批全部任務，輪詢進度用這個。

入參

參數名	型別	必填	說明
batchNo	string	必填	送出時回傳的批次號

回應 · 任務物件

參數名	型別	說明
translateOrderNo	string	任務訂單號
batchNo	string	送出時回傳的批次號
sourceFileName	string	原始檔名
status	number	任務狀態，見上方圖例
textNumber	number	本任務計費字元數
targetFileUrl	string	譯文檔案網址
targetFileUrl2	string	中國大陸備援網址
xComparisonS3Url	string	左右對照檔
yComparisonS3Url	string	上下對照檔
freeTranslateQuota	number	本次消耗的免費頁數
walletTranslateQuota	number	本次消耗的付費頁數
createTime	number	建立時間，毫秒時間戳
startTime	number	開始時間，毫秒時間戳
endTime	number	完成時間，毫秒時間戳
errorCode	string	status 為 4 時的失敗碼

範例

請求

{
  "batchNo": "B20260828173001"
}

回應

{
  "code": "200",
  "data": [
    {
      "translateOrderNo": "T20260828173002",
      "batchNo": "B20260828173001",
      "sourceFileName": "contract.pdf",
      "status": 3,
      "textNumber": 4820,
      "targetFileUrl": "https://s3.../contract_zh-CN.pdf?X-Amz-Signature=…"
    }
  ]
}

分頁查翻譯紀錄

POST

/external/translate/searchTranslateFilePage

分頁查詢本帳號的翻譯紀錄。

入參

參數名	型別	必填	說明
pageNum	number	必填	頁碼，從 1 開始
pageSize	number	必填	每頁筆數
status	number	—	任務狀態，見上方圖例
fileType	string	—	依檔案類型篩選，如 PDF
sourceFileName	string	—	依檔名篩選

回應 · data

參數名	型別	說明
records	array	本頁資料
total	number	總筆數
current	number	目前頁碼
pages	number	總頁數

查任務詳情

POST

/external/translate/getTranslateFileDetail

依訂單號查詢單一任務詳情。

入參

參數名	型別	必填	說明
translateOrderNo	string	必填	任務訂單號

回應 · 任務物件

參數名	型別	說明
translateOrderNo	string	任務訂單號
batchNo	string	送出時回傳的批次號
sourceFileName	string	原始檔名
status	number	任務狀態，見上方圖例
textNumber	number	本任務計費字元數
targetFileUrl	string	譯文檔案網址
targetFileUrl2	string	中國大陸備援網址
xComparisonS3Url	string	左右對照檔
yComparisonS3Url	string	上下對照檔
freeTranslateQuota	number	本次消耗的免費頁數
walletTranslateQuota	number	本次消耗的付費頁數
createTime	number	建立時間，毫秒時間戳
startTime	number	開始時間，毫秒時間戳
endTime	number	完成時間，毫秒時間戳
errorCode	string	status 為 4 時的失敗碼

取得下載網址

POST

/external/translate/getTranslateS3DownloadUrl

取得原檔、譯文或對照檔的下載網址（SSE 回應）。

入參

參數名	型別	必填	說明
translateOrderNo	string	必填	任務訂單號
urlType	number	必填	要取哪一份檔案，見上方圖例
isWatermark	number	—	0 表示去浮水印，需方案支援

回應 · SSE 事件

參數名	型別	說明
url	string	下載網址，隨 [DONE] 事件送出
url2	string	中國大陸備援網址，有則送出

範例

請求

{
  "translateOrderNo": "T20260828173002",
  "urlType": 2,
  "isWatermark": 0
}

回應

event:[PROCESS]
data:

event:[DONE]
data:{"translateOrderNo":"T20260828173002","url":"https://s3.../contract_zh-CN.pdf?X-Amz-Signature=…"}

查詢可用模型

POST

/external/translate/getModelList

查詢 model 可用值及其額度係數。

入參

無入參，送出空的 JSON 主體即可。

回應 · data

參數名	型別	說明
version	string	送出時 model 要帶的值
modelType	number	內部模型系列
vipType	number	可用此模型的方案
coefficient	number	此模型的額度係數
groupType	number	所屬分組

查詢支援語言

POST

/external/translate/getLanguageEnum

查詢 79 個支援的語言代碼及各語言譯名。

入參

無入參，送出空的 JSON 主體即可。

回應 · data

參數名	型別	說明
{locale}	object	語言 → 語言碼 → 該語言下的名稱

範例

回應

{
  "code": "200",
  "data": {
    "en": {
      "AnyLanguage": "Any language",
      "zh-CN": "Simplified Chinese",
      "…": "…"
    },
    "zh": {
      "AnyLanguage": "任意语言",
      "zh-CN": "简体中文",
      "…": "…"
    },
    "…": {}
  }
}

/external/videoTranslate10 個端點

影片翻譯

影片翻譯的完整循環：先試算額度，送出後追蹤進度，再取字幕改完回傳重新產生。

status：0 未開始 · 1 進行中 · 2 成功 · 3 失敗 · 4 已取消
step：1 語音辨識 · 2 字幕翻譯 · 3 語音生成
stepStatus：0 未開始 · 1 進行中 · 2 完成 · 3 失敗
subtitleType：0 不嵌字幕 · 1 譯文字幕 · 2 原文字幕 · 3 雙字幕

取得上傳網址

POST

/external/videoTranslate/batchPresignedUploadUrl

批次取得影片的預簽上傳網址。

入參

參數名	型別	必填	說明
fileNameList	array[string]	必填	要取得上傳網址的檔名

回應 · data

參數名	型別	說明
persignedUploadUrl	string	預簽 PUT 網址，10 分鐘內有效
objectKey	string	送出翻譯時要回傳的儲存鍵
fileName	string	原始檔名

送出影片翻譯

POST

/external/videoTranslate/submitVideoTranslate

送出影片翻譯任務，videoTaskParam 內含配音、字幕與字型設定。

入參

參數名	型別	必填	說明
sourceLanguage	string	必填	來源語言碼，AnyLanguage 為自動偵測
targetLanguage	string	必填	目標語言碼
sourceFileObjectKey	string	必填	已上傳影片的 objectKey
videoFileName	string	必填	原始影片檔名
videoTaskParam	object	必填	配音、字幕與字型設定
voiceRole	string	—	配音音色，clone 為複刻原聲
subtitleType	number	—	要嵌入哪種字幕，見上方圖例

videoTaskParam 的其餘欄位（25 項，皆可省略）

參數名	型別	說明
recognType	number	語音辨識引擎，預設 12，保持預設即可
modelName	string	辨識模型，預設 tiny
splitType	string	切分方式，預設 all
isCuda	boolean	是否啟用 GPU 加速，預設 false
translateType	number	字幕翻譯引擎，預設 14，保持預設即可
ttsType	number	語音合成引擎，預設 15，保持預設即可
voiceRate	string	配音語速，如 +10%，預設 +0%
volume	string	配音音量，如 +10%，預設 +0%
pitch	string	配音音調，如 +5Hz，預設 +0Hz
voiceAutorate	boolean	配音時長自動對齊原聲，預設 true
videoAutorate	boolean	畫面時長自動對齊配音，預設 true
appendVideo	boolean	時長不足時循環補足畫面，預設 true
isSeparate	boolean	單獨輸出人聲與背景音，預設 false
onlyVideo	boolean	只產出影片，不產出字幕檔，預設 false
fontsize	number	字幕字級，預設 14
fontname	string	字幕字型名稱，不傳用伺服器預設
fontcolor	string	字幕文字顏色，#RRGGBB 或 ASS 色值
fontbold	boolean	字幕是否粗體
subtitlePosY	number	字幕底邊距畫面底邊的百分比，0-90，不傳為底部
subtitlePosX	number	字幕水平中心距畫面左邊的百分比，5-95，50 為置中
fontbordercolor	string	字幕描邊顏色，#RRGGBB / #RRGGBBAA / ASS 色值
backgroundcolor	string	字幕背景框顏色，#RRGGBB / #RRGGBBAA / ASS 色值
outline	number	描邊寬度 0-10，0 為關閉描邊
shadow	number	陰影大小 0-10，0 為關閉陰影
borderStyle	number	邊框樣式：1 一般描邊/陰影，3 逐行矩形背景框

回應 · 任務物件

參數名	型別	說明
videoTranslateOrderNo	string	影片任務訂單號
videoFileName	string	原始影片檔名
videoDuration	number	影片長度，單位秒
status	number	任務狀態，見上方圖例
step	number	目前處理環節，見上方圖例
stepStatus	number	目前環節的狀態，見上方圖例
targetFileUrl	string	譯文檔案網址
sourceSubtitlesUrl	string	原文字幕檔網址
targetSubtitlesUrl	string	譯文字幕檔網址
freeTranslateQuota	number	本次消耗的免費頁數
walletTranslateQuota	number	本次消耗的付費頁數
errorMessage	string	任務失敗時的原因

範例

請求

{
  "sourceLanguage": "ja",
  "targetLanguage": "zh-CN",
  "sourceFileObjectKey": "video/10086/2026/lecture.mp4",
  "videoFileName": "lecture.mp4",
  "videoTaskParam": { "voiceRole": "clone", "subtitleType": 1 }
}

試算影片額度

POST

/external/videoTranslate/videoTranslateQuotaCalculate

送出前依時長、音色、字幕類型試算額度消耗。

入參

參數名	型別	必填	說明
videoDuration	number	必填	影片長度，單位秒
voiceRole	string	必填	配音音色，clone 為複刻原聲
subtitleType	number	必填	要嵌入哪種字幕，見上方圖例

回應 · data

參數名	型別	說明
translateQuota	number	本次總消耗額度
videoDurationTranslateQuota	number	依長度折算的額度
thirtySecondQuota	number	每 30 秒的額度
quotaCoefficient	number	在基準之上的係數

分頁查影片紀錄

POST

/external/videoTranslate/searchVideoTranslatePage

分頁查詢本帳號的影片翻譯紀錄。

入參

參數名	型別	必填	說明
pageNum	number	必填	頁碼，從 1 開始
pageSize	number	必填	每頁筆數
status	number	—	任務狀態，見上方圖例

回應 · data

參數名	型別	說明
records	array	本頁資料
total	number	總筆數
current	number	目前頁碼
pages	number	總頁數

查任務詳情

POST

/external/videoTranslate/getVideoTranslateDetail

查詢單一影片任務，含進度與成果網址。

入參

參數名	型別	必填	說明
videoTranslateOrderNo	string	必填	影片任務訂單號

回應 · 任務物件

參數名	型別	說明
videoTranslateOrderNo	string	影片任務訂單號
videoFileName	string	原始影片檔名
videoDuration	number	影片長度，單位秒
status	number	任務狀態，見上方圖例
step	number	目前處理環節，見上方圖例
stepStatus	number	目前環節的狀態，見上方圖例
targetFileUrl	string	譯文檔案網址
sourceSubtitlesUrl	string	原文字幕檔網址
targetSubtitlesUrl	string	譯文字幕檔網址
freeTranslateQuota	number	本次消耗的免費頁數
walletTranslateQuota	number	本次消耗的付費頁數
errorMessage	string	任務失敗時的原因

取消影片任務

POST

/external/videoTranslate/cancelVideoTranslateHistory

取消尚未完成的影片任務。

入參

參數名	型別	必填	說明
videoTranslateOrderNo	string	必填	影片任務訂單號

取得字幕檔

POST

/external/videoTranslate/getVideoTranslateSubtitles

取回原文與譯文字幕，供外部編輯。

入參

參數名	型別	必填	說明
videoTranslateOrderNo	string	必填	影片任務訂單號

回應 · data

參數名	型別	說明
sourceSubtitlesUrl	string	原文字幕檔網址
targetSubtitlesUrl	string	譯文字幕檔網址

送出字幕改寫

POST

/external/videoTranslate/submitVideoRewrite

回傳編輯後的字幕，依新字幕重新產生影片。

入參

參數名	型別	必填	說明
videoTranslateOrderNo	string	必填	影片任務訂單號
sourceSubtitlesTxt	string	必填	編輯後的原文字幕
targetSubtitlesTxt	string	必填	編輯後的譯文字幕
videoTaskParam	object	—	配音、字幕與字型設定

videoTaskParam 的其餘欄位（25 項，皆可省略）

參數名	型別	說明
recognType	number	語音辨識引擎，預設 12，保持預設即可
modelName	string	辨識模型，預設 tiny
splitType	string	切分方式，預設 all
isCuda	boolean	是否啟用 GPU 加速，預設 false
translateType	number	字幕翻譯引擎，預設 14，保持預設即可
ttsType	number	語音合成引擎，預設 15，保持預設即可
voiceRate	string	配音語速，如 +10%，預設 +0%
volume	string	配音音量，如 +10%，預設 +0%
pitch	string	配音音調，如 +5Hz，預設 +0Hz
voiceAutorate	boolean	配音時長自動對齊原聲，預設 true
videoAutorate	boolean	畫面時長自動對齊配音，預設 true
appendVideo	boolean	時長不足時循環補足畫面，預設 true
isSeparate	boolean	單獨輸出人聲與背景音，預設 false
onlyVideo	boolean	只產出影片，不產出字幕檔，預設 false
fontsize	number	字幕字級，預設 14
fontname	string	字幕字型名稱，不傳用伺服器預設
fontcolor	string	字幕文字顏色，#RRGGBB 或 ASS 色值
fontbold	boolean	字幕是否粗體
subtitlePosY	number	字幕底邊距畫面底邊的百分比，0-90，不傳為底部
subtitlePosX	number	字幕水平中心距畫面左邊的百分比，5-95，50 為置中
fontbordercolor	string	字幕描邊顏色，#RRGGBB / #RRGGBBAA / ASS 色值
backgroundcolor	string	字幕背景框顏色，#RRGGBB / #RRGGBBAA / ASS 色值
outline	number	描邊寬度 0-10，0 為關閉描邊
shadow	number	陰影大小 0-10，0 為關閉陰影
borderStyle	number	邊框樣式：1 一般描邊/陰影，3 逐行矩形背景框

回應 · data

參數名	型別	說明
videoTranslateRewriteOrderNo	string	字幕改寫任務訂單號
status	number	任務狀態，見上方圖例
targetFileUrl	string	譯文檔案網址

查字幕改寫進度

POST

/external/videoTranslate/getVideoTranslateRewriteDetail

查詢字幕改寫任務的進度。

入參

參數名	型別	必填	說明
videoTranslateRewriteOrderNo	string	必填	字幕改寫任務訂單號

回應 · data

參數名	型別	說明
status	number	任務狀態，見上方圖例
targetFileUrl	string	譯文檔案網址
targetSubtitlesUrl	string	譯文字幕檔網址
errorMessage	string	任務失敗時的原因

試算字幕改寫額度

POST

/external/videoTranslate/videoTranslateRewriteQuotaCalculate

試算字幕改寫重新產生影片的額度消耗。

入參

參數名	型別	必填	說明
videoTranslateRewriteOrderNo	string	必填	字幕改寫任務訂單號

回應 · data

參數名	型別	說明
translateQuota	number	本次總消耗額度
quotaCoefficient	number	在基準之上的係數

/external/user2 個端點

帳戶資訊

金鑰背後那個帳號的額度與方案。送出前先查餘額，比等介面回錯再補救省事。

subscriptionStatus：1 待處理 · 2 訂閱中 · 3 已退訂 · 4 已取消
interval：1 日 · 2 週 · 3 月 · 4 年

查詢剩餘額度

POST

/external/user/getMyWalletInfo

查詢該金鑰所屬帳號的錢包：頁數額度、OCR 額度、去浮水印次數與邀請獎勵餘額。

入參

無入參，送出空的 JSON 主體即可。

回應 · data

參數名	型別	說明
userId	number	該金鑰所屬的帳號 ID
translateQuota	number	剩餘可用頁數額度
advancedTranslateQuota	number	剩餘進階模型額度
ocrTranslateQuota	number	剩餘 OCR 額度
accelerationCardNumber	number	剩餘加速卡數量
totalFreeTranslateQuota	number	本週期發放的免費頁數
useFreeTranslateQuota	number	本週期已用的免費頁數
totalFreeOcrTranslateQuota	number	本週期發放的免費 OCR 頁數
useFreeOcrTranslateQuota	number	本週期已用的免費 OCR 頁數
freeWatermarkQuota	number	剩餘去浮水印次數
daysFreeWatermarkQuota	number	每日發放的去浮水印次數
usedDaysFreeWatermarkQuota	number	今日已用的去浮水印次數
rewardBalance	number	邀請獎勵餘額
rewardTotal	number	累計獲得的邀請獎勵

範例

請求

{}

回應

{
  "code": "200",
  "data": {
    "userId": 10086,
    "translateQuota": 12000,
    "advancedTranslateQuota": 0,
    "ocrTranslateQuota": 800,
    "totalFreeTranslateQuota": 500,
    "useFreeTranslateQuota": 132
  }
}

查詢目前方案

POST

/external/user/getMySubscriptionInfo

查詢該金鑰所屬帳號的方案：級距、當前週期，以及它給到的並行數、檔案大小與影片長度上限。

入參

無入參，送出空的 JSON 主體即可。

回應 · data

參數名	型別	說明
vipName	string	方案名稱
vipType	number	方案級距
subscriptionStatus	number	訂閱狀態，見上方圖例
interval	number	訂閱週期，見上方圖例
startTime	number	本期開始時間，毫秒時間戳
endTime	number	本期結束時間，毫秒時間戳
translateQuota	number	每期發放的頁數額度
advancedTranslateQuota	number	每期發放的進階模型額度
freeTranslateQuota	number	每個週期發放的免費頁數
freeTranslateQuotaInterval	number	免費頁數的重置週期：1 日 · 2 週 · 3 月
concurrenceTask	number	文件任務的並行上限
uploadFileSize	number	單一檔案大小上限，單位 MB
videoDurationLimit	number	影片長度上限，單位分鐘
videoTranslateConcurrency	number	影片任務的並行上限
videoFileSize	number	影片檔案大小上限，單位 MB

附錄

錯誤碼

金鑰層級的失敗同樣回傳 HTTP 200，業務碼放在回應主體裡。下列是接入方必須處理的幾個。

錯誤碼	含義	處理建議
30306	無效的 API 金鑰	確認金鑰是否完整複製（含 ft_ 前綴）。已刪除的金鑰同樣回傳這個碼。
30307	金鑰已停用	在開發者中心重新啟用，或改用另一把金鑰。
30308	金鑰已過期	把到期時間往後調，或建立新的金鑰。
30309	呼叫 IP 不在白名單內	把伺服器的對外 IP 加入該金鑰白名單，或直接清空白名單。
30312	金鑰遭管理員封鎖	請聯絡客服處理，這一項無法在開發者中心自行解除。

翻譯本身的錯誤——額度不足、檔案不支援、重複送出等——各有專屬錯誤碼，msg 也會依 language 標頭回傳對應語言。分支判斷請看 code，不要看 msg。

附錄

額度與限制

API 只是換一種呼叫方式，不是另一項產品。以下規則與網頁端完全相同。

同一份額度，不另計費: API 呼叫扣的是與網頁端同一份頁數、影片額度，模型係數也相同，沒有另外的 API 價目。
浮水印規則一致: 免費額度下 PDF 譯文帶浮水印，與瀏覽器中取得的完全相同，走 API 也不會去掉。
只有送出類端點計次: 金鑰的呼叫次數只在 batchSubmitTranslateTask、submitVideoTranslate、submitVideoRewrite 累加，查詢類端點可自由輪詢，不計次。
同一帳號序列化送出: 送出會依帳號加鎖。上一次尚在受理時再送一次，會得到重複任務的錯誤碼——稍候重試即可，不要平行連發。
OCR 預設關閉: 只有掃描檔才需要帶 isOcr。OCR 會在頁數額度之外再扣一份 OCR 子額度，文字版 PDF 開著它等於雙倍消耗——拿不準就先呼叫 isOcr 介面驗一下。

不想自己接 HTTP？

同一套能力也以 MCP 工具形式開放，AI 助理可直接呼叫，一行 HTTP 程式碼都不必寫。

查看 MCP 接入查看方案與額度

翻譯 API 文件

建立金鑰

上傳檔案

送出翻譯

輪詢並下載

取得上傳網址

辨識掃描檔

送出翻譯任務

依批次號查任務

分頁查翻譯紀錄

查任務詳情

取得下載網址

查詢可用模型

查詢支援語言

取得上傳網址

送出影片翻譯

試算影片額度

分頁查影片紀錄

查任務詳情

取消影片任務

取得字幕檔

送出字幕改寫

查字幕改寫進度

試算字幕改寫額度

查詢剩餘額度

查詢目前方案

不想自己接 HTTP？