リクエストヘッダー
X-API-Key: sk_…またはAuthorization: Bearer sk_…のいずれかを、リクエストごとに1つ使用してください。JSONの本文とともにContent-Type: application/jsonを送信してください。
Base URL https://omnidoc.top/api/v1 · HTTPS · JSON · APIキー認証 · ファイル翻訳は非同期ジョブとして実行されます
本サイトはクラウド HTTP API を説明しています。
ファイルをアップロードする前に、キーとネットワークが正常に動作することを確認してください。残高チェックにはクレジットは消費されず、翻訳ジョブも作成されません。
APIキーを取得する
APIコンソール にサインインし、sk_で始まるキーを作成してください。各アプリケーションに対して別々のキーを使用し、予算を設定してください。
キーは、それを生成したアカウントに対して有効です。サーバーに保存し、環境変数から読み込むようにしてください。決してウェブページのソースや公開リポジトリに含めないでください。
残高を確認する
環境変数 OMNIDOC_API_KEY を設定し、以下のいずれかの例を実行してください。成功時は JSON が返されます。401 の場合はキーに問題があるため、確認が必要です。チケット、スクリーンショット、ログには決してフルキーを表示しないでください。
export OMNIDOC_API_KEY="sk_your_key"curl --fail-with-body --silent --show-error \ 'https://omnidoc.top/api/v1/billing/credits/balance' \ -H "X-API-Key: $OMNIDOC_API_KEY"import osimport requests
response = requests.get( "https://omnidoc.top/api/v1/billing/credits/balance", headers={"X-API-Key": os.environ["OMNIDOC_API_KEY"]}, timeout=30,)response.raise_for_status()print(response.json())// Node.js 20+, save as balance.mjsconst apiKey = process.env.OMNIDOC_API_KEY;if (!apiKey) throw new Error('Set OMNIDOC_API_KEY');const response = await fetch('https://omnidoc.top/api/v1/billing/credits/balance', { headers: { 'X-API-Key': apiKey }, signal: AbortSignal.timeout(30_000),});if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);console.log(await response.json());アップロードが成功した場合でも、ファイルが保存されていることを示すだけであり、ジョブを作成後は最終状態になるまで待機し、その後で結果を一覧表示してダウンロードしてください。
| ステップ | メソッドとパス | 保持するもの |
|---|---|---|
| アップロードをリクエストする | POST /upload/presign | upload_url, upload_headers, finalize_token |
| ファイルを送信する | PUT から返された upload_url | 成功レスポンス;このリクエストにはAPIキーが含まれていません |
| アップロードを確認してください | POST /upload/finalize | document.id |
| 翻訳を作成する | POST /jobs | ジョブ id |
| ステータスを確認する | GET /jobs/{job_id} | completed または failed |
| 結果を一覧表示する | GET /artifacts?job_id={job_id} | アーティファクト ID とフォーマット |
| 結果をダウンロード | GET /artifacts/{artifact_id}/download | ファイルのバイト数とレスポンスファイル名 |
直接アップロードの場合、サーバーから返されたとおりにupload_headersを送信し、ストレージアドレスには決してX-API-Keyを送信しないでください。アップロードアドレスが期限切れになった場合や転送に失敗した場合は、新しいアドレスを要求してください。詳細: アップロードプロトコル 、 クイックスタート 、 完全なNode.jsワークフロー および 翻訳リクエストフィールド 。
各エントリには、パス、リクエストフィールド、および例が記載されています。お客様のアカウントのサービスステータスとキーの制限は、これらすべてに適用されます。
APIキーはアカウントを識別するものです。ファイルの公開ダウンロードパスワードではありません。
リクエストヘッダー
X-API-Key: sk_…またはAuthorization: Bearer sk_…のいずれかを、リクエストごとに1つ使用してください。JSONの本文とともにContent-Type: application/jsonを送信してください。
キーが到達可能な範囲
キーは、そのアカウントが利用可能なリソースにのみアクセスできます。サービスのステータス、キーの予算、および許可される翻訳設定は引き続き適用されます。アカウントの変更やキーの作成、ローテーション、失効はコンソールで行います。
参照 認証、予算およびローテーション および サービスと権限 。
タイムアウトが発生しても、ジョブが作成されなかったことを意味するわけではありません。修正が必要なリクエストと再試行可能なエラーを区別し、同じ処理が二度実行されないようにしてください。
Idempotency-Keyを生成します。同じ操作を再試行する場合は、元のキーと全く同一のリクエスト本文を再利用してください。ドキュメント操作、メディアジョブ、および音声作成にはこのキーが必要です。その他の作成エンドポイントについては、各参照ページをご覧ください。| ステータス | まず確認してください | どうすればよいですか |
|---|---|---|
401 / 403 | キー、権限、リソース所有権 | 認証情報または権限を修正してください。無暗に再試行しないでください。 |
402 | 利用可能なクレジット | チャージしてから、再度送信してください |
409 | べき等性のキーと本文、リソース状態 | 新しい操作を開始する前に、元の操作をクエリしてください |
422 | レスポンス内のフィールドエラー | パラメータまたはファイルを修正してください |
429 | ビジネス code および Retry-After | レート制限およびキュー制限は待機することで回避できますが、使用済みのキー予算を増額する必要があります。 |
5xx | 一時的なサービスエラー | 制限付き指数バックオフ;作成リクエストにはべき等性キーを保持する |
トラブルシューティングのためにX-Request-Idレスポンスヘッダー、リクエスト時刻、およびパスを保持してください。フルキーをログに記録してはなりません。すべてのエラーコードと再試行の例は、 エラー参照 にあります。
クレジットなし
アップロード、ジョブの確認、結果のダウンロード、および残高と決済記録の閲覧にはクレジットは消費されません。用語集、プロジェクト、タグ、検索、共有も同様に無料です。
使用量に応じて課金
ファイル翻訳、ドキュメントツール、インスタント翻訳、およびオーディオ・ビデオサービスは、実際の利用量に応じて料金が決まります。ジョブの作成自体には料金は発生しません。
ジョブの開始前には残高しきい値のみが確認され、終了後には実際の使用量が請求されます。残高が不足した場合は差額が債務として記録され、後日入金されたクレジットから優先的に充当されます。請求と返金は、ジョブ単位またはクレジット操作単位で照合できます。キーの予算を使い切った場合でも、そのキー配下のジョブ、結果および記録を引き続き照会できます。