Pikeway
登录
文档网关API 参考CLI 参考集成
API 参考

概览

Pikeway 的所有接口都在同一个网关域名下:API 代理、能力路由、兼容 OpenAI / Anthropic 的 AI 网关,以及 agent 用来查找、查看和调用端点的 Agent API。

基础地址

Gateway
https://gw.pikeway.ai

本参考中的所有路径都相对于网关基础地址。主要的路由分组:

  • /gw/{slug}/{path} 调用市场里的任意 API(任意方法),按成功调用计费。
  • /cap/{slug} 由多个提供方提供的同一动作,自动故障切换。
  • /ai/v1/… 兼容 OpenAI 和 Anthropic 的大模型接口,按 token 计费。
  • /v1/… Agent API:discover、inspect、run、runs、wallet。
  • /mock/{slug}/{path} 免费示例响应,无需 key,不访问上游。
  • /ws/{slug}/{path} WebSocket 代理(需要 key;见 WebSocket 指南)。

鉴权

API key

在 控制台 → Keys 创建 key,key 以 pk- 开头。以 Bearer token 方式发送;也接受 X-API-Key 请求头。

bash
curl https://gw.pikeway.ai/v1/auth/whoami \
  -H "Authorization: Bearer pk-..."

# equivalent
curl https://gw.pikeway.ai/v1/auth/whoami -H "X-API-Key: pk-..."

网关在转发前会去掉自己的鉴权请求头,你的 Pikeway key 不会被发给上游提供方。每把 key 可以在控制台单独设置限制:

  • 消费上限:用完后付费调用返回 402 api key spend limit reached。
  • IP 白名单(CIDR):其他 IP 返回 403 client IP not allowed for this API key。
  • 过期时间:过期的 key 与已吊销的 key 一样处理(401 invalid or revoked API key)。

浏览器 key

浏览器 key 就是设置了来源白名单的 key。网关用 Origin 请求头(没有时用 Referer)比对白名单;条目是域名,*.example.com 可匹配子域名。没有 Origin/Referer 的请求(例如服务端调用)会被拒绝:403 request origin not allowed for this API key。详见 浏览器 key。

无需 key 的接口

POST /v1/discover、POST /v1/inspect、GET /v1/examples、GET /v1/rankings、GET /ai/v1/models 和 /mock/… 免费,不需要 key。

计费与响应头

付费调用只在成功时收费。在 /gw 上,这意味着上游返回了 2xx(若提供方配置了业务码,还要求 body 里的业务码表示成功)。上游错误、网络故障、超时以及所有网关侧的拒绝都不收费。转发前网关会先在余额里冻结本次价格,不计费时退回。

响应头
X-Pikeway-Call-Idstring
本次调用的唯一 id。即 GET /v1/runs/{id} 的 runId,也会出现在请求日志里。
X-Pikeway-Costdecimal (USD)
本次调用的扣费金额,如 0.001;未计费时为 0。在 /ai/v1 上只在非流式响应中返回。
X-Pikeway-CacheHIT | MISS
响应缓存生效时返回(/gw 上的 GET 请求由提供方开启;/ai/v1/chat/completions 由请求头 X-Pikeway-Cache 显式开启)。/gw 的缓存命中按原价计费。
X-Pikeway-Planstring
对该 API 有有效套餐时,返回本次调用使用的套餐名。
X-Pikeway-Quota-Remaininginteger
本次调用后套餐含量里剩余的调用次数。
X-Pikeway-Volume-Discountpercent
本次按次付费请求适用的阶梯折扣。
X-Pikeway-Byok1
本次调用使用了你自己的上游 key(控制台 → Connections),不收费。
X-Pikeway-Upstream-Attemptsinteger
网关切换到备用上游时,实际尝试的上游次数。
X-Pikeway-Upstream-Errorstring
上游 2xx 响应为何被判为失败且不收费:business-code、graphql-errors 或 grpc-status-N。
X-Pikeway-Tokensprompt+completion
/ai/v1 非流式响应的 token 用量,如 812+64。
X-Pikeway-Capability / -Routed-To / -Attemptsstring
/cap 响应上:能力名、实际提供服务的 API,以及每次尝试(api:状态码)。
X-Pikeway-Mocktrue
该响应来自 /mock 的免费模拟(费用为 0)。

浏览器代码可以通过 CORS 读取这些响应头,但 X-Pikeway-Byok、X-Pikeway-Upstream-Attempts 和 X-Pikeway-Upstream-Error 不在暴露列表中。

请求与响应

  • 透传。/gw 和 /cap 原样返回提供方的状态码、响应头和 body(外加上面的响应头)。请求 body、查询参数和请求头原样转发,只去掉 Pikeway 的鉴权头。
  • Agent API。/v1/* 收发 JSON。价格和费用是 {"value": 0.001, "currency": "USD"} 这样的对象;时间戳为 UTC 的 RFC 3339 格式。
  • 幂等。在付费的 /gw 调用上带 Idempotency-Key(最长 255 字符),同一把 key 下网关最多转发并扣费一次;重复使用返回 409。
  • 错误。网关错误是带 error + statusCode 的 JSON;Agent API 错误使用 code + message。见 错误码。

分页

GET /v1/runs 和 GET /v1/wallet/activities 使用游标分页,按时间倒序。传入 limit(默认 20,最大 100)和上一页返回的 cursor。响应格式为 {"items": [...], "cursor": "..."},最后一页的 cursor 为 null。游标是不透明字符串。

bash
curl "https://gw.pikeway.ai/v1/runs?limit=50" -H "Authorization: Bearer pk-..."
curl "https://gw.pikeway.ai/v1/runs?limit=50&cursor=MjAyNi0xMC0yNFQwOToxMjo..." -H "Authorization: Bearer pk-..."

端点

网关

ANY/gw/{slug}/{path}
调用市场里的任意 API。
ANY/mock/{slug}/{path}
端点的免费示例响应。
GET/cap/{slug}
执行能力,带提供方故障切换。

AI 网关

POST/ai/v1/chat/completions
OpenAI Chat Completions。
POST/ai/v1/messages
Anthropic Messages。
POST/ai/v1/messages/count_tokens
Anthropic token 计数(免费)。
POST/ai/v1/responses
OpenAI Responses。
GET/ai/v1/models
列出模型及价格。

Agent API

POST/v1/discover
用自然语言搜索端点。
POST/v1/inspect
单个端点的输入 schema、价格和示例。
POST/v1/run
调用端点,同步或异步。
GET/v1/runs
列出你的运行记录。
GET/v1/runs/{runId}
获取单个运行。
POST/v1/runs/{runId}/stop
停止异步运行。
GET/v1/wallet/balance
余额与 key 预算。
GET/v1/wallet/activities
余额流水。
GET/v1/auth/whoami
key 对应的账户和 key 信息。

其他公开接口

GET/v1/examples
现成的 agent 任务示例,含所用端点和预估费用;/v1/examples/{slug} 获取单个。
GET/v1/rankings
最常用的 API。参数:window(24h | 7d | 30d,默认 7d)、category、limit(默认 30,最大 100)。
GET/health
网关状态与版本。
GET/SKILL.md
Agent skill 文件(也可用 /skill.md)。
GET/llms.txt
给 LLM 读的目录摘要。
POST/mcp
MCP 服务,用 Authorization: Bearer pk-… 鉴权;/mcp/agent 使用 OAuth 登录。
HTTP API 快速开始
一分钟完成第一次付费调用。
错误码
网关返回的所有状态码,以及是否扣费。
自托管(社区版)网关不计费:所有费用为 0,也不做余额检查。
下一页
错误码