开发者接入指南

本文面向开发者和第一次接触 API 的用户，说明如何把 Xmodel 接入代码、开发工具和常见 AI 客户端。你可以把 Xmodel 理解成一个“统一入口”：原来需要分别申请不同模型厂商账号，现在只需要使用 Xmodel 的 Token 和 Base URL，就能调用平台已开通的模型。

2.1 API 接口规范与兼容性说明

Xmodel 的接入方式

Xmodel 提供 OpenAI 兼容格式的 API。多数已经支持 OpenAI API 的客户端或 SDK，只需要改两项配置：

配置项	填写内容	说明
API Key / Token	在 Xmodel「令牌管理」中创建并复制	请求鉴权用，不要公开给他人
Base URL	https://api.xmodel.chat/v1 或 https://api.xmodel.pro/v1	OpenAI SDK、Cursor、Chatbox、NextChat 通常填写带 /v1 的地址
Model ID	例如 gpt-5.5、gpt-5.4、gpt-image-2	以「模型广场」或「列出模型」接口返回为准

如果某个客户端要求填写“接口地址”“API 地址”“OpenAI Base URL”“自定义 API Endpoint”，通常都填 Base URL。如果它要求单独填写“模型名”，就填模型 ID。

兼容哪些能力

Xmodel 主要兼容 OpenAI 风格的接口：

能力	接口	用途
对话补全	POST /v1/chat/completions	聊天、问答、代码生成、文本分析
图片生成	POST /v1/images/generations	文生图
图片编辑	POST /v1/images/edits	图生图、局部修改图片
模型列表	GET /v1/models	查询当前可用模型 ID

同时，Xmodel 也在文档中提供 Anthropic、Gemini、Codex 等协议入口。普通用户优先使用 OpenAI 兼容方式即可，最容易配置，也最容易排查。

鉴权方式

每次请求都需要带上 Token：

注意：

不要把真实 Token 写进公开文档、截图、GitHub 仓库或前端代码。

后端服务建议用环境变量保存 Token，例如 XMODEL_API_KEY。

每个项目或客户端建议单独创建 Token，后续更容易统计消耗和排查问题。

Base URL 怎么选

推荐优先使用：

https://api.xmodel.chat/v1

也可以使用：

https://api.xmodel.pro/v1

如果某个客户端明确说“不要带 /v1”，再填写不带 /v1 的地址，例如 Claude Code 文档中的 https://api.xmodel.chat。简单判断方法是：

OpenAI 兼容客户端、OpenAI SDK、Chatbox、NextChat、Cursor：通常带 /v1。

Claude Code 的 ANTHROPIC_BASE_URL：通常不带 /v1。

2.2 通过主流客户端使用 Xmodel

接入前准备

不管你使用哪个客户端，都先准备三样东西：

进入 https://xmodel.pro/console/token。

点击「添加令牌」，创建一个专用 Token。

打开 https://xmodel.pro/pricing，选择要用的模型 ID。

准备 Base URL：https://api.xmodel.chat/v1。

建议命名方式：

使用场景	Token 名称建议
Cursor	cursor-dev
Chatbox / NextChat	chatbox 或 nextchat
Codex	codex
Claude Code	claude-code
测试代码	api-test
生产服务	prod-service

这样做的好处是：以后在「使用日志」和「API Key 消耗排行」里，一眼就能看出哪个工具在消耗额度。

2.2.1 Cursor 接入 Xmodel 配置教程

Cursor 支持配置 OpenAI 兼容接口。适合用 Xmodel 做代码补全、代码解释、生成脚本、重构建议等。

配置步骤

打开 Cursor。

进入 Settings / Models / API Keys，找到 OpenAI 或自定义 OpenAI Compatible 配置项。

API Key 填写 Xmodel Token。

Base URL 填写：

https://api.xmodel.chat/v1

Model 填写你要使用的模型，例如：

gpt-5.5

保存后，新建一个聊天窗口，发送“你好，请用一句话介绍 Xmodel”测试是否能返回。

小白解释

Cursor 里所谓的“OpenAI API Key”，不一定只能填 OpenAI 官方 Key。只要它支持自定义 Base URL，就可以把请求转发到 Xmodel。Token 负责证明“你是谁”，Base URL 负责告诉 Cursor“请求发到哪里”。

如果失败

报 401：检查 Token 是否复制完整，前后不要多空格。

报模型不存在：换成模型广场中真实存在的模型 ID。

没有反应：保存后重启 Cursor 再试。

有消耗但客户端没显示：到 Xmodel「使用日志」查看返回状态和错误信息。

2.2.2 Chatbox / NextChat 接入配置教程

Chatbox 和 NextChat 都常用于日常聊天、提示词测试、知识问答。它们通常支持 OpenAI Compatible、自定义接口地址或代理地址。

Chatbox 配置

打开 Chatbox 设置。

模型提供方选择 OpenAI 或 OpenAI Compatible。

API Key 填写 Xmodel Token。

API Host / Base URL 填写：

https://api.xmodel.chat/v1

模型名填写：

gpt-5.5

保存后发送测试问题。

NextChat 配置

