Document-Translator.com
メニュー
JA

ドキュメント翻訳API

アプリやワークフローに文書翻訳を追加できます。抽出したテキストを送信して選択した言語に翻訳し、ご自身のクライアントで文書を再構成できます。サブスクリプション不要の前払いクレジットをご利用ください。

クイックスタート

  1. サインインしてAPIキーを作成. その .env エントリをコピーし、サンプルと同じ場所に非公開の .env ファイルを作成してください。API 翻訳では、利用条件を満たす登録時クレジットを含め、アカウントのクレジットを使用します。ウェブサイトの1日あたりの利用枠は適用されません。キーをコミットしたり、公開されるブラウザーコードに記載したりしないでください。
  2. Node.js のサンプルをダウンロード. Node.js 22 以降を使用してください。パッケージは不要です。UTF-8 の短いテキスト文書を、同じフォルダー内の input.txt として保存してください。このサンプルが対応するのは最大16,000文字です。それを超える文書は、以下の API で複数のセグメントに分けて処理します。
  3. 最初のコマンドを実行すると、クレジットを使わずに見積もりを確認できます。内容を確認してから、2つ目のコマンドを実行してスペイン語に翻訳し、translated.txt に保存してください。必要に応じて言語とパスを変更してください。
node --env-file=.env translate-text.mjs input.txt Spanish translated.txt
node --env-file=.env translate-text.mjs input.txt Spanish translated.txt --start

このサンプルは準備ができるまでポーリングし、既存の出力を上書きしません。.translation.json チェックポイントを保持し、中断後に同じコマンドを再実行してください。追加料金なしで既存のジョブとダウンロードを復旧します。チェックポイントにドキュメントのテキストや API キーは含まれません。待機タイムアウトが発生しても、処理はキャンセルされません。

翻訳APIは抽出したテキストを受け取り、翻訳済みのセグメントを返します。任意の非公開バックアップを使うと、完了から24時間まで文書を復元できます。完成した文書はクライアント側で再構築してください。

または、https://document-translator.com/developers/ をコピーしてAIエージェントに渡すと、使い始める際のサポートを受けられます。

文書翻訳ワークフローを構築

アプリケーション内で、安定したセグメント ID を使ってテキストを抽出します。以下のペイロードを送信し、返された各 ID を使って翻訳をドキュメントに戻してください。

見積もりを作成

POST /api/v1/quotes
Authorization: Bearer doctr_...
Content-Type: application/json

{
  "version": "document-ir/8",
  "format": "txt",
  "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
  "sourceLanguage": "auto",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hello, world."
    }
  ]
}

レスポンスには、見積もりID、原文の単語数、正確なクレジット数、有効期限が含まれます。見積もりの有効期限は10分です。見積もりを依頼しても、クレジットは確保されず、ドキュメントのテキストも保存されません。

見積もりの出力は既定で厳密です。部分的な結果を許可するには、見積もりURLにoutput=best-effort-v1を追加してください。完了した結果にはoutcomeとissuesが含まれます。使用前に確認してください。この方針は見積もり時に固定されます。

POST /api/v1/quotes?output=best-effort-v1

翻訳を開始

POST /api/v1/translations
Authorization: Bearer doctr_...
Content-Type: application/json

{
  "quoteId": "<quote id>",
  "idempotencyKey": "my-document-0001",
  "payload": {
    "version": "document-ir/8",
    "format": "txt",
    "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
    "sourceLanguage": "auto",
    "targetLanguage": "Spanish",
    "segments": [
      {
        "id": "s0",
        "text": "Hello, world."
      }
    ]
  }
}

開始時に、見積もり時と同じペイロードを送信してください。サーバーは、テキストの保存やクレジットの確保を行う前に、所有者と正規化されたハッシュを検証します。JSONオブジェクトのキーの順序は問いません。テキスト、セグメントの順序、形式、フィンガープリント、または言語を変更する場合は、新しい見積もりが必要です。

翻訳結果を取得

GET /api/v1/translations/JOB_ID/result
Authorization: Bearer doctr_...

{
  "version": "document-ir/8",
  "jobId": "<job id>",
  "fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hola, mundo."
    }
  ],
  "mock": false
}

