翻訳 API ドキュメント

1. 01

   API キーを作成する

   belindoc.com にログインし、右上のアイコンメニューから「デベロッパーセンター」を開いてキーを作成します。キーは ft_ で始まり、完全な値は作成直後の 1 回だけ表示されます。

2. 02

   ファイルをアップロードする

   まず署名付き URL を取得し、そこへ PUT で直接アップロードします。URL の有効期限は 10 分で、返ってくる objectKey は次のステップで使います。

   bash

   コピー

   # 1. 署名付きアップロード URL を取得（有効期限 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 でファイルをその URL に直接アップロード
   curl -X PUT "<persignedUploadUrl>" --upload-file contract.pdf

3. 03

   翻訳を送信する

   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": [ ... ] } }

4. 04

   進捗を取得してダウンロードする

   batchNo で status が 3 になるまでポーリングし、その後ダウンロード URL を取得します。このエンドポイントは 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>"}'
   
   # 訳文のダウンロード URL を取得：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://..."}

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

{}

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

{
  "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
    }
  ]
}

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

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

{
  "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
  }
}

{
  "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=…"
    }
  ]
}

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

event:[PROCESS]
data:

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

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

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

{}

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

翻訳自体のエラー（クォータ不足、未対応ファイル、重複送信など）は個別のコードを持ち、msg は language ヘッダーの言語で返ります。分岐は msg ではなく code で判定してください。

同じクォータ、追加課金なし

API 呼び出しは Web 版と同じページ数・動画クォータを、同じモデル係数で消費します。API 専用の料金はありません。

透かしの扱いも同じ

無料枠では PDF の訳文に透かしが入ります。ブラウザで取得した場合とまったく同じで、API 経由でも外れません。

呼び出し回数は送信系のみ加算

キーの呼び出し回数は batchSubmitTranslateTask、submitVideoTranslate、submitVideoRewrite でのみ増えます。参照系はいくらポーリングしても加算されません。

アカウントごとに送信は直列

送信はアカウント単位でロックされます。前回の受付中に再送すると重複タスクのエラーコードが返るため、並列に投げず少し待って再試行してください。

OCR は既定でオフ

isOcr はスキャン文書のときだけ指定します。OCR はページ数クォータに加えて OCR 用サブクォータも消費するため、テキスト PDF で有効にすると二重消費になります。判断がつかないときは先に isOcr エンドポイントで確認してください。