コンテンツにスキップ

ドキュメントワークフローをアプリに組み込む

1つのファイルのアップロードから翻訳、進行状況の確認、結果のダウンロードまで。各ステップは統合する順序に従って説明されており、ファイル管理、ドキュメント処理、オーディオおよびビデオサービスへのエントリポイントが用意されています。

Base URL https://omnidoc.top/api/v1 · HTTPS · JSON · APIキー認証 · ファイル翻訳は非同期ジョブとして実行されます

本サイトはクラウド HTTP API を説明しています。

01 クレジットを消費しないリクエストから始めます

Section titled “01 クレジットを消費しないリクエストから始めます”

ファイルをアップロードする前に、キーとネットワークが正常に動作することを確認してください。残高チェックにはクレジットは消費されず、翻訳ジョブも作成されません。

  1. APIキーを取得する

    APIコンソール にサインインし、sk_で始まるキーを作成してください。各アプリケーションに対して別々のキーを使用し、予算を設定してください。

    キーは、それを生成したアカウントに対して有効です。サーバーに保存し、環境変数から読み込むようにしてください。決してウェブページのソースや公開リポジトリに含めないでください。

  2. 残高を確認する

    環境変数 OMNIDOC_API_KEY を設定し、以下のいずれかの例を実行してください。成功時は JSON が返されます。401 の場合はキーに問題があるため、確認が必要です。チケット、スクリーンショット、ログには決してフルキーを表示しないでください。

    Terminal window
    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"

アップロードが成功した場合でも、ファイルが保存されていることを示すだけであり、ジョブを作成後は最終状態になるまで待機し、その後で結果を一覧表示してダウンロードしてください。

ステップメソッドとパス保持するもの
アップロードをリクエストするPOST /upload/presignupload_url, upload_headers, finalize_token
ファイルを送信するPUT から返された upload_url成功レスポンス;このリクエストにはAPIキーが含まれていません
アップロードを確認してくださいPOST /upload/finalizedocument.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を送信してください。

キーが到達可能な範囲

キーは、そのアカウントが利用可能なリソースにのみアクセスできます。サービスのステータス、キーの予算、および許可される翻訳設定は引き続き適用されます。アカウントの変更やキーの作成、ローテーション、失効はコンソールで行います。

参照 認証、予算およびローテーション および サービスと権限 。

05 統合にビルド失敗処理を組み込む

Section titled “05 統合にビルド失敗処理を組み込む”

タイムアウトが発生しても、ジョブが作成されなかったことを意味するわけではありません。修正が必要なリクエストと再試行可能なエラーを区別し、同じ処理が二度実行されないようにしてください。

  • 冪等性のある作成 :新しい作成操作ごとにIdempotency-Keyを生成します。同じ操作を再試行する場合は、元のキーと全く同一のリクエスト本文を再利用してください。ドキュメント操作、メディアジョブ、および音声作成にはこのキーが必要です。その他の作成エンドポイントについては、各参照ページをご覧ください。
  • 非同期通知 :最初の連携にはポーリングで問題ありません。継続的な進捗を監視する場合は SSE を使用し、バックグラウンドで最終状態を受け取るには webhook を利用してください。
ステータスまず確認してくださいどうすればよいですか
401 / 403キー、権限、リソース所有権認証情報または権限を修正してください。無暗に再試行しないでください。
402利用可能なクレジットチャージしてから、再度送信してください
409べき等性のキーと本文、リソース状態新しい操作を開始する前に、元の操作をクエリしてください
422レスポンス内のフィールドエラーパラメータまたはファイルを修正してください
429ビジネス code および Retry-Afterレート制限およびキュー制限は待機することで回避できますが、使用済みのキー予算を増額する必要があります。
5xx一時的なサービスエラー制限付き指数バックオフ;作成リクエストにはべき等性キーを保持する

トラブルシューティングのためにX-Request-Idレスポンスヘッダー、リクエスト時刻、およびパスを保持してください。フルキーをログに記録してはなりません。すべてのエラーコードと再試行の例は、 エラー参照 にあります。

06 統合する前に請求の仕組みを確認してください

Section titled “06 統合する前に請求の仕組みを確認してください”

クレジットなし

アップロード、ジョブの確認、結果のダウンロード、および残高と決済記録の閲覧にはクレジットは消費されません。用語集、プロジェクト、タグ、検索、共有も同様に無料です。

使用量に応じて課金

ファイル翻訳、ドキュメントツール、インスタント翻訳、およびオーディオ・ビデオサービスは、実際の利用量に応じて料金が決まります。ジョブの作成自体には料金は発生しません。

ジョブの開始前には残高しきい値のみが確認され、終了後には実際の使用量が請求されます。残高が不足した場合は差額が債務として記録され、後日入金されたクレジットから優先的に充当されます。請求と返金は、ジョブ単位またはクレジット操作単位で照合できます。キーの予算を使い切った場合でも、そのキー配下のジョブ、結果および記録を引き続き照会できます。