セグメントIDを使ってファイルを再構成してください。結果エンドポイントが返すのはJSONであり、完成したドキュメントではありません。空白、リンク、スタイルなど、翻訳対象ではない構造はクライアント側で保持してください。各セグメントには、a–z、0–9、アンダースコア、ハイフンを使った1～48文字の一意なIDが必要です。セグメントテキストは最大16,000 UTF-16コード単位です。フィンガープリントは、元のファイルのバイト列に対する小文字のSHA-256ハッシュです。

サイトが文書の解析と再構築を行います。APIクライアントは抽出したテキストを送り、ファイルを再構築します。ブラウザーOCRは6言語の鮮明なスキャンに対応します。詳細はホームページのFAQをご覧ください。複雑なレイアウトでは追加ページや読みやすい代替形式を使う場合があります。

cURL で見積もりを1件取得

上記の見積もり用 JSON を payload.json として保存し、シェルで DOCUMENT_TRANSLATOR_API_KEY を設定してください。このコマンドは見積もりのみをリクエストします。処理を開始するには、返された見積もり ID と同一のペイロードを含む開始用 JSON を translations エンドポイントに送信してください。

curl https://document-translator.com/api/v1/quotes \
  -H "Authorization: Bearer $DOCUMENT_TRANSLATOR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @payload.json

PowerShell では curl.exe と $env:DOCUMENT_TRANSLATOR_API_KEY を使用してください。上記のバックスラッシュによる継続記法ではなく、コマンドを1行で記述します。

翻訳クレジットとAPIキー

API の各ドキュメントは、上限の範囲内でアカウントのクレジットを1つ確保します。厳格モードのジョブは検証が完了し、結果が準備できた場合にのみ課金されます。失敗したジョブや、完了前にキャンセルされたジョブでは、確保されたクレジットが解放されます。ベストエフォート出力では、小さな欠落があっても所定のクレジットが使われる場合がありますが、大きな欠落や重大なエラーがある場合はクレジットが解放されます。準備完了の結果がすべて課金済みだと決めつけず、outcome.creditOutcome と outcome.completion を確認してください。

アカウントごとに有効なAPIキーを最大5つ作成できます。キーは作成時にのみ表示され、ハッシュ化して保存されます。キーはアカウントから取り消せます。有効なキーは、同じアカウントの別のキーで作成したジョブを含め、そのアカウントの有料翻訳にアクセスできます。キーではサインインや支払いはできません。

再試行と中断されたリクエスト

GET /api/v1/translations?requestKey=IDEMPOTENCY_KEY&quoteId=QUOTE_ID
DELETE /api/v1/translations?requestKey=IDEMPOTENCY_KEY&quoteId=QUOTE_ID

開始リクエストの結果が不明な場合は、同じ見積もりID、ペイロード、冪等性キーを再利用してください。同一の内容で再試行すると、追加料金なしで既存のジョブが返されます。ペイロードが変更された場合、または別の見積もりに同じキーを使用した場合は、409が返されます。ジョブと冪等性のメタデータは、終了後7日間保持されます。

再開可能な失敗ジョブは、元のテキストが利用可能な間は再試行できます。再試行してもジョブIDは変わらず、完了済みのチャンクを再利用します。処理の試行は最大3回までです。ダウンロードに失敗した場合は、翻訳を再開せずに結果エンドポイントを再試行できます。

ポーリングとダウンロード

GET /api/v1/translations/JOB_ID
GET /api/v1/translations?ids=JOB_ID_1,JOB_ID_2
GET /api/v1/translations/JOB_ID/result
PUT /api/v1/translations/JOB_ID/files/txt
GET /api/v1/translations/JOB_ID/files/txt
POST /api/v1/translations/JOB_ID/retry
DELETE /api/v1/translations/JOB_ID

バッチステータスで指定できるIDは最大100件です。認証済みで削除されていないジョブのみが { jobs: [...] } に含まれます。処理中は約5秒ごと、キュー待ち中は約15秒ごとに確認してください。100件を超えるジョブを復旧する場合は、バッチを公平に切り替えてください。非表示のタブでは確認を一時停止し、終端状態または恒久的な認証エラーになったら停止してください。

