ZCode 接入 apmix
ZCode 约 2 分钟即可用上你的 apmix 密钥。密钥只需粘贴一次,下方每个代码片段都可直接复制,目录中的任何模型都能用。
Base 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
- glm-5.3
打开模型设置
打开底部的模型选择器,点击 Manage models,选择一个服务商,并在右上角切换到 API Key 模式。
设置 Base URL
OpenAI 协议用 OpenAI URL,Claude 模型用 Anthropic URL。
配置值OpenAI Base URL https://api.apmix.ai/v1 Anthropic Base URL https://api.apmix.ai粘贴密钥并添加模型
粘贴 apmix 密钥,点击 Add Model,输入完全一致的 ID。ZCode 会把它保存在
~/.zcode/v2/config.json中。配置值API key apx_live_YOUR_KEY Model glm-5.3在上方粘贴密钥即可自动填入
验证
确认密钥可用。
列出你的密钥能访问的模型。返回 JSON 列表说明密钥和 URL 都正确;返回 401 说明密钥错误或已过期。
curl https://api.apmix.ai/v1/models -H "Authorization: Bearer apx_live_YOUR_KEY"在上方粘贴密钥即可自动填入
没有你用的工具?
任何允许设置 OpenAI 或 Anthropic Base URL 的工具都能用 apmix。找到 Base URL 或自定义服务商(Custom provider)字段,粘贴 URL 和密钥,再使用目录中的模型 ID 即可。
查看通用 API 示例还是卡住了?发邮件至 support@apmix.ai,附上工具名称和请求 ID。
错误
每个错误、对应的状态码,以及该怎么做。
API 以标准 HTTP 状态码加一个说明错误的 JSON 体作答。code 永不改变,可以放心用来匹配;message 是写给人读的。每个响应还带有 x-apmix-request-id 头,写信给 support@apmix.ai 时请附上。
两种格式,取决于端点
/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
何时发生: 账号的一笔付款正在核查,核查期间请求会暂停。
该怎么做: 你无需做任何操作。请留意邮件;若超过一天仍未恢复,请写信至 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
何时发生: 你本月的权重 token 已用完。
type为insufficient_quota,与 OpenAI 一致。该怎么做: 在「控制台 → 账单」中升级,或等待概览页显示的续费日期。
- 429
daily_limit_reachedrate_limit_error
何时发生: 你达到了自己在「设置 → 限额」中设置的每日上限。
该怎么做: 提高或移除上限,或等到 UTC 午夜。
- 429
weekly_limit_reachedrate_limit_error
何时发生: 你达到了自己在「设置 → 限额」中设置的每周上限。
该怎么做: 提高或移除上限,或等到周一 00:00 UTC。
- 429
key_limit_reachedinsufficient_quota · rate_limit_error
何时发生: 该密钥已达到其所有者在 控制台 → API 密钥 中设置的用量上限。
type为insufficient_quota。该怎么做: 请密钥所有者提高或取消用量上限,密钥会立即恢复可用。
- 429
rate_limit_exceededrate_limit_error
可安全重试何时发生: 单个密钥一分钟内超过 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
可安全重试何时发生: 该模型在我们这边暂时没有可用路由(少见,通常在维护期间)。
该怎么做: 几分钟后重试,或选择其他模型。
标记为「可安全重试」的错误是暂时性的:等一两秒,再发送同样的请求即可(大多数 SDK 在 429 和 5xx 时会自动重试)。其他错误都需要你先在自己这边做出修改。
有用的响应头
- x-apmix-request-id
- 本次请求的唯一 ID。发邮件至 support@apmix.ai 时请附上。
- x-apmix-remaining
- 本次请求之后,你的月额度还剩多少权重 token。
- x-apmix-key-remaining
- 设置了用量上限时,此密钥剩余的加权 token。
- x-apmix-weighted-tokens
- 本次请求的花费,已计入模型倍率。
- retry-after
- 需要等待的秒数;随
rate_limit_exceeded一起返回。