快速开始

三个动词，配上与 API 今天真实接受的形状一致的请求示例。

每个请求都需要 API key。目前还没有公开注册入口——这一页说明 API 做什么，而不是一个你今天能注册的产品。

Authorization: Bearer sk_live_…

discover — 选哪个能力

curl -s https://sealyx.ai/v1/discover \
  -H "authorization: Bearer $SEAL_KEY" \
  -H 'content-type: application/json' \
  -d '{"query":"把网页抓成 markdown","limit":5}'

返回候选项，含 id、描述和价格。它回答的是选哪个，并且刻意不返回调用 schema——后者体积大两个数量级，为了回答一次搜索而返回五份 schema 会把答案埋掉。

inspect — 怎么调

curl -s https://sealyx.ai/v1/inspect \
  -H "authorization: Bearer $SEAL_KEY" \
  -H 'content-type: application/json' \
  -d '{"id":"monid:context.dev/web/scrape/markdown"}'

返回输入 schema，外加 guidance——那些 JSON Schema 表达不了的散文规则，比如“要先注册素材”或“这个模型的时长必须在 5–12 秒之间”。只给 schema，足够让人构造出一个类型正确但注定失败的请求。

run — 花钱

curl -s https://sealyx.ai/v1/run \
  -H "authorization: Bearer $SEAL_KEY" \
  -H "idempotency-key: $(uuidgen)" \
  -H 'content-type: application/json' \
  -d '{
    "capabilityId": "monid:context.dev/web/scrape/markdown",
    "input": { "queryParams": { "url": "https://example.com" } },
    "maxCostMicros": 5000
  }'

这个请求里有三件事不是可选的：

idempotency-key 是必填请求头，8–255 字符。上游自己没有幂等机制——两次完全相同的 POST 会产生两个 run 和两次扣费——所以 sealyx 完全靠自己的状态保证至多一次，而这个保证就以这个头为键。用同一个 key 配不同的 body 会返回 409。

maxCostMicros 必填，且不得低于该能力的已知下限（上面这个例子是 900）。没有服务端已知的下限，对一个 900 micros 的能力声明 maxCostMicros: 1就能把准入控制击穿 900 倍。

input 要和 inspect 返回的形状完全一致。 上游的 body schema 很严格，出现未知字段会直接拒绝。

你会被收多少

maxCostMicros 是上限，不是估价。sealyx 在联系任何人之前先按它预留，事后按真实成本结算。如果上游收得比你声明的多，你按自己的上限付费，超出部分算我们的。

如果 sealyx 无法确定上游到底跑没跑你的任务，预留会被保留、run 标记为 UNKNOWN，而不是释放——多扣着的预留是可见且可恢复的，错误释放的则不是。后台清道夫会处理这些；永远无法确定的会被关成 ABANDONED，在没有证据表明上游接过活时扣费为零。

查询一次运行

curl -s https://sealyx.ai/v1/runs/run_… -H "authorization: Bearer $SEAL_KEY"
curl -s https://sealyx.ai/v1/runs      -H "authorization: Bearer $SEAL_KEY"

GET /v1/health 是唯一不需要 key 的路由——一个需要凭证的存活探针不是存活探针。