状態がreadyになったら、同じアカウント認証を使って結果を取得してください。結果には、ローカルで再構築するための翻訳セグメントの対応情報が含まれます。結果は完了後24時間アクセスできます。入力に問題がある場合は、作成から1時間後に期限切れになります。期限切れの結果は410を返します。削除済みまたはアクセスできないジョブは404を返します。

queued → processing → ready
                   ↘ failed / cancelled / expired

{"jobs":[{"id":"<job id>","state":"processing","completedChunks":1,"totalChunks":2}]}

完成したファイルを保存するには、バイナリ本文、Content-Length、対応するContent-Typeを指定してPUTを使用します。対応拡張子はdocx、pdf、txt、mdで、形式ごとに保存できるファイルは1つ、出力上限は50 MBです。保存に成功したファイルを再度保存しようとしても、既存のファイルが維持されます。GETで保存済みファイルをダウンロードできます。ジョブのステータスにあるsavedFormatsには、利用可能な形式が表示されます。保存とダウンロードには同じジョブ所有権チェックが適用され、追加クレジットはかからず、24時間の期限も延長されません。

PUT /api/v1/translations/{id}/files/docx
X-Download-Kind: reading-copy
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Length: {bytes}

{binary DOCX body}

GET /api/v1/translations/{id}

{"savedFormats":["docx"],"savedDownloads":[{"format":"docx","kind":"reading-copy"}]}

DELETEは未完了の処理をキャンセルするか、利用可能なテキストと保存済みファイルを削除します。完了した結果を削除しても、クレジットは返還されず、ダウンロード期限も延長されません。このリリースでは完了Webhookはありません。

PUT /api/v1/translations/{id}/manifest
Content-Type: application/json
Content-Length: {bytes, maximum 2 MiB}

{"version":1,"parserVersion":"document-ir/8","fingerprint":"{original SHA-256}","ocr":[]}

PUT /api/v1/translations/{id}/source
Content-Type: application/octet-stream
Content-Length: {bytes, maximum 25 MiB}
X-Parser-Version: document-ir/8
X-Source-SHA256: {original SHA-256}

{unchanged original bytes}

GET /api/v1/translations/{id}
// sourceBackup is available only after both saves
GET /api/v1/translations/{id}/manifest
GET /api/v1/translations/{id}/source

アカウント残高と利用履歴

GET /api/v1/translations?before=NEXT_CURSOR&limit=5
GET /api/v1/translations?active=1&before=NEXT_CURSOR
GET /api/account/balance

履歴を閲覧できるのは現在の所有者のみです。取得時には返されたページネーションカーソルを使用してください。残高エンドポイントはブラウザーのアカウントセッションを使用し、サインイン状態と残高に関する最小限の情報を返します。Checkoutが保留中の場合は、5秒ごとに最大10回ポーリングしてください。ページが非表示の間は一時停止し、クレジットが追加されるか、アカウントからサインアウトした時点で停止してください。

n8n、Make、Zapier

シークレットの Bearer 認証情報を使う HTTP リクエストのステップを使用してください。まずテキストを抽出し、JSON ペイロードを見積もり用エンドポイントに POST します。次に、見積もり ID、ペイロード、16～80文字の安定した冪等性キーを translations エンドポイントに POST します。遅延を挟み、準備ができるまでステータスを GET してから、結果を取得し、翻訳済みテキストを再構成または保存してください。ワークフローの記録に見積もり ID と再試行キーを保存してください。専用コネクターやマルチパートアップロードは不要です。

制限とエラー

エラーにはメッセージとコードが含まれます。400は無効な入力、401は無効な認証情報、402はクレジット不足、404はジョブが利用できない状態、409は見積もりまたは状態の競合、410は期限切れ、429はレートまたは容量制限、503はサービス利用不可を示します。

ダウンロードを復元できるよう、翻訳完了から24時間、元の文書のコピーを非公開で保存します。翻訳を削除すれば、それより前にコピーを削除できます。翻訳サービス提供元に送信するのは抽出したテキストのみです。 プライバシーの詳細