テキスト翻訳 API

この API はテキストをキュー内のジョブとして翻訳し、各ジョブで一つの対象言語を扱います。テキストを送信したら、返されたジョブ ID を保存し、処理が終わるまでジョブを取得してください。すべてのリクエストは HTTPS で送信し、アカウントの認証情報を使用します。例に示す HTTP Basic 認証情報、または API トークンを使用できます。詳しくは認証をご覧ください。認証情報はご自身のサーバーに保管してください。

エンドポイント

二つの API ホスト、https://api.multi.telと互換ホストのhttps://api.multitel.netは、同じアカウント内のジョブ、冪等性キー、制限、課金を共有します。レスポンスのエンベロープが異なるため、対応するパーサーを使い、一貫して同じホストを利用してください。

ホストがapi.multi.telの場合、すべてのパスではプレフィックス/v1/translateを/v3/translateの代わりに使用することもできます。ホストがapi.multitel.netの場合は、/v3/translateのパスを使用してください。

サービス情報のレスポンスには、enabled, paidEnabled, mode（batch）、realtime（false）、maxSourceCharacters（20000）、cpuLanguages、ratesNanosPerCharacterが含まれます。cpuLanguagesは標準翻訳で受け付ける基本言語コードの一覧です。ratesNanosPerCharacterは、各エンジンに設定された原文のコードポイント当たりの料金を、十億分の一米ドル単位で示します。値が 5000 なら百万コードポイント当たり $5 です。このレスポンスは、拡張翻訳が現在利用可能かどうかを示しません。利用できない場合、拡張翻訳の見積もりは 503 を返します。情報の取得は無料です。

テキストの翻訳

JSON を、Content-Type: application/jsonを指定してPOST https://api.multi.tel/v3/translateに送信してください。各ジョブの対象言語は一つなので、対象言語ごとに別のジョブを送信してください。

ロケールコードは BCP 47 タグで、英字、数字、ハイフンからなり、長さは 2 文字以上 63 文字以下です。正規の形式に変換されるため、en-usはen-USとして記録されます。無効なタグ、およびund, mul、zxxは 400 invalid_translation_languageを返します。標準翻訳の対応状況は基本言語で検証し、nbとnnはnoとして扱います。fr-CAのような地域付きの対象タグも受け付けて記録しますが、標準翻訳の出力は基本言語に従い、地域特有の表現は保証されません。

このホストではリクエスト本文を 128 KiB 以内にしてください。テキストは UTF-8 で送信してください。非 ASCII 文字をすべて\uシーケンスにエスケープすると、20,000 文字のリクエストが上限を超えることがあります。

本文で受け付けるのは、この四つのフィールドのみです。その他のプロパティは 400 invalid_translation_requestで拒否されます。idempotency_key、所有者 ID、無料処理フラグ、セグメント配列も含みます。

冪等性と再利用

各送信には、Idempotency-Keyヘッダーが必要です。長さは 1 文字以上 190 文字以下とし、ASCII の英字、数字、-, _, .、:を使用し、先頭と末尾に空白を付けないでください。キーがない、または 191 文字以上の場合は 400 で拒否されます。キーは、両ホストとアカウントのすべての認証情報にわたり、そのアカウントの翻訳に対して有効です。

• 同じキー、同じテキスト、正規化後の言語、同じエンジンで送信すると、既存のジョブと HTTP 200、およびduplicate: trueが返され、追加の課金はありません。
• 同じキーでテキスト、言語、エンジンのいずれかが異なると、409 idempotency_conflictを返します。ジョブの作成後に処理バージョンが変わった場合も、同じキーは 409 を返します。その場合は再送信せず、元のジョブを ID で取得してください。
• 新しいキーでテキスト、正規化後の言語、エンジンが同じ場合、その内容と現在の処理バージョンのジョブがキュー内、実行中、完了、支払い待ちのいずれかであれば、既存のジョブと HTTP 200、およびduplicate: trueが返され、追加の処理料金は発生しません。再利用された支払い待ちジョブは、引き続き精算が必要です。失敗したジョブは再利用されず、新しいジョブが作成されて完了時に課金されます。

API_USER="your-api-username"
API_PASSWORD="your-api-password"

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: translation-example-001" \
  --data '{"text":"Please move my appointment to Tuesday at 3 PM, not 11 AM.","source_language":"en","target_language":"es","engine":"cpu"}' \
  -o translation-job.json \
  https://api.multi.tel/v3/translate

node -p 'JSON.parse(require("node:fs").readFileSync("translation-job.json","utf8")).data.id'

新しいジョブは HTTP 202 を返します。例のテキストは 57 コードポイントなので、百万コードポイント当たり $5 の料金では $0.000285 になります。省略したレスポンスを示します（識別子は例です）。

{
  "status": "success",
  "data": {
    "id": "8b2e4c71-5d3a-4f09-a6e2-1c7f9d3b5a28",
    "status": "queued",
    "mode": "batch",
    "realtime": false,
    "engine": "cpu",
    "sourceLocale": "en",
    "targetLocale": "es",
    "sourceCharacters": 57,
    "costUsd": "0.000285000",
    "costIsEstimate": true,
    "pricePerMillionCharactersUsd": "5.000000000",
    "progress": null
  }
}

送信時には、プリペイド残高でそのジョブと他の未精算ジョブを賄えない場合の 402 insufficient_balance、アカウントまたはサービスに未完了ジョブが多すぎる場合の 429 translation_queue_fullも返されます。次の場合には 503 を返します。

