SolveHub REST API 参考：任务、价格、余额与 Webhook

本文按当前 HTTP 路由、应用服务及任务参数校验编写。生产地址（Base URL）为 https://www.tiam.codes，下文路径均相对于该地址；本地默认 http://127.0.0.1:8080，生产必须使用 HTTPS。所有示例中的密钥、邮箱和域名均为占位符。响应时间使用 RFC 3339，金额为 USD 微美元整数：1 USD = 1,000,000 micros。价格以 GET /v1/prices 的实时值为准，任务创建时冻结该次售价。

通用约定

常规 API 使用 Authorization: Bearer <API_KEY>；JSON 写请求使用 Content-Type: application/json。客户网页使用 HttpOnly、SameSite=Strict 的 solvehub_portal Cookie；Cookie 鉴权的非 GET/HEAD 请求必须加 X-SolveHub-Portal: 1。登录、注册及退出请求也要求该头。Bearer 优先于 Cookie：不要让浏览器无意附带另一个 Key 的 Authorization 头。

每次响应带 X-Request-ID，可用来向客服定位问题。失败响应通常为 {"error":"ERROR_CODE"}，不是成功响应格式；204 没有响应体。请求体只接受一个 JSON 对象，未知顶层字段通常会返回 400 INVALID_JSON。除创建任务和兼容接口最多 8 MiB 外，JSON 请求体最多 1 MiB。

API Key 权限为 tasks（任务、用量）、billing（余额、账本、充值 Key、历史订单）、account（账户资料、Key 元数据、Webhook、会话列表）。创建、修改或吊销 Key、更改联系邮箱、结束其他设备会话还需要邮箱密码账户会话；持有 account 权限的 Key 也不能执行这些敏感变更。部分宽限接口接受过期 Key，例如余额、充值 Key 兑换、续费记录和工单；过期 Key 不能创建任务，也不能用自身凭证授权扣费续费。冻结账户不能执行新任务、充值 Key 兑换等操作。工单使用已认证客户身份，无单独权限范围。

无需登录的 GET /healthz 返回 {"status":"ok"}，表示 API 进程存活；GET /readyz 返回 {"status":"ready"}，表示数据库及迁移标记可用，异常时返回 503 DATABASE_UNAVAILABLE。这两个接口不保证任务处理能力可用。

身份与会话

注册与绑定流程：POST /v1/portal/register/email 获取邮箱验证码 → POST /v1/portal/register 凭验证码注册邮箱密码账户 → POST /v1/portal/session/account 登录 → POST /v1/portal/account/bind-key 粘贴运营发放的 API Key，账户即归属该 Key 的客户。一个账户对应一个客户，可管理该客户的多把 Key；同一客户只能绑定一个邮箱账户。未绑定期间除会话、安全设置与绑定接口外，其余接口返回 403 ACCOUNT_UNBOUND。已有 Key、尚无邮箱账户的客户也可以继续用 Key 登录后在「安全」页绑定邮箱（见 account/claim）。

密码须为 12–128 个 Unicode 字符，至少有 6 个不同字符，不能包含邮箱地址；不强制混用特殊字符。会话视图含 authMethod,sessionId,customerId,customerName,customerStatus,keyId,keyLabel,scopes,keyExpiresAt,keyExpired,expiresAt,idleTimeoutSeconds；账户会话的 authMethod 为 account，Key 会话为 api_key。会话登录后 24 小时到期。账户会话与某把 API Key 独立；Key 会话随该 Key 撤销失效。TOTP 验证码不能在同一个时间步重复使用。登录失败有 IP 和账户级限制；收到 429 LOGIN_THROTTLED 时遵循 Retry-After。既有账户的登录邮箱默认未验证，需要在控制台“安全”页验证后才能自助恢复密码。遗失验证器时可用一次性恢复码登录、关闭 2FA 或配合已验证登录邮箱的邮件验证码重设密码；恢复码也遗失时需联系管理员核验身份。恢复码只能在启用或重新生成时看到，不应粘贴到工单、聊天或日志中。

