クイックスタート
以下のフローでは、APIキーを使用して1つのファイルをアップロードし、翻訳ジョブを作成し、結果をダウンロードします。
-
認証情報とファイルを準備する
Terminal window export OMNIDOC_API_KEY="sk_your_key"BASE="https://omnidoc.top/api/v1"FILE="report.docx"SIZE=$(wc -c < "$FILE" | tr -d ' ')import uuidfrom pathlib import Pathimport requestsAPI_KEY = "sk_your_key"BASE = "https://omnidoc.top/api/v1"FILE = Path("report.docx")H = {"X-API-Key": API_KEY}import axios from 'axios';import fs from 'node:fs';import path from 'node:path';const API_KEY = 'sk_your_key';const BASE = 'https://omnidoc.top/api/v1';const filePath = 'report.docx';const apiHeaders = { 'X-API-Key': API_KEY }; -
アドレスを要求し、ファイルをアップロードする
Terminal window PRESIGN=$(curl --fail-with-body -sS "$BASE/upload/presign" \-H "X-API-Key: $OMNIDOC_API_KEY" \-H "Content-Type: application/json" \-d "$(jq -n --arg filename "$(basename "$FILE")" --argjson size "$SIZE" \'{filename:$filename,file_size:$size}')")UPLOAD_URL=$(printf '%s' "$PRESIGN" | jq -r '.upload_url')UPLOAD_TYPE=$(printf '%s' "$PRESIGN" | jq -r '.upload_headers["Content-Type"]')FINALIZE_TOKEN=$(printf '%s' "$PRESIGN" | jq -r '.finalize_token')curl --fail-with-body -sS -X PUT "$UPLOAD_URL" \-H "Content-Type: $UPLOAD_TYPE" \-H "If-None-Match: *" \--upload-file "$FILE"presign = requests.post(f"{BASE}/upload/presign",headers=H,json={"filename": FILE.name,"file_size": FILE.stat().st_size,},timeout=20,)presign.raise_for_status()ticket = presign.json()with FILE.open("rb") as stream:put_headers = {**ticket["upload_headers"],"Content-Length": str(FILE.stat().st_size),}uploaded = requests.put(ticket["upload_url"], headers=put_headers, data=stream, timeout=300)uploaded.raise_for_status()const stat = fs.statSync(filePath);const { data: ticket } = await axios.post(`${BASE}/upload/presign`,{filename: path.basename(filePath),file_size: stat.size,},{ headers: apiHeaders });await axios.put(ticket.upload_url, fs.createReadStream(filePath), {headers: { ...ticket.upload_headers, 'Content-Length': stat.size },maxBodyLength: Infinity,}); -
アップロードを確認し、ドキュメントIDを取得します
Terminal window DOCUMENT=$(curl --fail-with-body -sS "$BASE/upload/finalize" \-H "X-API-Key: $OMNIDOC_API_KEY" \-H "Content-Type: application/json" \-d "$(jq -n --arg token "$FINALIZE_TOKEN" '{finalize_token:$token}')")DOCUMENT_ID=$(printf '%s' "$DOCUMENT" | jq -r '.document.id')finalized = requests.post(f"{BASE}/upload/finalize",headers=H,json={"finalize_token": ticket["finalize_token"]},timeout=30,)finalized.raise_for_status()document_id = finalized.json()["document"]["id"]const { data: finalized } = await axios.post(`${BASE}/upload/finalize`,{ finalize_token: ticket.finalize_token },{ headers: apiHeaders });const documentId = finalized.document.id; -
翻訳ジョブを作成します
Terminal window JOB=$(curl --fail-with-body -sS "$BASE/jobs" \-H "X-API-Key: $OMNIDOC_API_KEY" \-H "Content-Type: application/json" \-H "Idempotency-Key: $(uuidgen)" \-d "$(jq -n --arg document_id "$DOCUMENT_ID" \'{document_id:$document_id,target_lang:"en"}')")JOB_ID=$(printf '%s' "$JOB" | jq -r '.id')job_response = requests.post(f"{BASE}/jobs",headers={**H, "Idempotency-Key": str(uuid.uuid4())},json={"document_id": document_id, "target_lang": "en"},timeout=30,)job_response.raise_for_status()job_id = job_response.json()["id"]const { data: job } = await axios.post(`${BASE}/jobs`,{ document_id: documentId, target_lang: 'en' },{ headers: { ...apiHeaders, 'Idempotency-Key': crypto.randomUUID() } });const jobId = job.id; -
完了を待ってダウンロードする
import reimport timefrom urllib.parse import unquotewhile True:response = requests.get(f"{BASE}/jobs/{job_id}", headers=H, timeout=20)response.raise_for_status()job = response.json()if job["status"] in {"completed", "failed"}:breaktime.sleep(3)if job["status"] == "failed":raise RuntimeError(job.get("error_msg") or "translation failed")artifacts = requests.get(f"{BASE}/artifacts", headers=H, params={"job_id": job_id}, timeout=20)artifacts.raise_for_status()for artifact in artifacts.json():download = requests.get(f"{BASE}/artifacts/{artifact['id']}/download",headers=H,timeout=300,)download.raise_for_status()fallback = f"{artifact['id']}.{artifact['format']}"disposition = download.headers.get("Content-Disposition", "")utf8 = re.search(r"filename\*=UTF-8''([^;]+)", disposition, re.I)plain = re.search(r'filename="([^"]+)"', disposition, re.I)if utf8:name = unquote(utf8.group(1))elif plain:name = plain.group(1)else:name = fallbacksafe_name = Path(name).name or fallbackPath(safe_name).write_bytes(download.content)
得られるもの
Section titled “得られるもの”スクリプトはまず job_id を出力します。ジョブが成功すると、結果が現在のディレクトリにダウンロードされます。ジョブが completed または failed に達した時点でポーリングは停止します。
所要時間はファイルサイズとキューの状況によって異なります。本番環境では、無制限にポーリングするのではなく、 webhook または SSE を使用してください。
この例では、作成リクエストの自動再試行は行われません。ネットワークタイムアウト後は、ジョブID、べき等性キー、およびリクエスト本文を保持し、まずステータスを確認してください。スクリプトが終了しても、一度作成されたジョブはキャンセルされません。
何かが失敗したとき
Section titled “何かが失敗したとき”401:環境変数が設定されており、キーが有効であることを確認してください。402、または作業中のquota_exceeded:クレジット残高(負債控除後)が開始閾値をカバーしていることを確認してください。403:キーの予算、許可されている設定、およびリソースの所有者を確認してください。429:ビジネスエラーコードを読み取り、レート制限、キューの満杯、および予算の枯渇を区別します。- 直接アップロード用アドレスが期限切れまたはアップロードに失敗しました。新しいアップロード用アドレスを取得してください。
X-Request-Id とリクエストパスを記録しますが、フルキーまたはアップロード資格情報は決して記録しません。すべてのエラーと再試行方法については、 エラーリファレンス に記載されています。