客户端接入/pi

在 pi 中使用 Wokey API

准备好 Wokey API Key，把 pi 的 Base URL 指向 Wokey，再用一条 curl 请求确认连通。

更新于

本页内容expand_more

准备 API Key 与 Base URLlink

所有客户端都用同一个 Wokey API Key 和同一个 Base URL。

创建 API Key

登录后在 API 页面创建平台 Key；同一账户下的 Key 共享余额。

创建 API Keykey

使用 Wokey Base URL

客户端的 Base URL 填网关域名，按下方配置决定是否追加 /v1。

配置客户端link

pi 从 models.json 读取自定义供应商。下面的配置通过 Anthropic Messages 调用 Claude 模型；GPT、DeepSeek 等模型另加一个供应商，api 写 openai-completions，baseUrl 写带 /v1 的地址。

  1. 1

    导出 API Key

    在启动 pi 的终端里执行 export WOKEY_API_KEY="YOUR_API_KEY"，或写进 ~/.zshrc。

  2. 2

    写入 models.json

    把下面的内容保存到 ~/.pi/agent/models.json。文件里已有其他供应商时，只在 providers 下加上 wokey 这一项。

  3. 3

    选择模型

    启动 pi，输入 /model，选择 wokey 下的模型。

pi
{
  "providers": {
    "wokey": {
      "baseUrl": "https://api.wokey.ai",
      "api": "anthropic-messages",
      "apiKey": "$WOKEY_API_KEY",
      "models": [
        { "id": "claude-opus-5-5", "reasoning": true, "input": ["text", "image"] }
      ]
    }
  }
}

协议与 Base URL 写法link

同一个客户端换协议时，Base URL 带不带 /v1 可能不同。

协议Base URL 写法建议用于
Anthropic Messageshttps://api.wokey.aiClaude 模型
OpenAI Chat Completionshttps://api.wokey.ai/v1DeepSeek、GLM、Kimi 等其他模型
OpenAI Responseshttps://api.wokey.ai/v1GPT 模型

配置位置: ~/.pi/agent/models.json

用 curl 验证link

客户端报错时，先用 curl 排除 Key 和 Base URL 的问题。

pi 默认使用 Anthropic Messages 协议。这条请求返回 200，说明 Key 和 Base URL 都正确；发送前把 YOUR_API_KEY 换成你的 Key。

cURL
curl https://api.wokey.ai/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      { "role": "user", "content": "Hello" }
    ]
  }'

错误与排障link

先区分认证、额度、限流、模型不可用和上游超时。

401

invalid api key

Key 缺失、写错、已删除，或 Authorization / x-api-key 认证 Header 冲突。

402

insufficient balance

账户额度不足，需要充值后继续请求。

403

model_denylisted / account_restricted

该模型或整个账号因反复违规被暂停调用，处理方法见「违规处置费与风控限制」。

403

request_blocked

这个请求被拦截，没有发往上游，也不收费。例如原样重发刚被模型拒绝的请求，或某个终端用户（X-End-User-Id）被暂停。报错信息会说明拦截的范围；按提示修改请求或稍后再试，其他请求不受影响。

429

rate limited

请求过于频繁，稍后重试或降低并发。如果只有某一个模型或某一个终端用户（X-End-User-Id）持续返回 429，可能是违规后的临时限流。

499

client disconnected

客户端在响应完成前断开了连接（code 为 downstream_aborted），默认不收费。账号过去 24 小时的客户端断开达到 50 次、并且占全部请求的 10% 以上时，之后断开的请求会自动按上游报告的用量计费：已处理的输入（含缓存读写）照收，输出只在上游给出计数时才收；上游还没报告用量就断开的，仍然免费。开始计费时会通知账号；断开比例回到正常范围后，计费在一小时内自动停止。常见原因是客户端或代理的超时设得太短，或者程序在请求完成前主动取消了它。

502

upstream unavailable

上游模型服务暂不可用，通常可以切换模型或稍后重试。

504

upstream timeout

上游响应超时，建议缩短上下文、降低 max_tokens 或重试。

529

upstream overloaded

上游模型暂时过载，Wokey 已先换线路重试过（code 为 upstream_overloaded），和你的余额无关。稍后重试或切换模型。

常见问题link

pi 的 baseUrl 要不要加 /v1？
看 api 字段。api 为 anthropic-messages 时填 https://api.wokey.ai，不加 /v1；api 为 openai-completions 或 openai-responses 时填 https://api.wokey.ai/v1。
为什么 /model 里看不到 Wokey 的模型？
pi 解析不到 API Key 时不会列出自定义模型。apiKey 写成 $WOKEY_API_KEY 的话，先在启动 pi 的同一个终端里 export WOKEY_API_KEY，再检查 models.json 是不是合法 JSON。/model 每次打开都会重新读取这个文件。
pi 里怎么给 Wokey 的模型发图片？
pi 的自定义模型默认只声明文本输入。给支持图片的模型加上 "input": ["text", "image"]，声明它接受图片输入。
上下文窗口和最大输出要不要改？
不写时 pi 按 contextWindow 128000、maxTokens 16384 处理。模型实际窗口更大时，在模型条目里按模型页上的数值填写 contextWindow 和 maxTokens。
API Key 能不能不写进文件？
可以。apiKey 支持 $NAME 形式的环境变量，也支持 !command 形式，从命令输出里读取 Key。