**Key 泄露处理：**若仍持有密码账户会话，用 POST /v1/portal/keys/{id}/compromise（account 权限）应急撤销泄露 Key；该接口可撤销最后一把 Key，普通 DELETE /v1/keys/{id} 不行。随后查看 GET /v1/portal/sessions、GET /v1/ledger 和任务列表，撤销可疑会话，创建替代 Key；必要时联系运营冻结客户。已过期的泄露 Key 不能再以自身凭证扣费续费。尚未撤销的泄露 Key 仍能在它的安全额度内创建任务，因此发现泄露后应立即撤销。只有泄露 Key 而没有账户会话的攻击者不能调用应急接口，但撤销传播受多实例缓存影响，仍应尽快联系运营。

新用户试用余额（Telegram 绑定）

注册邮箱密码账户后，可在控制台「安全 → 绑定 Telegram」绑定并验证一个 Telegram 账号，验证成功后平台一次性发放 0.10 USD 试用余额到钱包。余额可直接调用接口，无需充值。

规则：

• 去重以 Telegram 数字 user_id 为准，一个 Telegram 账号只能绑定一个 SolveHub 账户，同一账户也只能绑定一个 Telegram 账号。
• 绑定不可解绑：验证成功后换绑、注销后重新注册都无法再次领取试用余额。
• Bot 回复语言跟随控制台界面语言：bind 请求可带 {"locale":"zh|en|ja"}，未提供时退回 Telegram 客户端语言，仍无法识别则用英文。
• 试用余额永不过期，但只够支撑 1 个并发任务：验证时会把该客户的 max_active 收紧为 1，前一个任务结束后才能提交下一个。任意金额充值到账（含充值码、Cregis 入账、订单确认与正向调账）都会自动删除这条系统设置的限制，恢复到全局默认并发；运营手工调整过的配额不受影响。
• 入账记为一条 credit 分录（备注「新用户 Telegram 验证奖励」），reference 唯一，重复触发不会重复加钱。
• 未绑定账户（status: unbound）验证成功后自动转为 active，随后即可在「API Key」页自助创建 Key（若 customerKeyCreation 为 false 则需运营发放）。

账户与 API Key

通知邮箱与登录邮箱分别验证，即使地址相同也不共用验证状态。未验证的通知邮箱不会收到公告、工单回复、Key 提醒或财务邮件；已排队但尚未投递的旧地址业务邮件在更改地址后作废。已经发出的邮件无法撤回。仅使用 Key 的客户须先在「安全」页用带 account 权限的 Key 自行绑定邮箱密码，才能设置及验证通知邮箱。

APIKeyMeta 包含 keyId,label,hint,status,scopes,ipAllowlist,expiresAt,lastUsedAt,lastUsedIp,createdBy,createdAt,revokedAt,version,spendLimit24hMicros,spendFreezeHourMicros,spendFrozenAt,viewable；viewable 表示服务端保存了该 Key 的加密明文，可在账户会话二次验证后查看，撤销后明文随即删除。expiresAt:null 表示长期有效，状态为 active、expired 或 revoked。spendFrozenAt 非空表示因一小时累计预占超阈值而冻结任务创建。两项额度均为正整数微美元，最多 10,000 USD，且一小时阈值不能超过 24 小时上限。额度按五分钟窗口保守统计，最多额外限制约五分钟；失败或取消后的退款不会释放安全额度，防止反复创建和退款试探。触发冻结的请求不创建任务、不动钱包；已配置联系邮箱且邮件服务可用时会发送通知，不能把邮件当作冻结生效的前提。解除冻结前先核对任务和账本。标签为 1–100 字符；IP 白名单接受单个地址或 CIDR，最多 32 项。不要把 API Key 放入 URL、浏览器本地存储或工单正文。Key 的 account 权限可以读取其他 Key 元数据并管理 Webhook，但不能签发或修改 Key；建议任务进程只授予 tasks。

