开发文档

把模型接入这件事说清楚

从模型广场复制模型名或配置，按这里的 Base URL 和 Key 接入。文档只保留真正会影响调用、计费和排障的内容。

OpenAI 兼容一个 Key 调用全部模型价格公开可对账

最小配置OpenAI-compatible

quickstart.sh

export APIEX_API_KEY="sk-..."

curl https://apiex.cc/gateway/v1/chat/completions \
  -H "Authorization: Bearer $APIEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-max",
    "messages": [
      {"role": "user", "content": "hi"}
    ]
  }'

Base URLhttps://apiex.cc/gateway/v1

鉴权Authorization: Bearer $APIEX_API_KEY

模型 ID从模型广场复制，避免手写出错

价格口径USD / 1M tokens，人民币仅作估算展示

OpenAI SDK

替换 baseURL、API Key 和 model 即可接入。

CLI / Agent

Claude Code、Codex、Cursor 等工具配置集中放在这里。

模型选择

按场景、厂家、价格和访问延迟选择模型。

快速开始

1. 创建 API Key

进入控制台并完成登录。
进入 API Key 管理页面，创建一个新的密钥。
确认账户有可用余额或企业额度。

2. 选择模型

进入模型广场，按供应商、上下文长度、输入输出价格、能力标签选择模型。接入初期建议先使用显式模型 ID。

3. 验证连通性

connectivity.sh

export APIEX_API_KEY="sk-xxxxxxxx"

curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Bearer $APIEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-5.2","messages":[{"role":"user","content":"hi"}]}' \
  https://apiex.cc/gateway/v1/chat/completions

标准接入与通用配置

apiex 网关 OpenAI 兼容。任何 SDK、CLI 或 Agent 工具，接入只涉及下面三个字段——全文只在这里定义一次，各工具章节只写差异点。

API Key	控制台创建的 `sk-...` 密钥，建议写入环境变量 `APIEX_API_KEY`，不要提交到仓库。
Base URL	统一填 `https://apiex.cc/gateway/v1`；部分工具要求填到版本段之前、由工具自行拼接 /v1，此时填 `https://apiex.cc/gateway`，两种写法等价。不要把完整接口路径写进 Base URL。
模型 ID	使用模型广场中的 `provider/model-name` 格式，从模型广场复制，避免手写出错。

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["APIEX_API_KEY"],
    base_url="https://apiex.cc/gateway/v1",
)

completion = client.chat.completions.create(
    model="openai/gpt-5.2",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "how are you?"}
    ],
)

print(completion.choices[0].message.content)

下面各工具章节均以上表为准；「Base URL 填到 /gateway」特指会自行拼接 /v1/messages 的 Anthropic 系工具。

IDE 与 CLI 接入

以下工具都在「标准接入与通用配置」三字段基础上工作，本组只列各工具的差异点。

Claude Code

Anthropic 兼容工具：Base URL 填到 https://apiex.cc/gateway（不带 /v1），由 CLI 自行拼接 /v1/messages。

持久配置（推荐）

~/.claude/settings.json

mkdir -p ~/.claude

cat > ~/.claude/settings.json <<'EOF'
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://apiex.cc/gateway",
    "ANTHROPIC_API_KEY": "sk-xxxxxxxx",
    "ANTHROPIC_MODEL": "anthropic/claude-sonnet-4.6"
  },
  "includeCoAuthoredBy": false
}
EOF

claude /logout 2>/dev/null || true
unset ANTHROPIC_AUTH_TOKEN

出现认证冲突时，确认本机没有同时设置 OAuth Token 和 API Key，只保留一种认证方式。

临时接入（环境变量）

claude.env

export ANTHROPIC_BASE_URL="https://apiex.cc/gateway"
export ANTHROPIC_API_KEY="sk-xxxxxxxx"

claude

团队协作时建议把结构化配置提交到仓库，把真实密钥放进本地 .local 配置或系统密钥管理中。

Codex CLI

差异点：使用 Responses API（wire_api = "responses"），配置写在用户级 ~/.codex/config.toml。

~/.codex/config.toml

mkdir -p ~/.codex

cat > ~/.codex/config.toml <<'EOF'
model_provider = "apiex"
model = "openai/gpt-5.2"

[model_providers.apiex]
name = "apiex"
base_url = "https://apiex.cc/gateway/v1"
env_key = "APIEX_API_KEY"
wire_api = "responses"
requires_openai_auth = false
EOF

export APIEX_API_KEY="sk-xxxxxxxx"
codex

