验证码识别 API 快速开始：三步创建任务

账户、Key 与可用余额

先注册账户并验证邮箱（注册必须通过邮箱验证码）；新用户还可以绑定 Telegram 领取 0.10 USD 试用余额，无需充值即可先跑通流程。控制台开放自助服务时，可开通账户并获得首把 Key；也可绑定 SolveHub 已签发的 Key。自助服务暂未开放时，请联系 SolveHub 获取 Key，不要假定邮箱注册后即可直接调用任务接口。在控制台的 Key 页面确认 tasks 权限、有效期、IP 限制与消费额度，按当前提供的方式充值。价格接口无需登录，余额与 Key 状态则以自己的账户为准。

1. 从控制台取得具有 tasks 权限的 API Key，并查询 GET /v1/prices，确认目标 type 的 available 为 true。生产环境 Base URL 为 https://www.tiam.codes。本机 API 地址为 http://127.0.0.1:8080。
2. 按左侧验证码类型栏目准备 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 按验证码类型返回结果；不同类型的结果字段不同。任务成功时按创建时冻结的价格扣费，明确失败或取消时退回预占。网络超时或 5xx 时，使用相同幂等键和相同请求体重试，再查询原任务；幂等记录仅保留约 25 小时，长期去重应保存 taskId。

下列“结果示意”只展示已完成任务中的 solution 字段。令牌、Cookie、识别文字及代理均为占位值；真正的结果应从你自己的 GET /v1/tasks/{taskId} 响应读取。不要依赖示例值或把不同类型的 solution 解析为同一种格式。

需要自定义代理的类型使用 proxyType:"http"、proxyAddress、字符串 proxyPort；地址与端口必须一起提供。可选代理不填写时由平台处理网络请求。使用代理解题后，消费 Cookie、令牌或验证载荷时，通常还需保持相同出口 IP 和返回的 useragent。API Key 与代理口令只应保存在服务端。

平台创建与查询响应

创建成功（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 是创建时冻结的单次价格，金额单位为 USD 微美元。

可在 实时价格 查看公开标价，或直接请求 GET /v1/prices。签有协议价的客户可用自己的 API Key 请求 GET /v1/me/prices 查看生效单价；最终扣费以创建任务响应的 priceMicros 为准。