价格、任务与用量

GET /v1/prices 无需登录，返回按类型命名的对象；每项含 available，启用时含全局 priceMicros,currency，停用时含 reason，还可能有 version,updatedAt。available 表示该类型在价目配置中启用，不代表实时处理能力保证。

需要知道自己的实际单价时调用认证接口 GET /v1/me/prices：结构与 GET /v1/prices 相同，启用类型另含 listPriceMicros（公开标价）和 negotiated。negotiated:true 时 priceMicros 为你的协议价；运营上调采购价导致协议价不再适用时，自动回退公开标价且 negotiated:false。停用或未配置的类型不报价，即使签有协议价。报价与建单使用同一规则，但两次请求之间仍可能调价，最终预占金额以创建响应的 priceMicros 为准。version 是公开价目版本，协议价变化不会改变它。POST /v1/tasks 需要 tasks 权限和 8–128 字符的 Idempotency-Key。请求示例：

POST /v1/tasks HTTP/1.1
Authorization: Bearer sh_EXAMPLE
Content-Type: application/json
Idempotency-Key: order-12345-turnstile

{"type":"turnstile","task":{"websiteURL":"https://example.com","websiteKey":"SITE_KEY"}}

成功返回 202 任务对象，如 {"taskId":"uuid","type":"turnstile","status":"queued","priceMicros":200,"traceId":"uuid","createdAt":"2026-10-02T00:00:00Z"}。任务对象还可能有 solution、errorCode、finishedAt。失败时 errorCode 为 TASK_FAILED 或 TASK_TIMEOUT；待核对时为 TASK_UNCERTAIN。结果只包含客户完成业务所需的字段，诊断信息请凭 taskId 与 X-Request-ID 联系客服。任务状态：queued（可取消）、dispatching、processing、uncertain、completed、failed、cancelled。uncertain 不是终态：平台暂时无法确认任务处理结果或费用，金额继续预占；继续查询原任务并向客服提供 taskId，不要换幂等键创建替代任务。完成时扣除冻结售价，明确失败/取消则退回预占。

失败任务还可能返回 failureReason：上游明确失败时的具体说明（例如 IP Blocked (fake page)），经过脱敏与长度限制；上游没有说明时可能退回稳定失败码。请根据 errorCode 和 status 判断流程，failureReason 仅用于诊断展示，不应作为固定枚举解析。

同一客户在任务幂等记录保留期内重用完全相同的请求体与同一键，会返回原任务而不会再次预占；同键不同请求返回 409 IDEMPOTENCY_CONFLICT。客户端网络超时或 5xx 时先用同一键重试，记录返回的 taskId 并持续查询。服务端定期清理超过约 25 小时的任务幂等记录，因此客户端应长期保存 taskId，不要在清理后依赖旧幂等键去重。任务 task 不得超过 7 MiB。

任务类型与参数

外层 type 必填；内层 task.type 可省略，若提供必须与外层一致。所有类型都拒绝未列出的字段，不能传入 clientKey 或任何外部服务密钥。下表的 URL 必须为完整 HTTP(S) URL；代理端口为字符串，代理协议只能为 http。

websiteURL 上限 2048 字节；websiteKey 256，proxyAddress 256，proxyPort 5，代理用户名/密码各 256。captchaUrl 和 WafScriptUrl 上限 4096；具体可选字段长度以服务端验证为准。funcaptcha 的复杂结构必须按该类型验证规则提交，避免将其他验证码类型字段混用。