• paid_translation_not_enabled：有料翻訳が無効な場合。
• translation_unavailable：拡張翻訳のリクエストで、拡張翻訳が利用できない場合。
• translation_pricing_unavailable：選択したエンジンに料金が設定されていない場合。

429 および 503 の場合は、同じキーで時間を置いて再試行してください。

品質の選択

長文は小さく分割して処理し、再度結合します。改行や空白が変わったり、処理の境界をまたぐ文で文脈が失われたりすることがあります。原文を保存し、結合後の結果を確認してください。標準翻訳は地域付きタグの基本言語を使用し、タグを受け付けて記録しても、地域特有の表現は保証されません。

標準翻訳は CPU ワーカーで実行します。拡張翻訳は、設定された外部 AI サービスへテキストを送信します。出力の確認は依然として必要です。すべての言語ペアやテキストの種類で、一方のエンジンの精度が高いとは保証しません。

標準翻訳は下訳で、品質と処理時間は言語ペアにより異なります。拡張翻訳は文脈が重要なテキスト向けですが、重要な名前、数字、否定表現、約束の内容の確認は必要です。どちらも元の文字起こしにある誤りは修正しないため、比較できるよう原文を保存してください。

次の操作で、現在の対応状況、標準翻訳の対応言語、設定料金を同じ API ホストで確認してください：GET /v3/translate。標準翻訳のリクエストで、原文または対象の基本言語がcpuLanguagesにない場合、422 translation_language_pair_unavailableを返します。source_languageが指定され、その基本言語が対象言語と同じ場合、ジョブを作成せず 409 translation_same_languageを返します。拡張翻訳は個別に有効化されます。利用できない間、拡張翻訳の送信と見積もりは 503 を返します。

先に料金を見積もる

ホストがapi.multi.telの場合、同じ JSON 本文をPOST /v3/translate/estimateに送信してください。冪等性キーは不要です。見積もりも 422 と 409 の検証を含む同じ検証を行いますが、ジョブ作成、翻訳、資金の確保、残高確認、課金は行いません。HTTP 200 を返し、estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd、costUsdがdataに含まれます。上記の例では、costUsdは0.000285000（標準料金）です。拡張翻訳が利用できない場合、その見積もりは 503 service_unavailableを返します。見積もりには現在の設定料金を使用します。ジョブの料金単価は作成時に固定され、その単価で課金されます。

翻訳結果の取得

新規送信は HTTP 202、既存または再利用のジョブは HTTP 200 を返します。data.idを保存し、共通の「ジョブのワークフロー」を利用してください。ジョブオブジェクトには以下のフィールドが含まれます。

• id, status, engine, sourceLocale、targetLocale。
• sourceCharacters, costUsd, costIsEstimate、pricePerMillionCharactersUsd。
• progress、createdAt。
• modelVersion：内部構造を解釈せずに扱う処理バージョン文字列。
• duplicate：再利用のレスポンスに含まれます。
• failureCode：失敗したジョブの場合は、translation_failed, translation_timeout, input_failed、またはworker_lease_lost。

失敗したジョブのcostUsdはゼロです。

完了したジョブには、data.resultがあり、その中にsourceLocale（原文の言語を指定しなかった場合は空）、targetLocale、翻訳されたtext（セグメントのテキストを改行で結合したもの）、segmentsが含まれます。この API から送信したテキストでは、segmentsに一つのエントリーがあり、翻訳されたtextと対象のlanguageを含みます。支払い待ちのジョブは、精算するまで結果を取得できません。

api.multitel.net の利用

互換エンドポイントPOST https://api.multitel.net/v3/translateは同じ JSON フィールドと同じIdempotency-Keyヘッダーを受け付けます。ヘッダーがない場合は JSON 本文のidempotency_key文字列も受け付けます。その他の追加フィールドは拒否され、400 unsupported_translation_optionを返します。このホストでは、生の本文は最大 256,000 バイトで、20,000 コードポイントを超えるテキストは 413 translation_too_largeを返し、400 ではありません。空のsource_languageは省略として扱います。429 レスポンスにはRetry-After: 15が含まれます。このホストは以下のエラーも返します。

• 400 json_body_required：本文がない、JSON が不正、または JSON スカラーの場合。JSON オブジェクトを送信してください。
• 400 invalid_translation_options：text, target_language、engineのいずれかがない、空、文字列でない場合、またはsource_languageが文字列でない場合。
• 400 invalid_translation_text：テキストが空白のみの場合。
• 400 invalid_translation_engine：エンジンが不明な場合。
• 400 idempotency_key_required：キーがない、空、長すぎる場合、またはidempotency_keyが文字列でない場合。
• 400 invalid_job：ジョブ ID の形式が不正な場合。

このホストの翻訳サービスは、レスポンスにエンベロープ{"status":{"code":HTTP_STATUS},"response":{...}}を使います。statusはオブジェクトです。ジョブ ID はresponse.idから、完了した結果はresponse.resultから取得してください。エラー時はresponse.codeにコードが格納され、メッセージやリクエスト ID は含まれません。認証失敗（401）はホスト共通のサインイン検証が返すため、本文が異なる場合があります。解析前に HTTP ステータスを確認してください。ジョブはプライマリホストと共有されますが、パーサーとエンベロープが合うように、ポーリング、精算、利用量の取得には同じホストを使ってください。このホストも/v3/translate/estimateで同じ JSON フィールドを受け付けます。冪等性キーは不要で、見積もりはresponseに格納されます。