CAPTCHA 解決 API クイックスタート：3 ステップでタスク作成

アカウント、Key と利用可能残高

まずアカウント登録とメール認証を行います（登録にはメール認証コードが必要です）。新規アカウントはTelegram を連携して 0.10 USD のトライアル残高を受け取ることもでき、入金なしで最初の連携を試せます。コンソールでセルフサービスが利用できる場合は有効化して最初の Key を取得でき、SolveHub 発行の Key を紐付けることもできます。利用できない場合は Key の発行を SolveHub に依頼してください。メール登録だけではタスク API を使える状態にはなりません。Key 画面で tasks 権限、期限、IP 制限、支出枠を確認し、現在の方法でチャージします。料金は公開情報ですが、残高と Key 状態は自分のアカウントで確認してください。

1. コンソールから tasks 権限を持つ API キーを取得し、GET /v1/prices を呼び出して、対象 type の available が true であることを確認します。本番環境のベース URL は https://www.tiam.codes です。ローカルの API アドレスは http://127.0.0.1:8080 です。
2. 左側の CAPTCHA タイプ別セクションに従って task パラメータを準備します。POST /v1/tasks に外側の type と内側の task を送信し、同時に Authorization: Bearer <API_KEY>、Content-Type: application/json、および 8–128 文字の Idempotency-Key を指定します。リクエストに clientKey、taskType、その他のサービスのキーを含めないでください。
3. 返された taskId を保存します。約 2–3 秒ごとに GET /v1/tasks/{taskId} を照会し、completed、failed、または cancelled になるまで待ちます。完了したタスクの solution を読み取ります。queued、dispatching、processing の場合は待機を続けます。uncertain の場合は元のタスクを保持したまま照会を続けるか、サポートに連絡してください。新しい冪等キーで安易に再作成してはいけません。

export SOLVEHUB_URL='https://www.tiam.codes'
export SOLVEHUB_API_KEY='sh_REPLACE_ME'
curl -sS -X POST "$SOLVEHUB_URL/v1/tasks" \
  -H "Authorization: Bearer $SOLVEHUB_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: your-order-12345' \
  -d '{"type":"turnstile","task":{"websiteURL":"https://example.com","websiteKey":"SITE_KEY"}}'
# レスポンスから taskId を保存し、続けて照会します：
curl -sS -H "Authorization: Bearer $SOLVEHUB_API_KEY" \
  "$SOLVEHUB_URL/v1/tasks/TASK_ID"

作成に成功すると HTTP 202 が返され、taskId,status,priceMicros,traceId などのフィールドが含まれます。完了後、solution には CAPTCHA タイプに応じた結果が返されます。結果のフィールドはタイプごとに異なります。タスクが成功した場合は作成時に確定した価格で課金され、明確に失敗またはキャンセルされた場合は仮押さえ分が返金されます。ネットワークタイムアウトや 5xx の場合は、同じ冪等キーと同じリクエストボディで再試行してから、元のタスクを照会してください。冪等レコードの保持期間は約 25 時間のみのため、長期的な重複排除には taskId を保存してください。

以下の「結果イメージ」は、完了したタスクの solution フィールドのみを示しています。トークン、Cookie、認識テキスト、プロキシはすべてプレースホルダー値です。実際の結果は、ご自身の GET /v1/tasks/{taskId} レスポンスから読み取ってください。例の値に依存したり、異なるタイプの solution を同一の形式として解析したりしないでください。

カスタムプロキシが必要なタイプでは、proxyType:"http"、proxyAddress、文字列の proxyPort を使用します。アドレスとポートは必ずセットで指定してください。任意のプロキシを指定しない場合、ネットワークリクエストはプラットフォーム側で処理されます。プロキシを使用して解決した場合、Cookie、トークン、または検証ペイロードを使用する際には、通常、同じ送信元 IP と返された useragent を維持する必要があります。API キーとプロキシのパスワードはサーバー側でのみ保管してください。

プラットフォームの作成・照会レスポンス

作成に成功すると（HTTP 202）、プラットフォームのタスクオブジェクトが返されます：

{"taskId":"00000000-0000-4000-8000-000000000001","type":"turnstile","status":"queued","priceMicros":200,"traceId":"00000000-0000-4000-8000-000000000002","createdAt":"2026-10-05T00:00:00Z"}

GET /v1/tasks/{taskId} の照会に成功すると、同じタスクオブジェクトが返されます。status=completed の場合は solution を読み取ります。failed の場合は TASK_FAILED または TASK_TIMEOUT を確認します。uncertain の場合は TASK_UNCERTAIN となり、金額は仮押さえのままのため、元のタスクの照会を続けてください。priceMicros は作成時に確定した 1 回あたりの価格で、金額の単位は USD のマイクロドルです。

公開価格は リアルタイム価格 で確認できるほか、GET /v1/prices を直接リクエストして取得することもできます。契約価格が設定されているお客様は、ご自身の API キーで GET /v1/me/prices をリクエストすると、適用されている単価を確認できます。最終的な課金額は、タスク作成レスポンスの priceMicros を正とします。