画像 CAPTCHA OCR API：文字キャプチャを REST で認識

SolveHub OCR API で画像文字 CAPTCHA を解決。Base64 画像を POST /v1/tasks に送信し、認識テキストを取得します。フィールド制限、cURL 例、結果形式、エラーコード。

許可された QA 自動化とブラウザー連携向けです。テスト権限のあるサイトと業務フローでのみ使用してください。

画像文字 CAPTCHA に適用されます。実際の画像バイトを Base64 にエンコードして base64 に渡します。data:image/...;base64, プレフィックスを付けることもできます。URL やプロキシは不要です。文字列の上限は 5,242,880 バイトで、画像はデコード可能である必要があります。例は極小のプレースホルダー PNG です。導入時には認識対象の画像に置き換えてください。

リクエストフィールド

外側の type と task は必須です。以下の task.* パスはすべて task オブジェクト内にあります。フィールド名は大文字と小文字が区別されます。長さの制限は UTF-8 のバイト数で計算されます。

フィールド	型	必須	制限	説明
`type`	文字列	はい	`ocr` 固定	プラットフォームのタスクタイプ。
`task`	JSON オブジェクト	はい	≤ 7 MiB	このタイプのタスクパラメータ。
`task.type`	文字列	いいえ	指定する場合は `ocr` であること	旧リクエスト形式との互換用。新規導入では省略できます。
`task.base64`	Base64 文字列	はい	≤ 5,242,880 バイト	元画像の Base64。`data:image/...;base64,` プレフィックスを付けても構いません。内容はデコード可能である必要があります。

作成リクエストの例

{
  "type": "ocr",
  "task": {
    "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aK9sAAAAASUVORK5CYII="
  }
}

cURL での呼び出し

例に含まれるキー、サイト情報、プロキシを実際の値に置き換えてください。Idempotency-Key は同一の業務リクエストに対して変更しないでください。

curl -sS -X POST 'https://www.tiam.codes/v1/tasks' \
  -H 'Authorization: Bearer sh_REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-ocr-0001' \
  --data-binary @- <<'JSON'
{
  "type": "ocr",
  "task": {
    "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aK9sAAAAASUVORK5CYII="
  }
}
JSON

作成レスポンスと照会

作成に成功すると HTTP 202 が返され、status の初期値は通常 queued です。taskId を保存し、約 2–3 秒ごとに GET /v1/tasks/{taskId} を呼び出して照会します。このタイプの処理のソフトタイムリミットは 90 秒 です。ソフトタイムリミットを超えると uncertain になる場合があります。受理済みタスクの結果は引き続き確認できるため、クライアントは新しい冪等キーで安易に再作成しないでください。

結果フィールド

solution は status=completed の場合にのみ読み取ってください。下表はよく使われるフィールドを示しています。実際のフィールドは該当タスクのレスポンスを正とします。

フィールド	型	読み取り方法
`solution.value`	文字列	認識されたテキスト。実際の値は空の場合や、業務側での再検証が必要な場合があります。

タスクが completed になったら、solution.value から認識されたテキストを読み取ります。結果イメージ：{"value":"EXTRACTED_TEXT"}。画像が大きすぎる、Base64 でない、またはデコードできない場合は、作成時に 400 INVALID_TASK が返されます。

失敗とトラブルシューティング

画像が大きすぎる、Base64 が無効、またはデコードできない場合、作成リクエストは 400 INVALID_TASK を返します。処理に失敗したタスクは TASK_FAILED を返します。

作成リクエストでよくあるエラーは 400 INVALID_TASK、402 INSUFFICIENT_BALANCE、429 TASK_LIMIT_EXCEEDED、503 TYPE_UNAVAILABLE です。作成済みタスクが失敗した場合の公開エラーコードは TASK_FAILED または TASK_TIMEOUT で、uncertain には TASK_UNCERTAIN が対応します。詳細はプラットフォーム API リファレンスを参照してください。

処理時間はタスク作成の受理確認後に起算し、待ち行列の時間は差し引きません。ノードの現在のタイムアウトは約30秒、プラットフォームのソフト期限は通信と結果確認を含め90秒です。