用戶端/pi

在 pi 中使用 Wokey API

取得 Wokey API 金鑰，將 pi 的 Base URL 指向 Wokey，再用一個 curl 請求確認連線。

更新於

本頁內容expand_more

準備 API 金鑰與 Base URLlink

所有用戶端都使用同一組 Wokey API 金鑰和同一個 Base URL。

建立 API 金鑰

登入後在 API 頁面建立平台金鑰；同一帳號下的金鑰共用餘額。

建立 API 金鑰key

使用 Wokey Base URL

用戶端的 Base URL 填入閘道網域；是否加上 /v1 請參考下方設定。

設定用戶端link

pi 從 models.json 讀取自訂供應商。下方設定透過 Anthropic Messages 呼叫 Claude 模型；GPT、DeepSeek 等其他模型，請另外新增一個 api 設為 openai-completions、baseUrl 以 /v1 結尾的供應商。

  1. 1

    匯出 API 金鑰

    在啟動 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"] }
      ]
    }
  }
}

API 格式與 Base URLlink

同一個用戶端切換 API 格式時，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 排除金鑰與 Base URL 的問題。

pi 預設使用 Anthropic Messages 格式。這個請求回傳 200，代表金鑰和 Base URL 都正確；送出前請把 YOUR_API_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

金鑰缺少、輸入錯誤、已刪除，或 Authorization 與 x-api-key 標頭內容衝突。

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

用戶端在回應完成前關閉了連線（代碼 downstream_aborted）。預設不收費。當帳號在過去 24 小時內至少有 50 次用戶端中斷，且占其請求的 10% 以上時，之後中斷的請求會依上游回報的用量計費：已處理的輸入（含快取讀取與寫入），以及僅在上游有計入時的輸出。在上游回報任何用量之前就中斷的請求仍然免費。開始計費時會通知帳號，中斷率恢復正常後一小時內會自動停止計費。常見原因是用戶端或代理的逾時設定太短，或程式在請求完成前就取消了請求。

502

upstream unavailable

上游模型服務暫時無法使用。請切換模型或稍後重試。

504

upstream timeout

上游回應逾時。請縮短上下文、調低 max_tokens 或重試。

529

upstream overloaded

上游模型暫時過載，Wokey 已經在其他路由上重試過（代碼 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 金鑰時不會列出自訂模型。如果 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 金鑰可以不寫進檔案嗎？
可以。apiKey 支援 $NAME 形式的環境變數，也支援從指令輸出讀取金鑰的 !command 形式。