← 返回 KasadaKASADA / API DOCUMENTATION

Kasada

受保护页面访问与动态请求参数生成。

在线测试 API 接口文档

PAGEmode: page

页面验证

执行入口挑战并在同一 Session 重载页面，返回 Cookie、页面摘要与验收项。

目标: 受保护的 HTML 页面
证据: HTML 200 + Kasada 证据
返回: cookies / verification_checks

GENERATEmode: generate

请求参数生成

执行当前 SDK，截获目标请求描述；返回本轮 headers、Cookie 与 body，不发送最终业务请求。

目标: 受保护的 API 或页面
状态: 参数已生成，不代表业务验证通过
返回: headers / cookies / body_base64

Request reference

鉴权与请求参数

POST /solver/v1/solve/kasada
X-API-Key: capi_live_…

参数	类型 / 默认值	说明
url	string · 必填	公网 HTTP / HTTPS URL，8–2048 字符；page 模式为页面，generate 模式为最终业务 URL。
mode	page / generate · page	页面验证或仅生成参数；generate 不发送最终业务请求。
page_url	string / null · null	generate 模式加载 SDK 的页面；默认使用 url。
method	string · GET	generate 支持 GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS；page 仅 GET。
headers	object · {}	generate 的业务头，最多 50 项、总计 32 KiB；运行时管理 Host、Cookie、UA、连接、sec-* 与 x-kpsdk-*，不能覆盖。
body	string / null · null	generate 的原始 UTF-8 字符串，最多 64 KiB；JSON body 先序列化为字符串。
proxy	string / null · null	http://、https://、socks5://、socks5h://；必须指定公网主机与端口，支持用户名密码。
cookies	object · {}	最多 50 项字符串 Cookie，值最多 8192 字符；绑定初始页面域名。
timeout	number · 30	单请求超时，1–60 秒。
flow_timeout	number · 180	流程超时，10–300 秒；排队与进程启动另计，客户端建议至少等待 360 秒。

代理与运行边界

仅用于自有或已获授权目标。目标、SDK 资源、代理与每次重定向均校验公网地址并固定 DNS；HTTP(S) 代理需支持 CONNECT。拒绝本机、内网、云元数据地址和跨来源重定向；如网站跨域跳转，请填写最终页面地址。代理留空明确直连，不继承服务器环境代理。

本服务使用一次性独立会话。生成结果不是“通用 token”，也不提供持久 Session 或业务自动重试；复用时保持同一出口、返回的 User-Agent、Cookie、请求头与原始 body。站点业务初始化和最终结果验收由调用方完成，不能保证任意站点或 SDK 版本均兼容。

当前 ksd_env 0.5.1 的部分 DOM、iframe 与 Worker 原生回归尚未通过；已验证的离线参数生成不代表任意站点可用，实际请求可能因兼容性不足而失败。

Quick start

请求示例

与现有服务使用相同的 WANXIANG_API_KEY。

Python · 页面验证

import os
import requests

response = requests.post(
    "https://your-host/solver/v1/solve/kasada",
    headers={"X-API-Key": os.environ["WANXIANG_API_KEY"]},
    json={
        "mode": "page",
        "url": "https://your-authorized-site.example/page",
        "proxy": os.getenv("KASADA_PROXY") or None,
        "timeout": 30,
        "flow_timeout": 180,
    },
    timeout=360,
)
response.raise_for_status()
result = response.json()
print(result["verification_checks"])
print(result["cookies"])

Python · 仅生成参数

import base64
import json
import os
import requests

response = requests.post(
    "https://your-host/solver/v1/solve/kasada",
    headers={"X-API-Key": os.environ["WANXIANG_API_KEY"]},
    json={
        "mode": "generate",
        "url": "https://api.your-authorized-site.example/items",
        "page_url": "https://your-authorized-site.example/search",
        "method": "POST",
        "headers": {"Content-Type": "application/json"},
        "body": json.dumps({"query": "sample"}),
        "proxy": os.getenv("KASADA_PROXY") or None,
    },
    timeout=360,
)
response.raise_for_status()
parameters = response.json()
assert parameters["parameters_generated"]
assert parameters["business_request_sent"] is False
body = base64.b64decode(parameters["body_base64"])
print(parameters["headers"])
# 最终业务请求由调用方使用相同代理、UA、Cookie、headers 和原始 body 发送。
# 参数生成成功不代表业务请求已通过验证。

cURL

curl 'https://your-host/solver/v1/solve/kasada' \
  -H "X-API-Key: $WANXIANG_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"mode":"page","url":"https://your-authorized-site.example/page"}' \
  --max-time 360

Response reference

响应与计费

公共字段：service=kasada、mode、user_agent、proxy_enabled、session_request_count、total_elapsed_seconds、request_id、quota（limit / used / remaining）。

page：verification_passed=true、verification_status、verification_url、verification_checks、challenge_solved、cookies、page_title、page_sha256、page_bytes。检查 HTML、状态和 Kasada 证据；不返回整个网页，且不代表网站业务数据验收已完成。

generate：parameters_generated=true、business_request_sent=false、verification_passed=false、url、method、headers、cookies、cookie_header、body_base64。body_base64 解码后是实际请求 bytes。

401 / 403：鉴权或登录失败；422：参数或访问策略不符；429：额度不足；502：上游拒绝、代理失败或未完成流程；503：模块未就绪（不扣费）；504：超时，charged=false、charge_units=0，自动退还本次额度。其余已受理请求按现有规则扣 1 单位；generate 的“参数已生成”也计一次调用。成功响应包含 X-RateLimit-Limit 和 X-RateLimit-Remaining。取消页面等待不等于服务端超时，不自动退费。