funcaptcha.challengeInfo 允许字段：publicKey,site,surl,apiUrl,capiMode,styleTheme,locationHref,documentReferrer,documentTitle,iframeUrl,ancestorOrigins,treeIndex,treeStructure,languageEnabled,jsfEnabled,appMode,uniqueFingerprint,oldFingerprint,overrideFingerprint,syntheticFingerprint,randomProtoChain,randomVideoExtended,staticSpeechData,customTimezoneOffset,historyLength,noIframe,lowBandwidthMode,storageAccess,solvePOW,cookieTimestamp,disableArid,disableAridCookie,disableCookies,disableCookiesAnalytics,disableGT2Cookies,disableNavigatorCookies,powPause,exploitMode,skipHighWaves,submitAnswerPause,extraData。browserInfo 允许字段：Accept-Language,Cache,Cookie,DNT,HTTP3,Linux,Mac,Mobile,Safari,Sec-Ch-Ua,Sec-Ch-Ua-Platform,User-Agent,dataBrands,languages,randomTLS,userbrowser。未列出的字段会被拒绝。

余额与充值

充值只支持管理员人工入账或管理员发行充值 Key 后由客户兑换。客户 POST /v1/topup-orders 固定返回 410 TOPUP_ORDERS_DISABLED，GET /v1/topup-orders/instructions 返回 410 PAYMENT_METHODS_DISABLED。平台没有公开的银行卡、支付宝、微信、USDT、PayPal 或自动付款 API。余额以账本与 GET /v1/balance 为准，不根据客户端付款提示自行增加。

工单与公告

Ticket 含 id,customerId,customerName,category,subject,status,priority,assignedTo,version,createdAt,updatedAt,lastMessageAt,closedAt,messageCount；TicketMessage 含 id,ticketId,authorKind,authorRef,body,internal,createdAt。工单有未关闭数量（20 个）和频率限制（24 小时内创建 10 个）。

创建工单和客户回复可带 Idempotency-Key（8–128 个可见 ASCII 字符，不含空格；格式不符返回 400 INVALID_IDEMPOTENCY_KEY）。键按客户隔离、24 小时内有效：同一键重试相同请求（首尾空白不影响）时返回原工单当前状态，不会重复创建或追加消息，即使工单已关闭或已达到频率上限；同一键用于不同内容、不同工单或在创建与回复之间混用时返回 409 IDEMPOTENCY_CONFLICT。网络错误或 5xx 时应以同一键原样重试；每次新的工单或回复须使用新键。不带该头时保持原有行为，每次请求都会写入。公告正文按纯文本展示；邮箱公告为异步发送，网站接口不代表邮件已送达。

Webhook

推荐多端点接口，最多 10 个端点；地址必须是公开可访问的 HTTPS 443 URL，不允许凭据、查询串或片段。创建与密钥轮换的 signingSecret 只返回一次。

可订阅事件：task.completed、task.failed、task.cancelled、task.uncertain、api_key.expiring、api_key.expired、api_key.renewed、balance.low、topup_order.paid、topup_order.rejected、topup_order.expired。手动测试事件为 webhook.test，无需订阅。部分历史订单事件只针对已存在的订单。

balance.low 在可用余额因任务预占、Key 续费、人工扣减或冲正，从至少 5 USD 降到低于 5 USD 时产生；预占余额不计入可用余额。事件载荷包含 availableMicros 与 thresholdMicros。已验证的通知邮箱也会收到邮件；未验证邮箱不会收件。余额随后补至至少 5 USD，再次跌破时会产生新提醒。已低于阈值的历史余额不会因部署本功能而补发提醒。

平台 POST JSON 到端点，头为 X-SolveHub-Event-ID（十进制事件 ID）、X-SolveHub-Event-Type、X-SolveHub-Timestamp（Unix 秒）及 X-SolveHub-Signature。任务事件正文示例：{"event":"task.completed","occurredAt":"2026-10-02T00:00:00Z","taskId":"uuid","type":"turnstile","status":"completed","traceId":"uuid","priceMicros":200}；测试事件含 event,testId,endpointId,occurredAt。签名为 sha256= 加上 HMAC-SHA256(signingSecret, timestamp + "." + 原始请求体字节) 的十六进制值；轮换宽限期内签名头可能是逗号分隔的两个 sha256= 值，验证任意一个即可。接收端应在读取原始字节后校验时间窗口、恒时比较签名、按事件 ID 去重，再快速返回 2xx；非 2xx 会重试，投递可重复、也可能晚到。事件载荷不是最终结算依据，任务事件收到后查询 GET /v1/tasks/{id}。

