Alibaba Cloud（Aliyun）CAPTCHA 2.0 解決 API

SolveHub API で Alibaba Cloud CAPTCHA 2.0 を解決：シーン ID、ID プレフィックス、対象サイトに返送する検証ペイロード。フィールド、cURL 例、エラー。

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

ページアドレス websiteURL、シーン ID websiteKey、アイデンティティプレフィックス prefix、HTTP プロキシは必須です。region は sgp と cn のみサポートし、省略時のデフォルトは sgp です。useragent は任意です。シーン ID とアイデンティティプレフィックスは、対象業務で実際に使用されている Alibaba Cloud CAPTCHA の設定から取得してください。

ブラウザーの選択

useragent を指定する場合はデスクトップ Chrome/Chromium または Android Chrome を使用してください。Firefox、Edge、Opera、iOS は非対応です。Android の対応可否は互換性のあるデバイス指紋を生成できるかに依存します。

リクエストフィールド

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

フィールド	型	必須	制限	説明
`type`	文字列	はい	`aliyun` 固定	プラットフォームのタスクタイプ。
`task`	JSON オブジェクト	はい	≤ 7 MiB	このタイプのタスクパラメータ。
`task.type`	文字列	いいえ	指定する場合は `aliyun` であること	旧リクエスト形式との互換用です。新規の連携では省略できます。
`task.websiteURL`	HTTP(S) URL	はい	≤ 2048 バイト	解決対象ページの完全な URL です。アカウント名やパスワードは含めないでください。
`task.websiteKey`	文字列	はい	≤ 256 バイト	対象ページが CAPTCHA を初期化する際に使用する SceneId。
`task.prefix`	文字列	はい	≤ 128 バイト	対象 CAPTCHA 設定の Identity Prefix。
`task.region`	文字列	いいえ	`sgp` / `cn`	サービスリージョンです。省略した場合はデフォルトのリージョンとして処理されます。
`task.useragent`	文字列	いいえ	≤ 512 バイト	カスタムのブラウザ User-Agent です。後続のリクエストでは、実際に返された `solution.useragent` を優先して使用してください。
`task.proxyType`	文字列	はい	`http` のみ	プロキシのプロトコルです。指定する場合は `http` である必要があります。
`task.proxyAddress`	文字列	はい	≤ 256 バイト	プロキシの IP アドレスまたはホスト名です。`proxyPort` と併せて指定する必要があります。
`task.proxyPort`	文字列	はい	1–5 バイト、値は 1–65535	プロキシのポートです。引用符で囲んだ数字の文字列で指定する必要があります。
`task.proxyLogin`	文字列	いいえ	≤ 256 バイト	プロキシに認証が必要な場合のユーザー名です。アドレスとポートを指定せずに単独で指定することはできません。
`task.proxyPassword`	文字列	いいえ	≤ 256 バイト	プロキシに認証が必要な場合のパスワードです。アドレスとポートを指定せずに単独で指定することはできません。

作成リクエストの例

{
  "type": "aliyun",
  "task": {
    "websiteURL": "https://example.com/login",
    "websiteKey": "SCENE_ID",
    "prefix": "IDENTITY_PREFIX",
    "region": "sgp",
    "proxyType": "http",
    "proxyAddress": "203.0.113.10",
    "proxyPort": "8080"
  }
}

cURL での呼び出し

例の API キー、サイト情報、プロキシを実際の値に置き換えてください。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-aliyun-0001' \
  --data-binary @- <<'JSON'
{
  "type": "aliyun",
  "task": {
    "websiteURL": "https://example.com/login",
    "websiteKey": "SCENE_ID",
    "prefix": "IDENTITY_PREFIX",
    "region": "sgp",
    "proxyType": "http",
    "proxyAddress": "203.0.113.10",
    "proxyPort": "8080"
  }
}
JSON

作成レスポンスと照会

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

結果フィールド

solution は status=completed の場合にのみ読み取ってください。下表は主なフィールドの一覧です。実際のフィールドは当該タスクのレスポンスに従ってください。

フィールド	型	読み取り方法
`solution.value`	オブジェクトまたは JSON 文字列	解析後に `sceneId`、`certifyId`、`deviceToken`、`data` を確認してください。これら 4 項目は実際の結果によって決まります。

solution.value は JSON 文字列の場合も、すでにオブジェクトになっている場合もあります。解析後に sceneId,certifyId,deviceToken,data を読み取ってください。例：{"value":"{\"sceneId\":\"...\",\"certifyId\":\"...\",\"deviceToken\":\"...\",\"data\":\"...\"}"}。deviceToken は解決時のネットワーク環境に関連するため、対象業務に検証ペイロードを送信する際は同じプロキシの送信元 IP を使用してください。

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

prefix は Identity Prefix であり、SceneId で代用することはできません。solution.value は文字列またはオブジェクトの場合があります。deviceToken を利用する際は同じネットワークの送信元 IP を維持してください。

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

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

対応 User-Agent