NextChat 一般在设置页或环境变量里配置：

配置项	示例
OPENAI_API_KEY	Xmodel Token
BASE_URL / OPENAI_API_BASE_URL	https://api.xmodel.chat/v1
模型	gpt-5.5

如果你是本地部署 NextChat，常见环境变量示例：

不同版本的 NextChat 配置名可能略有差异，如果页面里看到“接口地址”“代理地址”“自定义接口”，含义基本都是 Base URL。

使用建议

聊天客户端建议单独创建一个 Token，不要和代码项目共用。

如果多人共用同一个 NextChat，建议设置 Token 额度上限。

如果要低成本测试，先选择价格较低、响应稳定的模型。

2.2.3 Codex 接入 Xmodel 教程

Codex 适合代码生成、项目修改、命令行协作等场景。Xmodel 官方文档中 Codex 接入使用 OpenAI Provider 方式。

Mac / Linux 配置

编辑 Codex 配置文件：

~/.codex/config.toml

写入或修改为：

model_provider = "OpenAI"
model = "gpt-5.5"
review_model = "gpt-5.4"
model_reasoning_effort = "xhigh"

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://api.xmodel.chat/v1"
wire_api = "responses"
requires_openai_auth = true

再编辑鉴权文件：

~/.codex/auth.json

写入：

{
  "OPENAI_API_KEY": "<你的 Xmodel Token>"
}

保存后，关闭并重新打开终端，让配置生效。

Windows 配置

配置文件通常在：

%userprofile%\.codex\config.toml
%userprofile%\.codex\auth.json

config.toml 示例：

model_provider = "OpenAI"
model = "gpt-5.4"
review_model = "gpt-5.4"
model_reasoning_effort = "xhigh"
disable_response_storage = true
network_access = "enabled"
windows_wsl_setup_acknowledged = true
model_context_window = 1000000
model_auto_compact_token_limit = 900000

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://api.xmodel.chat/v1"
wire_api = "responses"
requires_openai_auth = true

auth.json 示例：

{
  "OPENAI_API_KEY": "<你的 Xmodel Token>",
  "auth_mode": "apikey"
}

验证方式

重新打开终端后运行 Codex，发送一个简单任务，例如：

请用一句话说明当前项目是做什么的

如果能正常返回，并且 Xmodel「使用日志」里能看到请求，说明接入成功。

2.2.4 Claude Code 接入 Xmodel 教程

Claude Code 使用 Anthropic 风格环境变量。它和 OpenAI SDK 的配置略有不同：Base URL 通常不带 /v1。

Mac / Linux 临时配置

在终端执行：

然后启动 Claude Code 测试。

Mac / Linux 长期配置

可以写入 shell 配置文件，例如 ~/.zshrc 或 ~/.bashrc：

保存后执行：

settings.json 配置方式

也可以配置：

~/.claude/settings.json

示例：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.xmodel.chat",
    "ANTHROPIC_AUTH_TOKEN": "<你的 Xmodel Token>",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
  }
}

Windows CMD

set ANTHROPIC_BASE_URL=https://api.xmodel.chat
set ANTHROPIC_AUTH_TOKEN=<你的 Xmodel Token>
set ANTHROPIC_MODEL=claude-sonnet-5

PowerShell

$env:ANTHROPIC_BASE_URL="https://api.xmodel.chat"
$env:ANTHROPIC_AUTH_TOKEN="<你的 Xmodel Token>"
$env:ANTHROPIC_MODEL="claude-sonnet-5"

生效提醒

Claude Code 通常可以即时生效。

如果没有生效，关闭当前终端，重新打开后再试。

如果使用的是桌面客户端，建议完整退出并重新打开。

2.3 代码调用示例

下面示例都使用占位符 $XMODEL_API_KEY，请不要把真实 Token 写进代码仓库。

cURL 对话示例

Python 示例

先安装 SDK：

代码：

Python 流式输出

流式输出就是模型边生成边返回，适合聊天页面的“打字机效果”。

Node.js 示例

先安装 SDK：

代码：

查询模型列表

返回中 data[].id 就是可以填写到客户端里的模型 ID。

图片生成示例

图片生成建议优先使用英文提示词，效果通常更稳定。如果要中文描述，可以先让模型帮你把中文提示词优化成英文。

2.4 常见报错代码与排查指南

快速排查顺序

遇到问题时，先按这个顺序看：

Token 是否正确：有没有复制完整、有没有多空格、是否被禁用或删除。

Base URL 是否正确：OpenAI 兼容客户端通常要带 /v1。

模型 ID 是否正确：到「模型广场」或 /v1/models 查询。

账户是否有余额：到「钱包管理」查看。

是否命中 Token 限制：检查额度上限、模型限制、IP 白名单。

使用日志是否有请求：到 https://xmodel.pro/console/log 查看状态码和错误信息。

401 Unauthorized / Invalid API Key

含义：鉴权失败，平台不知道你是谁。

常见原因：

Token 写错、少复制了一段或前后有空格。

Token 已被禁用或删除。

Header 没写成 Authorization: Bearer <token>。

客户端把 API Key 填到了错误位置。