如果 /responses 报 404，优先检查 wire_api = "responses" 和 Base URL，不要把完整接口路径写进 base_url。

Cursor

打开 Cursor 设置，进入 Models。
添加自定义模型，模型 ID 使用模型广场中的 provider/model-name 格式。
打开 OpenAI API Key 开关，填写 apiex Key。
Base URL 按通用配置填写（https://apiex.cc/gateway/v1；工具自拼 /v1 时填 https://apiex.cc/gateway）。
保存后在 Chat、Composer 或 Agent 中选择对应模型。

Claude Desktop

差异点：桌面客户端通常经本地 MCP 或工具代理接入，把 apiex Key 放在本机环境变量中，再由工具配置读取。

desktop.env

export APIEX_API_KEY="sk-xxxxxxxx"
export APIEX_BASE_URL="https://apiex.cc/gateway/v1"

如果客户端仍连接官方域名，检查工具配置是否读取了旧的环境变量或本地缓存。

Hermes / QClaw / AutoClaw

差异点：这类 Agent 工具直接支持 OpenAI 兼容配置，无专属配置文件，把通用配置三字段填进工具设置即可：

API Key	`APIEX_API_KEY` 或工具支持的自定义环境变量（填真实 Key 值即可，变量名无需复制）。
Base URL	标准（推荐）`https://apiex.cc/gateway/v1` 工具自拼 /v1 时`https://apiex.cc/gateway` Responses API`https://apiex.cc/gateway/v1/responses`
模型 ID	`provider/model-name` 格式，见通用配置。

API 参考

所有接口均挂载在 https://apiex.cc/gateway/v1 之下。

POST

对话生成

/gateway/v1/chat/completions

OpenAI 兼容的对话补全接口。

POST

Responses

/gateway/v1/responses

Responses API，Codex 等工具使用。

GET

模型列表

/gateway/v1/models

返回当前可用模型与能力信息。

POST

Anthropic 格式

/gateway/v1/messages

Anthropic 兼容消息接口，Claude 生态使用。

多模态接口

图像、视频和参考图生成能力按模型能力逐步开放。不同模型可能按 token、图片张数、分辨率、视频时长或任务规格计费，价格以模型广场标注为准。

文本生成图像

输入提示词，返回图像任务结果。

参考图生成图像

上传参考图并指定生成要求。

视频生成

按模型支持的时长、分辨率和任务类型计费。

响应与对账

apiex 主张对账可核验：每次调用的响应都带 usage 字段，账单扣费以它为准，你可以逐笔核对。

usage 示例

{
  "id": "chatcmpl-...",
  "model": "openai/gpt-5.2",
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 42,
    "total_tokens": 60
  }
}

计费口径	按响应 `usage` 中的 token 数、以模型广场标注单价（USD / 1M tokens）计费；人民币金额仅为估算展示。
逐笔核对	控制台「日志」页可按请求 ID 查到每笔调用的 token 明细与扣费，与响应 `usage` 一一对应。
余额与预算	控制台「账单」页查看余额、企业额度与预算限制；余额不足会返回 `402`。
流式调用	流式（`stream: true`）调用需传 `stream_options: {"include_usage": true}`，`usage` 会随最后一个分片返回；不传则分片中不含用量，无法逐笔对账。

故障排除

每行按「原因 → 处置」排查；带错误码的先对照状态码徽标定位类别。

401

鉴权失败

原因Key 错误、过期或无余额。

处置检查 Key 是否复制完整、是否被删除；确认工具读取的是 apiex Key 而非官方 Key；确认账户有可用余额。

402

余额不足

原因账户余额或企业额度用尽。

处置控制台「账单」页充值或调整预算限制后重试。

404

URL / 模型不存在

原因Base URL 写成完整路径，或模型 ID 手写有误。

处置SDK 只配 Base URL，接口路径由 SDK 拼接；模型 ID 一律从模型广场复制（provider/model-name）。

429

触发限流

原因超过并发或频率限制。

处置降低调用频率或并发数；持续出现可在控制台检查限额配置。

5xx

服务端错误

原因上游通道或网关瞬时故障。

处置先重试一次；持续失败查看状态页或联系支持，勿盲目重试刷量。

域名

旧域名残留

原因工具仍连接官方域名。

处置检查本机环境变量、IDE 设置、CLI 用户级配置和项目级配置是否存在旧值。

npm

安装失败

原因registry 网络或权限问题。

处置临时切换镜像、修复全局目录权限后重试。