OmniDocDocument Translation API アクセス ガイド: Python を使用して Word と PDF をバッチ翻訳し、Webhook を使用して結果を受け取る
OmniDoc ドキュメント翻訳 API を使用して、Word、PDF、Excel、その他のファイルをバッチ翻訳します。アップロード、タスクの作成、Webhook コールバックとダウンロードの完全なプロセスと、Python の例、パラメータの説明、べき等再試行、および請求ルールが含まれます。
この記事のポイント
・アップロード申請、アップロード確認、タスク作成、結果取得の4ステップで文書翻訳が完了します。
- タスクを作成するときは、Idempotency-Key を使用することをお勧めします。同じキーと同じリクエストボディが繰り返し作成されたり、繰り返し課金されることはありません。
- タスクの失敗やキャンセルによる料金の減点はなく、残高、タスクのステータス、使用量などのクエリ操作によるポイントの減点はありません。
- PDF タスク開始前の残高はページ数 × 2 ポイントより大きくなければなりません。そうでない場合、タスクはquota_exceeded で終了し、料金は差し引かれません。
ドキュメント翻訳 API は、アップロード、タスクの作成、コールバックの受信、翻訳のダウンロードを自動化されたプロセスに文字列化できます。わずか 4 つのステップで完全な翻訳を完了できます。
システムが契約書、指示書、書類、レポートを毎日処理する場合、手動によるアップロード、待機、ダウンロードがすぐにボトルネックになります。これらの手順をプログラムに引き渡すことで初めてバッチ処理が安定します。
OmniDoc (Zhiyi)のドキュメント翻訳 API は、ファイルのアップロード、タスクの作成、完了通知の受信、翻訳のダウンロード というプロセス全体をつなぎ合わせます。翻訳では、元の文書のレイアウト、表、写真、数式が保持され、対訳比較または翻訳のみを出力できます。
この記事は、ドキュメント翻訳を独自のシステムに統合する必要がある開発者に適しています。これを読むと、完全な呼び出しプロセス、共通パラメータ、べき等再試行メソッド、Webhook コールバック、および課金ルールを習得し、Python を使用して完全なタスクを実行できるようになります。
ドキュメント翻訳 API にアクセスするにはどうすればよいですか?一文の結論
API を使用してドキュメント翻訳を独自のシステムに統合し、4 段階のプロセスで自動的にアップロード、タスクの作成、コールバックの受信、翻訳のダウンロードを行うことができます。
表 0 アクセス シナリオと推奨される実践方法
| あなたの状況 | 推奨される実践方法 | 理由 |
|---|---|---|
| 契約書、仕様書、書類、報告書をバッチ処理する必要がある | API を使用して、4 段階のプロセスに従って翻訳を自動的にアップロード、作成、ダウンロードします | 手動によるアップロード、待機、ダウンロードを排除する |
| バイリンガルでの比較が必要 | Output_mode はバイリンガルに設定されます (デフォルト)。 | PPTX を除く他のすべての形式はバイリンガル出力をサポートします |
| タスクが完了したらすぐに処理されることを希望します | Webhook を設定し、シークレット署名検証を入力します。 | タスクが終了すると、システムはサーバーに事前に通知します。 |
| ネットワークが不安定で、何度も投稿されるのが心配です。 | タスクを作成するときに冪等性キーを持ってきて、タイムアウトになったら最初にステータスを確認します。 | 同じキーと同じリクエストを持っている場合、元のタスクが返され、重複した減点は行われません。 |
アクセスする前に基本情報をお読みください
API の基本的な規約は次のとおりです。コードを書き始める前に、これらの内容を確認してください。
表 1 API の基本規則
| プロジェクト | 説明する |
|---|---|
| Base URL | https://omnidoc.top/api/v1 |
| 認証 | API キーは X-API-Key リクエスト ヘッダーに配置され、ベアラー資格情報として送信することもできます。 APIコンソールで作成 |
| リクエストフォーマット | JSON、コンテンツタイプ: application/json |
| リクエスト追跡 | 各応答の X-Request-Id を保存し、サポートに連絡するときにそれを提供します |
| 電流制限 | 429 が返された場合は、Retry-After を押して再試行します。 |
どのファイルがサポートされていますか?
Word (.docx)、Excel (.xlsx)、PowerPoint (.pptx)、PDF、HTML、EPUB、テキスト付きマークダウン、SRT/ASS 字幕、CSV、PNG/JPG 画像、および UniDoc ドキュメント (.udoc)をサポートします。
PPTX を除き、他のすべての形式はバイリンガル出力をサポートします。 PPTX がバイリンガリズムを要求すると、翻訳のみが返されます。具体的な比較方法については、以下の主要な比較を参照してください。
4 つのステップで翻訳を完了します
- アップロードの申請: POST /upload/presign を呼び出し、ファイル名とサイズを送信し、直接転送アドレス、アップロード ヘッダー、および Finalize_token を取得します。
- アップロードと確認: 返されたアップロード ヘッダーを使用してファイルを PUT します。アップロード時に API キーを使用しないでください。次に、document.id と引き換えに POST /upload/finalize を呼び出します。
- タスクの作成: POST /jobs を呼び出し、document_id と target_lang を送信します。同時に Idempotency-Key を持参することをお勧めします。
- 結果の取得: GET /jobs/{id} をポーリングするか、SSE の進行状況をサブスクライブするか、Webhook を構成します。タスクが完了したら、GET /artifacts?job_id=... を使用して製品を取得し、ダウンロードします。
タスク作成用の共通パラメータ
タスクを作成するときに、最も一般的に使用される 2 つのフィールドは、document_id と target_lang です。他のフィールドは必要に応じて設定されます。
表 2 POST /jobs リクエスト フィールド
| 分野 | デフォルト | 説明する |
|---|---|---|
| document_id | — | 確認済みの文書ID (必須) |
| target_lang | — | ターゲット言語コード (必須) |
| source_lang | 自動検出 | ソース言語コード |
| engine | xr-397b | 翻訳構成: xr-397b、deepseek、qwen、chatgpt、gemini、claude |
| output_mode | bilingual | バイリンガル バイリンガル比較、単一のみの翻訳 |
| glossary_id | — | 用語集ID、統一ブランド名、専門用語 |
| include_images | false | 文書内の画像テキストを処理するかどうか |
| context_translation | false | 強化されたコンテキスト、より一貫した用語 |
| style_preset | — | スタイルのデフォルト |
Python の例: タスクを作成し、完了を待ちます
以下のスニペットはリクエストのみに依存します。アップロードとダウンロードの完全なプロセスについては、開発者ドキュメントの Python ページを参照してください。
import time, uuid, requests
BASE = "https://omnidoc.top/api/v1"
HEADERS = {"X-API-Key": "sk_your_key"}
def create_job(document_id, target_lang="en", engine="xr-397b"):
r = requests.post(f"{BASE}/jobs",
headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
json={"document_id": document_id, "target_lang": target_lang, "engine": engine},
timeout=30)
r.raise_for_status()
return r.json()
def wait_for_job(job_id):
while True:
job = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=20).json()
if job["status"] in ("completed", "failed"):
return job
time.sleep(5)バッチ処理と再試行: 同時実行性、キューイング、冪等性
自動キューイング
各アカウントは 5 つのファイルを同時に処理できます。上限を超えるタスクは通常どおり作成されてキューに入れられ、stage_message には先行するタスクの数が示されます。
冪等キー
Idempotency-Key が同じでリクエスト本文が同じ場合、元のタスクが返され、繰り返し作成または課金されることはありません。ネットワーク タイムアウトが発生した場合は、最初にタスクのステータスを確認し、新しいキーを使用して再送信しないでください。
エラーコード
- 403: 選択した構成はキーに対して許可されていません。
- 404: ドキュメントまたは用語集が存在しません。
- 415: サポートされていない形式です。
- 422: ファイルが空であるか、パラメータが無効です。
Webhook: タスクの終了時にサーバーに通知します
各ユーザーは 3 つの Webhook を設定できます。 POST /webhooks で作成し、PATCH で更新または非アクティブ化します。
ファイル変換タスクが終了すると (成功または失敗に関係なく)、システムは job.completed イベントを送信します。
- data.status は完了または失敗しました。
- data.char_count は翻訳文字数です。
Webhook を作成するときにシークレットを入力すると、後続のすべてのコールバックで X-Webhook-Signature が提供されます。 HMAC-SHA256 を使用して元のリクエストに署名し、コールバック ソースを確認します。
コールバック URL はパブリック ネットワークからアクセスできる必要があり、HTTPS が推奨されます。
料金の計算方法は?
開始前のバランスチェック
・PDF：「ページ数×2ポイント」以上の残高が必要です。
- その他の形式: 元の単語の数に基づいて、少なくとも 2 ポイントが課金されます。
- 残高が不足している場合、タスクはquota_exceededで終了し、料金は差し引かれません。
実際の使用量に基づく控除
タスク完了後、実際の使用量に基づいて料金が差し引かれます。タスクが失敗したりキャンセルされた場合、料金は差し引かれません。
無料のクエリ
残高、タスクのステータス、使用状況、バウチャー、ダウンロード アドレスの確認ではポイントは差し引かれません。
ポイントパッケージ
ポイントパックは3,000ポイントで9.9円から、購入したポイントの有効期限は長期です。セール中のパッケージは、GET /billing/credits/plans 経由でクエリできます。
次のステップ
cURL、Python、Node.js の完全な例は、開発者ドキュメントhttps://docs.omnidoc.top/guide/quickstart/で参照できます。
当分コードを書きたくない場合は、OmniDoc の AI アシスタントに接続してネイティブ ファイルを直接翻訳することもできます。詳しくは「AIにWord・Excel・PPTを直接操作してもらう」：https://omnidoc.top/blog/ai-word-excel-ppt-omnidoc/をご覧ください。
📊 コアの比較
ファイル形式が異なれば、バイリンガル出力方法も異なります。独自のファイルの種類に応じて事前に計画できます。
| ファイルの種類 | 対訳比較方法 | バイリンガルをサポートするかどうか |
|---|---|---|
| Word | 段落ごとに比較する | はい |
| Excel | 列ごとに比較する | はい |
| ページごとに比較する | はい | |
| 字幕（SRT/ASS） | 行ごとに比較する | はい |
| PPTX | 翻訳のみに戻る | いいえ |
🎯 どの方法があなたに適していますか?
契約書、仕様書、または書類をバッチ処理する必要がある場合
API を使用してシステムに接続し、4 段階のプロセスに従ってアップロード、タスクの作成、翻訳のダウンロードを自動的に行うため、手動操作が不要になります。
ネットワークが頻繁に不安定になる場合
タスクを作成するときに冪等性キーを使用します。繰り返しの作成や繰り返しの推論を避けるために、タイムアウト後に最初にステータスをクエリします。
タスク終了後すぐに処理したい場合
Webhook を設定し、署名検証用のシークレットを入力します。タスクが完了すると、システムはサーバーに事前に通知します。
専門用語の要件を統一している場合
まず用語集を作成し、ブランド名と専門用語の翻訳を統一するタスクの作成時に Glossary_id を渡します。
❓ よくある質問 (FAQ)
1. 同じタスクを繰り返し提出すると、減点が繰り返されますか?
Idempotency-Key が同じでリクエスト本文が同じ場合、元のタスクは繰り返し作成または推論されることなく返されます。
2. タスクが失敗したりキャンセルされた場合、ポイントは減点されますか?
手数料はかかりません。タスクが失敗したりキャンセルされた場合、減点は行われません。
3. ポイントが足りない場合はどうなりますか?
タスクはquota_exceededで終了し、料金は差し引かれません。開始前の残高基準は、PDF の場合は「ページ数×2 ポイント」以上の残高が必要、その他の形式の場合は文字数に基づいて 2 ポイント以上の残高が必要です。
4. ファイルをアップロードするときに API キーを持参する必要がありますか?
不要。アップロードヘッダーの PUT ファイルを使用する場合は、API キーを持参しないでください。
5. 429 のトラフィック制限に遭遇した場合はどうすればよいですか?
応答の Retry-After 時間に従って再試行します。
📝 概要
アップロード、タスク作成、コールバック、ダウンロードを自動プロセスに組み込むことで、文書翻訳を日常業務に統合できます。まず、Python の例を使用してタスクを実行し、必要に応じて用語集、バイリンガル出力、Webhook を追加します。
