Alibaba Cloud (Aliyun) CAPTCHA 2.0 Solver API

Solve Alibaba Cloud CAPTCHA 2.0 with the SolveHub API: scene ID, identity prefix and the verification payload to submit back to the target site. Request fields, cURL example and errors.

For authorized QA automation and browser integration. Use only on websites and workflows you have permission to test.

Requires the page URL websiteURL, the scene ID websiteKey, the identity prefix prefix, and an HTTP proxy. region supports only sgp and cn, and defaults to sgp when omitted; useragent is optional. The scene ID and identity prefix should be taken from the target service's actual Alibaba Cloud CAPTCHA configuration.

Browser selection

When providing useragent, use desktop Chrome/Chromium or Android Chrome. Firefox, Edge, Opera and iOS are unsupported. Android support depends on whether a compatible device fingerprint can be generated.

Request fields

The top-level type and task are required; all task.* paths below are inside the task object. Field names are case-sensitive. Length limits are measured in UTF-8 bytes.

Field	Type	Required	Limits	Description
`type`	String	Yes	Always `aliyun`	Platform task type.
`task`	JSON object	Yes	≤ 7 MiB	Task parameters for this type.
`task.type`	String	No	Must be `aliyun` if provided	Kept for compatibility with the legacy request format; can be omitted in new integrations.
`task.websiteURL`	HTTP(S) URL	Yes	≤ 2048 bytes	Full URL of the target page to solve, without credentials.
`task.websiteKey`	String	Yes	≤ 256 bytes	SceneId used when the target page initializes the CAPTCHA.
`task.prefix`	String	Yes	≤ 128 bytes	Identity Prefix from the target CAPTCHA configuration.
`task.region`	String	No	`sgp` / `cn`	Service region; the default region is used when omitted.
`task.useragent`	String	No	≤ 512 bytes	Custom browser User-Agent; subsequent requests should prefer the `solution.useragent` actually returned.
`task.proxyType`	String	Yes	`http` only	Proxy protocol; must be `http` when provided.
`task.proxyAddress`	String	Yes	≤ 256 bytes	Proxy IP or hostname; must be provided together with `proxyPort`.
`task.proxyPort`	String	Yes	1–5 bytes, value 1–65535	Proxy port; must be a quoted numeric string.
`task.proxyLogin`	String	No	≤ 256 bytes	Username, if the proxy requires authentication; must not be provided without the address and port.
`task.proxyPassword`	String	No	≤ 256 bytes	Password, if the proxy requires authentication; must not be provided without the address and port.

Create request example

{
  "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 call

Replace the key, site details, and proxy in the example with your actual values; keep the Idempotency-Key unchanged for the same business request.

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

Create response and polling

A successful create returns HTTP 202, and status is usually queued initially. Save the taskId and call GET /v1/tasks/{taskId} about every 2–3 seconds. The soft processing time limit for this type is 150 seconds; after the soft limit the task may enter uncertain, and the results of accepted tasks can still be verified. Clients should not blindly recreate the task with a new Idempotency-Key.

Result fields

Read solution only when status=completed; the table below lists common fields, and the actual fields are determined by the task response.

Field	Type	How to read
`solution.value`	Object or JSON string	After parsing, check `sceneId`, `certifyId`, `deviceToken`, `data`; these four are determined by the actual result.

solution.value may be a JSON string or may already be an object; after parsing, read sceneId,certifyId,deviceToken,data. For example: {"value":"{\"sceneId\":\"...\",\"certifyId\":\"...\",\"deviceToken\":\"...\",\"data\":\"...\"}"}. deviceToken is tied to the network environment used for solving, so use the same proxy egress IP when submitting the verification payload to the target service.

Failures and troubleshooting

prefix is the Identity Prefix and cannot be replaced with the SceneId; solution.value may be a string or an object. Keep the same network egress when using deviceToken.

Common errors for create requests are 400 INVALID_TASK, 402 INSUFFICIENT_BALANCE, 429 TASK_LIMIT_EXCEEDED, and 503 TYPE_UNAVAILABLE. When a created task fails, the public error code is TASK_FAILED or TASK_TIMEOUT; uncertain corresponds to TASK_UNCERTAIN. See the Platform API reference for details.

The processing window starts after task creation is confirmed; queue waiting does not consume it. The current node timeout is approximately 120 seconds; the platform allows a 150-second soft window for transport and result polling.

Supported User Agents