开发者文档

认证

Bearer API Key

# 所有 /v1 请求携带 qak_ key
Authorization: Bearer qak_****

# 立即验证 key 与余额
curl https://api.quasar.oreoking.cn/v1/credits/balance \
  -H "Authorization: Bearer qak_****"

Key 支持轮换双活（新旧 key 并存一个宽限期）与吊销（即时 401）；default key 不出现在列表中。双层限流：账户级 + key 级，超限返回 429 与 retry-after。

REST /v1

常用端点

端点	方法	说明
`/v1/scrape`	POST	同步采集（engine: http / browser / auto）；带 `async:true` 时 202 + webhook 回调
`/v1/tasks/{id}`	GET	任务状态与结果（异步模式）
`/v1/sessions`	POST	创建浏览器会话（指纹 / 出口 / jar 固化）
`/v1/sessions/{id}/command`	POST	会话动词：navigate / snapshot / click / type / eval / network / cookies…
`/v1/jars` 系列	POST	Cookie Jar 生命周期：bind（冒号动作）、verify、export
`/v1/guided-login`	POST	创建人机协同登录任务，返回 view_url + control_token
`/v1/usage` · `/v1/credits/balance`	GET	用量聚合（按日）与余额
`/v1/proxies/catalog`	GET	出口资源可用性（geo × IP 类型）
`/v1/assets/fetch`	POST	资产重签下载 URL

注：字段命名以服务端实际行为为准（如 cookie jar 用 jar 寻址）；端点契约如有调整，会在发布说明中提前公告。

响应信封

一次 scrape 的完整回执

{
  "id": "scrape_a99caeddda",
  "execution_id": "01a08be2-d503-7b6e-82b2-9f4e51895133",
  "status": "completed",          // completed | blocked | failed
  "block": null,                    // 被拦时：category / evidence / hint
  "data": { "markdown": "# Example Domain\n…" },
  "warnings": [],
  "assets": [ { "kind": "screenshot", "id": "shot_…" } ],
  "execution": { "engine": "http", "attempts": 1, "plugins": […] },
  "usage": { "credits": 1, "breakdown": { "http_scrape": 1 } },
  "logs": { … }                     // 任务级日志入口
}

CLI

命令组一览

三层帮助：--help 常用参数 → scrape --help all 全参数 → scrape --help <topic> 主题深读。退出码：0 成功 / 1 业务失败 / 2 用法错误。

命令	用途	常用形态
`login / logout`	凭证管理	`quasar --api-key K --base-url U login`（全局参数在子命令前）
`scrape`	采集 URL	`quasar scrape <url> -O dir/ --output markdown --output screenshot`
`session`	浏览器会话	create · snapshot · click --ref · type --text · eval --expr · network · cookies · close
`jar`	Cookie Jar	create · bind --cookies-file · verify · delete
`gl`	guided-login	create --site --jar --check · status · finish --control-token · cancel
`proxy / fingerprint / plugin`	目录查询	list / show
`usage`	用量与余额	`quasar usage`（按日聚合）
`asset`	资产下载	`quasar asset fetch <asset_id> -o file.png`

错误处理

错误码速查

HTTP	code	含义与动作
401	`unauthorized`	key 无效或被吊销 → 换 key / 轮换
402	`insufficient_credits`	余额不足 → 充值或调账
409	`account_disabled`	账户被禁用 → 联系支持
422	`ssrf_blocked`	目标解析到内网/保留段 → 换公网目标
422	`blocked`	反爬拦截（不计费）→ 读 block.hint 决定升级/重试
429	`rate_limited`	限流 → 按 retry-after 退避
503	`farm_unavailable`	浏览器农场暂不可用 → 稍后重试

异步与回调

Webhook（HMAC 签名）

怎么接

请求体带 webhook_url（或在 Web UI 设置默认回调）。任务终态时 POST 通知，头带 X-Quasar-Signature（HMAC，密钥为账户 webhook secret），请验签后消费。

失败怎么办

指数退避重试 5 次，仍失败进死信（DLQ）；Web UI 设置页可查看投递历史并一键重放。投递失败不影响任务结果本身。