無料で使えるパスポートOCR API

アカウントなしで最初の認識を実行する

ドキュメントからキーをコピーして、画像をPOSTするだけです。連携作業はこれですべてです。

IMG=$(base64 -i passport.jpg | tr -d '\n')

curl -s https://api.doc.cheap/v1/scans \
  -H "Authorization: Bearer sk_sandbox_public" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-call-1" \
  -d '{"image":"'"$IMG"'","options":{"mode":"full"}}'

sk_sandbox_public は公開サンドボックスキーです。意図的に公開しているもので、秘密情報ではなく、リクエスト数の制限があります。Idempotency-Key を付けると、再試行したリクエストが二重に課金されることはありません。キューを再実行する日に、これが効いてきます。

返ってくるもの

レスポンスの形式は1つだけで、8つのグループからなり、すべてのキーが常に含まれます。フィールド一覧ではすべてのキーとその型を確認でき、APIリファレンス（英語）が契約そのものです。

{
  "meta": { "schema_version": "1.0", "status": "recognized", "billed": true,
            "confidence": "high",
            "timing": { "upload_ms": 118, "processing_ms": 684, "total_ms": 826 } },
  "document": { "kind": "passport", "country": "GRC", "country_name": "Greece",
                "number": "AM7304518", "series": null,
                "issue_date": "2022-03-10", "expiry_date": "2032-03-10",
                "is_expired": false, "days_remaining": 2001 },
  "holder": { "given_names": "ELENI SOFIA", "surname": "PARADEIGMA",
              "birth_date": "1994-03-08", "sex": "F", "nationality": "GRC" },
  "mrz": { "status": "passed", "reason": null, "lines": ["…", "…"] },
  "fields": [ "…" ], "images": { "…": null },
  "quality": { "overall": "pass" },
  "authenticity": { "overall": "not_checked", "checks": [] }
}

• meta.status は次の5つの文字列のいずれかです：recognized、no_document_found、unreadable、unsupported_document、rejected。
• 日付は常にISO-8601形式です。値がない場合はnullになり、キー自体が省略されることはありません。
• meta.billed はすべてのレスポンスに含まれ、その呼び出しに料金がかかったかどうかを示します。
• fields[] には書類に含まれるすべてのフィールドが入ります。符号化されたゾーンと印字されたゾーンから別々に読み取り、それぞれに信頼度が付くため、2つの読み取り結果を比較できます。独自の文字体系で書かれた値は、ラテン文字への翻字と並べて、言語タグ付きで返ります。

例に登場する所持人は合成した見本です。架空の人物で、架空の値に対して実際のチェックディジット計算を適用しています。この人物のゾーンはMRZフォーマットのページで解説しています。

無料分を使い切った後の料金

画像はどう扱われるか

サンドボックスキーでは何も保存しません。画像はディスクに書き込まれることはなく、リクエストの処理中だけメモリ上に置かれます。結果も保存されません。ご自身の live キーでは、あとで読み直せるよう結果が保持されます。期間はリクエストで指定した retain_hours、指定がなければアカウントの保存期間設定で、変更するまでは1年（8760時間）です。

何も保存したくない場合は retain_hours: 0 を送ってください。保存される結果も、後から取り出すものもありません。呼び出しごとに選べます。

写真を読み取れない場合

レスポンスがそのことを伝え、料金はかかりません。meta.status でケースを区別でき、3つのいずれの場合も meta.billed は false です。

• no_document_found – フレーム内に書類らしきものがない.
• unreadable – 書類は見つかったが読み取れない（反射、ぼやけ、解像度）.
• unsupported_document – 読み取れたが、その種類には対応していない.

すべてのレスポンスに処理時間の内訳が含まれます。リアルタイムの中央値は、ここで約束するのではなく稼働状況ページで公開しています。

キーがまったく不要な無料ツール

• MRZパーサー – TD1、TD2、TD3のゾーンを貼り付けると、すべてのフィールドとチェックディジットを確認できます。ブラウザ内で動作します。
• MRZジェネレーター – テスト用に有効なゾーンを作成できます。
• 書類フィールド一覧 – APIが返すフィールドの一覧を確認できます。

コードからではなくアシスタントから呼び出したい場合は、MCPサーバーが同じ認識機能を3つのツールとして提供しています。