Pi を apmix で使う
約 2 分で、Pi を apmix のキーで動かせます。キーを一度貼り付ければ、下のスニペットはすべてそのままコピーでき、カタログのどのモデルでも使えます。
ベース URL
https://api.apmix.ai/v1OpenAI 互換Chat Completions と Responses。Codex、Cursor、OpenCode、Kilo Code、Pi、Kimi、Grok、Hermes、各種 SDK 向け。
https://api.apmix.aiAnthropic 互換Messages API。Claude Code と Anthropic SDK 向け。
セットアップ
キーを取得 →- base_url
- https://api.apmix.ai/v1
- api_key
- apx_live_YOUR_KEY
- model
- claude-sonnet-5
Pi をインストールする
Node.js が必要です。インストーラースクリプトは macOS と Linux 専用です。
curl -fsSL https://pi.dev/install.sh | shmodels.json に apmix を登録する
Pi はカスタムプロバイダーを
~/.pi/agent/models.jsonから読み込みます。apmix のモデルはすべてopenai-completionsで動作します。ほかの ID を使うには、modelsにエントリーを追加してください。mkdir -p ~/.pi/agent [ -f ~/.pi/agent/models.json ] && cp ~/.pi/agent/models.json ~/.pi/agent/models.json.bak cat > ~/.pi/agent/models.json <<'EOF' { "providers": { "apmix": { "baseUrl": "https://api.apmix.ai/v1", "api": "openai-completions", "apiKey": "apx_live_YOUR_KEY", "models": [ { "id": "claude-sonnet-5", "name": "Claude Sonnet 5", "contextWindow": 200000, "maxTokens": 32000 } ] } } } EOF上にキーを貼り付けると、ここに自動で入力されます
実行する
Pi を起動し、
/modelでモデルを選びます。モデル選択を開くたびに、ファイルが再読み込みされます。ターミナルcd your-project pi
動作確認
キーが使えるか確認しましょう。
キーでアクセスできるモデルの一覧を取得します。JSON のリストが返れば、キーと URL は正しく設定されています。401 が返った場合は、キーが間違っているか期限切れです。
curl https://api.apmix.ai/v1/models -H "Authorization: Bearer apx_live_YOUR_KEY"上にキーを貼り付けると、ここに自動で入力されます
お使いのツールが一覧にありませんか?
OpenAI または Anthropic のベース URL を設定できるツールなら、どれでも apmix で使えます。Base URL や Custom provider といった項目を探して URL とキーを貼り付け、カタログにあるモデル ID を指定してください。
API を直接使う方法を見るそれでも解決しない場合は、ツール名とリクエスト ID を添えて support@apmix.ai までメールしてください。
エラー
すべてのエラーと、そのステータスコード、対処法。
API は標準の HTTP ステータスと、エラーの種類を示す JSON ボディを返します。code は変わることがないので、判定に使えます。message は人が読むための説明です。すべてのレスポンスには x-apmix-request-id ヘッダーも付いています。support@apmix.ai に問い合わせる際は、この値を添えてください。
エンドポイントによって異なる 2 つの形式
/v1/chat/completions、/v1/responses、/v1/models、/v1/usage)HTTP/1.1 429 Too Many Requests
x-apmix-request-id: req_5b1f…
{
"error": {
"message": "Your monthly allowance is used up. …",
"type": "insufficient_quota",
"code": "allowance_exhausted",
"param": null
}
}/v1/messages、/v1/messages/count_tokens)HTTP/1.1 429 Too Many Requests
x-apmix-request-id: req_5b1f…
{
"type": "error",
"error": {
"type": "rate_limit_error",
"message": "Your monthly allowance is used up. …",
"code": "allowance_exhausted"
}
}- 400
invalid_jsoninvalid_request_error
発生する状況: リクエストボディを JSON として解析できませんでした。
対処法: 引用符、カンマ、
Content-Type: application/jsonヘッダーを確認してください。 - 400
missing_modelinvalid_request_error
発生する状況: リクエストに
modelフィールドがありません。対処法: カタログにあるモデル ID を指定してください(例:
claude-sonnet-4-6)。 - 400
bad_requestinvalid_request_error
発生する状況: モデルがパラメーターを拒否しました(型の誤り、未対応のオプション、内容が長すぎるなど)。
対処法:
messageを確認してください。モデルが示した理由がそのまま記載されています。パラメーターを修正して再送してください。
- 401
missing_api_keyauthentication_error
発生する状況: キーが送信されていません。カタログの内容はプランによって異なるため、
GET /v1/modelsを含むすべてのエンドポイントでキーが必要です。対処法:
Authorization: Bearer apx_live_…を送信してください(Anthropic エンドポイントではx-api-key)。 - 401
invalid_api_keyauthentication_error
発生する状況: キーが存在しないか、削除されています。
対処法: 「ダッシュボード → API キー」からもう一度コピーするか、新しいキーを作成してください。
- 401
key_expiredauthentication_error
発生する状況: 作成時に設定した有効期限をキーが過ぎています。
対処法: 新しいキーを作成してください。有効期限は延長できません。
- 403
model_not_in_planpermission_error
発生する状況: モデルは存在しますが、より上位のプランが必要か、アカウントにまだプランがありません。
messageには、モデル名、必要なプラン、キーが属するプランが記載されます。対処法: 同じキーで
GET /v1/modelsを呼び出す(プランで使えるモデルだけが一覧表示されます)か、「ダッシュボード → 請求」でアップグレードしてください。 - 403
account_suspendedpermission_error
発生する状況: 規約違反により、アカウントが停止されています。
対処法: アカウントに登録したメールアドレスから support@apmix.ai にメールしてください。
- 403
account_on_holdpermission_error
発生する状況: アカウントの支払いを確認中です。確認が済むまで、リクエストは一時停止されます。
対処法: お客様側での対応は不要です。メールをお待ちください。1 日以上かかる場合は support@apmix.ai までご連絡ください。
- 404
model_not_foundnot_found_error
発生する状況: モデル ID が不明か、提供が終了しています。
対処法:
/v1/modelsまたは「モデル」ページにある ID を使ってください。anthropic/のようなベンダーのプレフィックスも使えます。 - 404
not_foundnot_found_error
発生する状況: パスまたはメソッドが存在しません。
対処法:
POST /v1/chat/completions、POST /v1/responses、POST /v1/messages、GET /v1/models、GET /v1/usageのいずれかを使ってください。
- 429
allowance_exhaustedinsufficient_quota · rate_limit_error
発生する状況: 今月の加重トークンを使い切りました。
typeは OpenAI と同じくinsufficient_quotaです。対処法: 「ダッシュボード → 請求」でアップグレードするか、「概要」ページに表示されている更新日までお待ちください。
- 429
daily_limit_reachedrate_limit_error
発生する状況: 「設定 → 上限」でご自身が設定した 1 日の上限に達しました。
対処法: 上限を引き上げるか解除するか、UTC の午前 0 時までお待ちください。
- 429
weekly_limit_reachedrate_limit_error
発生する状況: 「設定 → 上限」でご自身が設定した 1 週間の上限に達しました。
対処法: 上限を引き上げるか解除するか、月曜日の 00:00 UTC までお待ちください。
- 429
key_limit_reachedinsufficient_quota · rate_limit_error
発生する状況: キーの所有者がダッシュボード → API キーで設定した使用量の上限に達しました。
typeはinsufficient_quotaです。対処法: キーの所有者に使用量の上限を引き上げるか解除してもらってください。すぐに再び使えるようになります。
- 429
rate_limit_exceededrate_limit_error
再試行可発生する状況: 1 つのキーで、1 分間に 60 件(Max では 120 件)を超えるリクエストがありました。
対処法:
retry-after秒待ってください。負荷の高い処理は複数のキーに分散してください。 - 429
upstream_rate_limitedrate_limit_error
再試行可発生する状況: モデル自体が現在混み合っています。
対処法: 間隔を広げながら再試行してください(1 秒、2 秒、4 秒)。料金は発生していません。
- 502
upstream_errorapi_error
再試行可発生する状況: モデルから壊れた応答、または予期しない応答が返されました。
対処法: 一度再試行し、繰り返し発生する場合は別のモデルをお試しください。料金は発生していません。
- 503
upstream_unavailableapi_error · overloaded_error
再試行可発生する状況: モデルがタイムアウトしたか、メンテナンスで停止しています。
対処法: 少し待って再試行するか、モデルを切り替えてください。料金は発生していません。
- 503
no_providerapi_error · overloaded_error
再試行可発生する状況: 当社側でこのモデルに有効なルートがありません(まれに、メンテナンス中に発生します)。
対処法: 数分後に再試行するか、別のモデルを選んでください。
「再試行可」のエラーは一時的なものです。1~2 秒待ってから、同じリクエストをもう一度送信してください(ほとんどの SDK は 429 と 5xx で自動的に再試行します)。それ以外のエラーは、先にリクエストや設定を修正する必要があります。
役立つレスポンスヘッダー
- x-apmix-request-id
- このリクエストの一意の ID。support@apmix.ai にメールするときに添えてください。
- x-apmix-remaining
- このリクエストの後、月間利用枠に残っている加重トークン数。
- x-apmix-key-remaining
- 使用量の上限があるキーの、残りの加重トークン数。
- x-apmix-weighted-tokens
- このリクエストで消費した量(モデルの倍率を適用後)。
- retry-after
- 待機すべき秒数。
rate_limit_exceededとともに送られます。