处理方法：重新复制 Token；必要时删除旧 Token，重新创建一个新的。

403 Forbidden

含义：请求被拒绝，通常是权限或限制问题。

常见原因：

Token 设置了 IP 白名单，当前网络不在白名单里。

Token 所属分组不允许调用该模型。

当前账号或分组权限不足。

处理方法：检查令牌管理里的 IP 限制、模型限制和分组配置。

404 Model Not Found / 模型不存在

含义：模型名没有匹配到。

常见原因：

模型 ID 拼错。

使用了客户端默认模型名，但 Xmodel 当前没有这个模型。

Token 限制了可用模型。

处理方法：打开「模型与价格」复制准确模型 ID，或调用 GET /v1/models 查询可用模型。

429 Too Many Requests / 请求过多

含义：请求太频繁，超过当前模型、账号或平台限制。

处理方法：

降低并发和请求频率。

为批量任务增加重试等待时间。

换用更适合批量调用的模型或分组。

查看控制台的 RPM、TPM 指标。

402 / 余额不足 / Insufficient Quota

含义：账户余额不足或 Token 额度上限已用完。

处理方法：

到「钱包管理」查看余额。

到「令牌管理」检查该 Token 的额度上限。

到「使用日志」查看最近是否有异常消耗。

400 Bad Request

含义：请求格式不正确。

常见原因：

JSON 格式写错，例如少了逗号或引号。

messages 不是数组。

图片接口传参不符合要求。

客户端把 Base URL 和完整接口路径拼重复了。

处理方法：先用本文的 cURL 示例跑通，再迁移到自己的代码中。

500 / 502 / 503 服务异常

含义：服务端或上游模型暂时异常。

处理方法：

等待几秒后重试。

切换其他可用模型。

查看 Xmodel 控制台公告或服务状态。

如果是生产服务，建议在代码里加入失败重试和备用模型。

客户端配置后没有生效

常见处理：

Cursor、Chatbox、NextChat：保存配置后关闭设置页，重新发起会话。

Codex：关闭并重新打开终端。

Claude Code：重新打开终端或重新启动客户端。

桌面客户端：完整退出应用后再打开。

如何确认真的接入成功

最简单的成功标准有两个：

客户端或代码能正常返回模型回答。

Xmodel「使用日志」里能看到对应 Token 的请求记录。

如果客户端没有返回，但使用日志里有错误记录，优先按日志中的状态码排查；如果使用日志里完全没有请求，通常是客户端没有把请求发到 Xmodel，重点检查 Base URL 和保存/重启是否生效。

开发者接入指南

2.1 API 接口规范与兼容性说明#

Xmodel 的接入方式#

兼容哪些能力#

鉴权方式#

Base URL 怎么选#

2.2 通过主流客户端使用 Xmodel#

接入前准备#

2.2.1 Cursor 接入 Xmodel 配置教程#

配置步骤#

小白解释#

如果失败#

2.2.2 Chatbox / NextChat 接入配置教程#

Chatbox 配置#

NextChat 配置#

使用建议#

2.2.3 Codex 接入 Xmodel 教程#

Mac / Linux 配置#

Windows 配置#

验证方式#

2.2.4 Claude Code 接入 Xmodel 教程#

Mac / Linux 临时配置#

Mac / Linux 长期配置#

settings.json 配置方式#

Windows CMD#

PowerShell#

生效提醒#

2.3 代码调用示例#

cURL 对话示例#

Python 示例#

Python 流式输出#

Node.js 示例#

查询模型列表#

图片生成示例#

2.4 常见报错代码与排查指南#

快速排查顺序#

401 Unauthorized / Invalid API Key#

403 Forbidden#

404 Model Not Found / 模型不存在#

429 Too Many Requests / 请求过多#

402 / 余额不足 / Insufficient Quota#

400 Bad Request#

500 / 502 / 503 服务异常#

客户端配置后没有生效#

如何确认真的接入成功#

2.1 API 接口规范与兼容性说明

Xmodel 的接入方式

兼容哪些能力

鉴权方式

Base URL 怎么选

2.2 通过主流客户端使用 Xmodel

接入前准备

2.2.1 Cursor 接入 Xmodel 配置教程

配置步骤

小白解释

如果失败

2.2.2 Chatbox / NextChat 接入配置教程

Chatbox 配置

NextChat 配置

使用建议

2.2.3 Codex 接入 Xmodel 教程

Mac / Linux 配置

Windows 配置

验证方式

2.2.4 Claude Code 接入 Xmodel 教程

Mac / Linux 临时配置

Mac / Linux 长期配置

settings.json 配置方式

Windows CMD

PowerShell

生效提醒

2.3 代码调用示例

cURL 对话示例

Python 示例

Python 流式输出

Node.js 示例

查询模型列表

图片生成示例

2.4 常见报错代码与排查指南

快速排查顺序

401 Unauthorized / Invalid API Key

403 Forbidden

404 Model Not Found / 模型不存在

429 Too Many Requests / 请求过多

402 / 余额不足 / Insufficient Quota

400 Bad Request

500 / 502 / 503 服务异常

客户端配置后没有生效

如何确认真的接入成功