Cloudflare Turnstile API：許可されたテストでのトークン取得

SolveHub API で Cloudflare Turnstile を解決：websiteURL と websiteKey、任意の cdata/action とプロキシを送信し、タスクをポーリングしてレスポンストークンを取得。フィールド、cURL 例、エラー。

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

対象ページの完全な URL websiteURL と、ページ上の Turnstile の websiteKey（通常はウィジェットの sitekey）が必要です。ページで cdata または action が明示的に使用されている場合にのみ、対応する値を付加します。どちらも任意の文字列です。カスタム HTTP プロキシは任意で、指定する場合はアドレス、文字列のポート、および任意の認証情報をあわせて指定する必要があります。

ブラウザーの選択

任意の useragent（最大512バイト）で Chrome/Chromium または Firefox と、Windows・macOS・Linux・Android・iOS を選択できます。Turnstile はファミリーとプラットフォームを選び、バージョンはサービス側が決定します。このフィールドまたはカスタムプロキシの指定時は専用ブラウザーを使用します。結果は引き続き solution.value のトークンです。

リクエストフィールド

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

フィールド	型	必須	制限	説明
`type`	文字列	はい	`turnstile` 固定	プラットフォームのタスクタイプ。
`task`	JSON オブジェクト	はい	≤ 7 MiB	このタイプのタスクパラメータ。
`task.type`	文字列	いいえ	指定する場合は `turnstile` であること	旧リクエスト形式との互換用。新規導入では省略できます。
`task.websiteURL`	HTTP(S) URL	はい	≤ 2048 バイト	解決対象ページの完全な URL。アカウント名やパスワードは含めません。
`task.websiteKey`	文字列	はい	≤ 256 バイト	対象ウィジェットの Turnstile sitekey。
`task.cdata`	文字列	いいえ	≤ 4096 バイト	対象ウィジェットが提供している場合に、対応する cdata を指定します。
`task.action`	文字列	いいえ	≤ 4096 バイト	対象ウィジェットが提供している場合に、対応する action を指定します。
`task.useragent`	文字列	いいえ	≤ 512 バイト	ブラウザーの選択。Cookie は返却された `solution.useragent` と共に再利用してください。
`task.proxyType`	文字列	いいえ	`http` のみ	プロキシプロトコル。指定する場合は `http` である必要があります。
`task.proxyAddress`	文字列	いいえ	≤ 256 バイト	プロキシの IP またはホスト名。`proxyPort` と同時に指定する必要があります。
`task.proxyPort`	文字列	いいえ	1–5 バイト、数値 1–65535	プロキシのポート。引用符で囲んだ数字の文字列である必要があります。
`task.proxyLogin`	文字列	いいえ	≤ 256 バイト	プロキシに認証が必要な場合にユーザー名を指定します。アドレスとポートを指定せずに単独で指定することはできません。
`task.proxyPassword`	文字列	いいえ	≤ 256 バイト	プロキシに認証が必要な場合にパスワードを指定します。アドレスとポートを指定せずに単独で指定することはできません。

作成リクエストの例

{
  "type": "turnstile",
  "task": {
    "websiteURL": "https://example.com/login",
    "websiteKey": "0x4AAAAAAA_EXAMPLE"
  }
}

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-turnstile-0001' \
  --data-binary @- <<'JSON'
{
  "type": "turnstile",
  "task": {
    "websiteURL": "https://example.com/login",
    "websiteKey": "0x4AAAAAAA_EXAMPLE"
  }
}
JSON

作成レスポンスと照会

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

結果フィールド

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

フィールド	型	読み取り方法
`solution.value`	文字列	対象業務の検証フローに送信できる Turnstile トークン。

completed になったら solution.value からレスポンストークンを取得します。例：{"value":"0.EXAMPLE_TOKEN"}。トークンはご自身のサイトのバックエンドに渡し、検証または後続の業務リクエストを行ってください。トークンを Cookie として扱わないでください。対象ウィジェットに action または cdata がある場合、送信時の値は対象ページの実際の値と一致させる必要があります。

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

sitekey がない、URL が無効、またはプロキシフィールドが揃っていない場合は 400 INVALID_TASK が返されます。対象ウィジェットが action/cdata を使用している場合は、ページ上の実際の値を送信してください。

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

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

対応 User-Agent