はじめての API リクエスト。
DocAligner で書類の輪郭を検出し、MRZScanner で機械読取領域を認識できます。モデルを選び、以下のサンプルで始めてください。
1. API キーを作成
コンソールにログインし、キー名を入力して「キーを作成」を選択します。キー全体は一度しか表示されないため、その場で保存してください。有効期限は 90 日で、いつでも無効化できます。
このキーで呼び出せるモデルを選択します。既存の DocAligner キーの権限は変わりません。
API キーサーバー環境またはターミナルで DOCSAID_API_KEY を設定してください。ブラウザーのコードや公開リポジトリには含めないでください。製品の API キーと Clerk のログインセッションは別の認証情報です。
2. 画像を送信
file フィールドを持つ multipart POST で画像を送信します。対応形式はアニメーションではない JPEG・PNG・WebP で、上限は 768 KiB、400 万画素、各辺 4096 ピクセルです。任意のフィールド do_center_crop=true を指定すると、中央の正方形領域に検出範囲を限定します。
初回の準備
Python 3.12 を使用します。ツールと依存パッケージ一覧を同じローカルフォルダーに保存し、そのフォルダーで以下を実行してください。ツールの出力は英語です。サンプル画像から試すこともできます。
python3 -m venv .venv .venv/bin/python -m pip install -r requirements.txt新しいジョブを作成
画像を document.jpg として置くか、コマンドのファイル名を変更してください。処理済み画像、固定したオプション、新しい操作 ID を docaligner-job-01 に保存します。送信前に input.jpg を確認してください。画像やオプションを変える場合は新しいフォルダーを使います。既存フォルダーは上書きしません。
.venv/bin/python docsaid-client.py new document.jpg --model docaligner --job docaligner-job-01 --origin https://docsaid.orgEXIF に従って回転し、透明部分を白背景に合成して長辺を 1,600 px 以下、容量を 768 KiB 以下にします。入力は静止 JPEG/PNG/WebP、最大 10 MiB・4,000 万画素です。縮小後の文字が読めることを確認してください。
デモに送信した画像をそのまま使う
デモから「処理済み画像」を保存し、--prepared で JPEG のバイト列をそのまま使います。元画像の変換では Python とブラウザーの出力が異なる場合があります。デモの設定に合わせて --center-crop、--doc-align、--raw-mrz を追加してください。send と inspect にもこのコマンドのフォルダー名を使います。
.venv/bin/python docsaid-client.py new docsaid-input.jpg --prepared --model docaligner --job docaligner-demo-01 --origin https://docsaid.org一度送信してレスポンスを保存
キーは非表示の入力で指定するか、設定済みの DOCSAID_API_KEY を使います。キーを保存せず、リダイレクトや自動再試行もしません。HTTP 状態、Request ID、原因コードを表示し、各試行の受付情報とレスポンスをジョブ内の attempts に保存します。
.venv/bin/python docsaid-client.py send docaligner-job-01https://docsaid.org/api/v1/models/docaligner/predict取得した結果を確認
HTTP 200 の後、inspect は response.json の隣に overlay.png を作成します。input.jpg と並べて四隅を確認してください。MRZScanner は返された文字列と後処理の設定も表示します。各欄を原本と照合してください。座標は処理済み画像が基準です。形式の確認では文書の真正性は確認できません。
.venv/bin/python docsaid-client.py inspect docaligner-job-01
中断したジョブを確認
レスポンスがない場合は、job.json の操作 ID をコンソールで先に確認してください。retry は同じ画像・バージョン・設定・ID で一度だけ再送します。受理済みの場合は 409 と Request ID が返ります。認識結果はローカルのレスポンスにのみ保存されます。失った場合は、再計算すると判断したときだけ新しいジョブを作成してください。入力や設定の変更にも新しいジョブが必要です。
操作 ID またはリクエスト ID で検索.venv/bin/python docsaid-client.py retry docaligner-job-01ジョブフォルダーには画像と認識結果が入っています。非公開で保管し、不要になったら削除してください。サポートには操作 ID や診断用の受付情報を送り、画像や認識本文は添付しないでください。
既存クライアント向け HTTP 例
準備と送信のコードを分けて示します。curl 例は Bash、curl 7.76 以降、cat、awk と、操作 ID 作成用の Python 3.12 を使います。Python 例は requests を使用します。Windows は上の PowerShell 手順を利用できます。再試行では画像・設定・操作 ID ファイルを変更しないでください。
export DOCSAID_API_KEY='YOUR_API_KEY'サーバー環境またはターミナルで DOCSAID_API_KEY を設定してください。ブラウザーのコードや公開リポジトリには含めないでください。製品の API キーと Clerk のログインセッションは別の認証情報です。
新しい処理ごとに別のディレクトリを使います。このコマンドは ID ファイルを作成し、既存ファイルの上書きを拒否します。両方の例で毎回同じファイルを読みます。入力と設定とともに保管してください。
python3 -c 'import uuid; from pathlib import Path; f = Path("docsaid-operation-id.txt").open("x"); f.write(str(uuid.uuid4())); f.close()'DOCSAID_OPERATION_ID=$(cat docsaid-operation-id.txt)
DOCSAID_CURL_STATUS=0
curl --fail-with-body --connect-timeout 10 --max-time 30 'https://docsaid.org/api/v1/models/docaligner/predict' \
--dump-header docsaid-response.headers --output docsaid-response.json \
--write-out 'HTTP %{http_code}\n' \
-H "Authorization: Bearer ${DOCSAID_API_KEY:?Set DOCSAID_API_KEY first}" \
-H "Idempotency-Key: ${DOCSAID_OPERATION_ID:?Create an operation ID first}" \
-F 'model_version=docaligner-1.1.1-fastvit-sa24-7f9f5a89' \
-F 'do_center_crop=false' \
-F '[email protected]' || DOCSAID_CURL_STATUS=$?
awk 'tolower($0) ~ /^(http|x-request-id:|x-error-code:|retry-after:)/' docsaid-response.headers
test "$DOCSAID_CURL_STATUS" -eq 0成功時の応答には polygon(四隅の座標)、画像サイズ、model_version、request_id が含まれます。
JPEG/PNG/WebP、上限 768 KiB・4 MP・各辺 4096 px。両モデルでアカウントの利用枠を共有します。
入力と前処理入力と前処理
JPEG/PNG/WebP、上限 768 KiB・4 MP・各辺 4096 px。両モデルでアカウントの利用枠を共有します。
デモは最大10 MiBを受け付け、EXIF の向き、長辺1600 pxへの縮小、白背景への合成を行い、品質0.92、0.80、0.65、0.45、0.25の順に768 KiB以内になるまで JPEG 化します。元画像が4,000万画素を超える場合は拒否します。処理済み入力をダウンロードすると送信したバイト列を取得できます。API は EXIF と色を正規化しますが、上限超過画像の縮小は行いません。
応答仕様
会員コンソールから完全な OpenAPI 契約を取得できます。入力の既定値、出力の型・単位、null 許容項目、合成例、エラーコード別の対応を含みます。ログインしてダウンロードし、クライアント連携に使用してください。
ログインして完全な連携仕様を取得3. 利用状況を確認
コンソールには受け付けたリクエストの最新 30 件と現在の利用枠が表示されます。API とプレイグラウンドで利用枠を共有し、成功したリクエストのみ成功件数に数えます。受付試行件数にも 1 日の上限があります。処理中は利用枠を 1 件分確保し、各アカウントで同時に処理できるのは 1 件です。
毎日の利用枠は 00:00 UTC にリセットされ、リクエストは受付時点の UTC 日付に属します。管理者は利用枠の変更や無料利用件数の即時リセットを行えますが、履歴は保持されます。リセット時に処理中のリクエストは、完了まで 1 件分の枠を確保します。
アプリケーションはアップロード画像や認識結果を保存しません。
完全な Request ID で検索再試行とエラー
重複実行を防ぐには、新しい操作ごとに一意の Idempotency-Key を指定します。使用できるのは 1–64 文字の英字、数字、ピリオド、アンダースコア、コロン、ハイフンです。受付済みのキーを再利用すると 409 が返り、モデルは再実行されません。同一アカウントの全 API キーとプレイグラウンドで共通の保護です。結果は保存しないため、以前の結果は再送されません。
X-Error-Code はモデルの混雑、頻度制限、日次上限、結果不明を区別します。Retry-After がある場合は従い、再試行回数を制限して間隔を徐々に延ばしてください。結果不明の場合は先に利用状況を確認してください。日次上限は UTC 00:00 にリセットされます。
| HTTP | 意味/対応 |
|---|---|
| 400 | 画像をデコードできません。ファイルを確認し、有効な画像を送信してください。 |
| 401 | API キーが未指定、無効、期限切れ、または無効化済みです。Authorization ヘッダーを確認するか、新しいキーを作成してください。 |
| 403 | キーにこのモデルの権限がないか、アカウントが停止されています。コンソールでキーのモデル権限を確認してください。 |
| 409 | この Idempotency-Key は受付済みです。モデルは再実行されず、以前の結果も保存されていません。新しい操作の前に利用状況を確認してください。 |
| 413 | 画像の容量または寸法が上限を超えています。小さい画像を選択してください。 |
| 415 | アニメーションではない JPEG、PNG、WebP の画像を使用してください。 |
| 422 | 有効な結果が得られなかったか、入力項目に問題があります。入力内容を確認して再試行してください。 |
| 429 | 利用枠または同時リクエスト数の上限に達しました。利用状況を確認し、しばらく待ってから再試行してください。 |
| 503 | サービスが混雑しているか、一時的に利用できません。しばらくしてから再試行してください。 |
| 504 | リクエストがタイムアウトしました。結果が不明な場合があるため、再試行する前に利用状況を確認してください。 |
タイムアウトや応答の中断により、結果が不明になる場合があります。未完了のリクエストは 2 分経過後、利用状況の更新時に結果不明として扱われます。再試行前に利用状況を確認し、サポート用に X-Request-ID ヘッダーを控えてください。ベータ版のリクエストは課金されません。
ログインして完全な連携仕様を取得DocAligner と MRZScanner は API とプレイグラウンドで利用できます。ベータ版のリクエストは無料で、支払い設定は不要です。
サービス状況と API の変更コンソール