Skip to main content
この記事では、CAPTCHA非同期タスククエリインターフェース POST /captcha/tasks を紹介します。任意のCAPTCHAインターフェース(トークンシリーズまたは認識シリーズ)を呼び出す際に async: true を渡すと、インターフェースはすぐに task_id を返し、サーバーがすぐに処理を引き継ぎます。あなたはその task_id を使って最終結果をクエリできますが、クエリはタスクの継続実行の前提ではありません。これはマルチソルバー回転(multi-solver rotation)などのシナリオに適しています:タスクを提出した後、すぐに task_id を取得し、他のソルバーを調整し、後で結果を読み取ることができます。
📘 完全なインタラクティブドキュメント(オンラインデバッグを含む):CAPTCHAタスククエリAPI →

申請プロセス

このインターフェースを使用するには、まず Ace Data Cloudコンソール にアクセスしてAPIトークンを取得し、予備として保管してください。1つのAPIトークンでプラットフォームのすべてのサービスを呼び出すことができ、各サービスごとに個別に申請する必要はありません。

基本的な使用法

ステップ1:非同期方式でタスクを作成

任意のCAPTCHAインターフェースのリクエストボディに async: true を渡すと、インターフェースはすぐに task_id(HTTP 201)を返し、待機することなく処理を開始します:

ステップ2(オプション):task_idを使用して結果をクエリ

進捗を確認する必要がある場合は、前のステップで返された task_id を使用して POST /captcha/tasks をクエリできます(3〜5秒ごとを推奨)。このインターフェースはタスク処理をトリガーしたり進めたりしません;ready結果を読み取る際は、既存の一回限りの決済行動を引き続き使用します:
処理中は status: processing が返されます:
処理が完了すると status: ready と対応する結果フィールドが返されます——フィールド構造は同期モードと完全に一致します:
  • トークンシリーズ(hcaptcha、recaptcha2、recaptcha3)は token を返します:
  • 認識分類(recognition/recaptcha2、recognition/hcaptcha)は solution を返します;recognition/image2text は text を返します。
/captcha/tasks はすべてのCAPTCHAインターフェース(トークンおよび認識シリーズ)に共通で、同じ task_id でポーリングできます。 サーバーは作成時から処理を継続し、最長120秒です。デッドラインの最後のクエリで結果が得られない場合、HTTP 504が永続化されます。この状態は終端状態であり、クライアントはポーリングを停止する必要があります;同じ task_id を繰り返しクエリすると、同じ失敗結果が安定して返されます:
status: ready とHTTP 504の終端応答は、計時フィールドを含みます。
  • started_at、タスク開始処理時間、Unixタイムスタンプ(秒、浮動小数点)。
  • finished_at、タスク結果出力時間、Unixタイムスタンプ(秒、浮動小数点)。処理中の場合はこのフィールドは返されません。
  • elapsed、タスク処理にかかった時間、単位は秒(浮動小数点、3桁の小数点以下を保持)。処理中の場合はこのフィールドは返されません。

課金説明

非同期モードでは、タスクの作成と「処理中」状態の読み取りは課金されません;クライアントが初めて成功した結果を読み取るときに1回課金されます(既存の動作および同期モードの価格と一致)。サーバーはタスクを自動的に進めますが、バックグラウンドで先に完了しても早期に課金されることはありません。120秒のデッドライン内に成功しなかったタスクはHTTP 504で終了し、課金されません。

エラー処理

このインターフェースを呼び出す際にエラーが発生した場合、対応するエラーコードと情報が返されます。例えば:
  • 400 invalid_request:リクエストに task_id パラメータが欠けています。
  • 401 invalid_token:未承認、承認トークンが無効または欠落しています。
  • 404 not_found:task_id が存在しない、または現在のアカウントに属していません。
  • 504 timeout:タスクが終了し、結果が生成されませんでした;この task_id のポーリングを停止してください。この失敗は課金されません。

エラー応答の例