ドキュメント翻訳API | Document-Translator.com

クイックスタート

サインインしてAPIキーを作成. キーはサーバーのシークレット設定に保存してください。API翻訳には前払いクレジットが必要です。ブラウザーの無料利用枠は適用されません。
クライアント側で文書のテキストを抽出し、各セグメントに固定IDを割り当てて見積もりをリクエストしてください。再構成できるよう、元の文書はローカルに保存してください。
見積もりID、安定した冪等性キー、同じペイロードを指定して開始します。準備ができるまでポーリングし、翻訳済みセグメントを取得して文書を再構成します。

翻訳APIは抽出されたテキストを受け取り、翻訳済みのセグメントを返します。完成ファイルはお客様のクライアントで作成し、必要に応じて後からダウンロードできるよう翻訳済みファイルを保存できます。元のファイルはアップロードしないでください。

見積もりを作成

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

{
  "version": "document-ir/1",
  "format": "txt",
  "fingerprint": "<64-character SHA-256 of the source file>",
  "sourceLanguage": "auto",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hello, world."
    }
  ]
}

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

翻訳を開始

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

{
  "quoteId": "<quote id>",
  "idempotencyKey": "<stable key, 16–80 letters, digits, underscores or hyphens>",
  "payload": {
    "version": "document-ir/1",
    "format": "txt",
    "fingerprint": "<the same source fingerprint>",
    "sourceLanguage": "auto",
    "targetLanguage": "Spanish",
    "segments": [
      {
        "id": "s0",
        "text": "Hello, world."
      }
    ]
  }
}

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

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

アプリケーションでテキストを抽出し、ダウンロード用ファイルを再構築します。上記のペイロードを送信し、返されたセグメントIDを使って各翻訳を元のドキュメントに戻してください。

// Run this on your server. Keep your API key private.
const response = await fetch(
  'https://document-translator.com/api/v1/quotes',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  }
);
if (!response.ok) throw new Error('Quote request failed');
const quote = await response.json();
// Show the price before starting with the same payload.

DOCXでは対応している元の構造が保持されます。PDF出力ではテキストが再配置され、ページレイアウトは正確に再現されません。スキャンPDFとパスワード保護されたPDFには対応していません。使用前に、重要な翻訳と書式を確認してください。

翻訳クレジットとAPIキー

APIではアップロード上限内の各ドキュメントにつき、アカウントクレジットを1つ使用します。クレジットは処理開始時に確保され、検証済みの翻訳が完成した時点で1回だけ請求されます。登録ボーナスクレジットはAPIでも使用できます。毎日の無料利用枠はウェブサイトでのみ利用できます。

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

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

開始リクエストの結果が不明な場合は、同じ見積もり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は最大10件です。認証済みで削除されていないジョブのみが { jobs: [...] } に含まれます。処理中は約5秒ごと、キュー待ち中は約15秒ごとに確認してください。10件を超えるジョブを復旧する場合は、バッチを公平に切り替えてください。非表示のタブでは確認を一時停止し、終端状態または恒久的な認証エラーになったら停止してください。

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

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

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

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

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回ポーリングしてください。ページが非表示の間は一時停止し、クレジットが追加されるか、アカウントからサインアウトした時点で停止してください。

制限とエラー

1文書あたり、原文は最大50,000語、抽出文字数は最大400,000文字、テキストセグメント数は最大12,000件です。ブラウザーで扱える元ファイルは最大25 MB、PDFは最大100ページです。
アカウントごとに、キュー待ちまたは処理中のドキュメントは最大100件です。開始と再試行には共通のレート制限が適用されます。429レスポンスではRetry-Afterに従い、一時的なエラーには上限付きバックオフを使用してください。
翻訳済みセグメントの欠落、重複、形式不備がある場合は、公開および課金の前に検証エラーとなります。失敗またはキャンセルされた未完了ジョブでは、予約済みクレジットが返却されます。

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

元のドキュメントはお客様のクライアント内に保持されます。抽出されたテキストは翻訳プロバイダーによって処理され、保存された翻訳ファイルはダウンロード用に非公開で保管されます。一時ストレージは定期的に削除されます。プロバイダーの保持ポリシーも適用されます。プライバシーの詳細