兼容接口

POST /createTask、POST /getTaskResult、POST /getBalance 接受 clientKey JSON 字段；业务成功或失败均可能返回 HTTP 200，必须检查 errorId（0 成功、1 失败）和 errorCode。createTask 支持原生类型及 ImageToTextTask、TurnstileTask、TurnstileTaskProxyless、TurnstileTaskProxyLess、AntiTurnstileTaskProxyLess 别名。

兼容错误可能为 ERROR_KEY_DOES_NOT_EXIST、ERROR_KEY_DENIED_ACCESS、ERROR_IP_NOT_ALLOWED、ERROR_ACCOUNT_SUSPENDED、ERROR_BAD_PARAMETERS、ERROR_TASK_NOT_SUPPORTED、ERROR_NO_SLOT_AVAILABLE、ERROR_ZERO_BALANCE、ERROR_NO_SUCH_CAPCHA_ID 或 ERROR_SERVICE_UNAVAILABLE。兼容创建接口没有幂等键，超时后盲目重试可能再次创建任务和预占余额；新集成应使用 /v1/tasks。

最小接入示例

export SOLVEHUB_URL='https://www.tiam.codes'
export SOLVEHUB_API_KEY='sh_REPLACE_ME'
curl -sS -H "Authorization: Bearer $SOLVEHUB_API_KEY" "$SOLVEHUB_URL/v1/balance"
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、幂等键和 X-Request-ID。不要在日志、截图或工单中提交完整 API Key、充值 Key、密码、TOTP 秘钥或原始代理凭据。

DataDome 挑战 URL 工具

POST /v1/datadome/build-url：要求有效 Key 的 tasks 权限和可用账户，同步返回结果，免费且不创建解题任务。传入 websiteURL（≤ 2048 字节）及 body、location、captchaUrl 至少一个。body 为捕获的 HTML/JSON（≤ 1 MiB）；location 和 captchaUrl 各 ≤ 4096 字节。优先采用已提供的 captchaUrl。不要传入内部服务的凭据。

curl -sS -X POST 'https://www.tiam.codes/v1/datadome/build-url' \
  -H 'Authorization: Bearer sh_REPLACE_ME' \
  -H 'Content-Type: application/json' \
  --data '{"websiteURL":"https://example.com/login","body":"{\"url\":\"https://geo.captcha-delivery.com/captcha/?cid=EXAMPLE\"}"}'

{"captchaUrl":"https://geo.captcha-delivery.com/captcha/?cid=EXAMPLE","challengeType":"captcha"}

成功返回 captchaUrl,challengeType；URL 原样用于 DataDome 解题任务。错误：400 INVALID_DATADOME_PAYLOAD、422 DATADOME_CHALLENGE_NOT_FOUND、503 DATADOME_BUILDER_UNAVAILABLE（稍后退避重试）、502 DATADOME_BUILDER_FAILED。兼容 POST /buildDataDomeUrl 在 JSON 中传 SolveHub 的 clientKey，使用 HTTP 200 和 errorId/errorCode/errorDescription。此工具不需要 Idempotency-Key；解题任务仍使用原有幂等和计费规则。

浏览器支持范围和可复制的 UA 示例见支持的 User-Agent。处理软时限从任务确认受理后起算；DataDome 为 240 秒，PerimeterX 为 210 秒。

可选查询参数 keyId 可用于 GET /v1/tasks 和 GET /v1/usage，仅筛选当前客户对应 Key 的任务；省略时仍按原方式汇总全部 Key。任务响应的 keyId 为 Key ID，非密钥明文；历史任务可能省略该字段。GET /v1/ledger 支持 kind（credit,reserve,capture,refund,fee,reversal,adjustment）在全部历史流水中筛选，翻页时请保留相同的 kind。