文档 · 快速开始

接入你的 SDK

2026-09-18

Base URL、各接入点及其鉴权头、OpenAI SDK 和 Anthropic SDK 的可用示例，以及每个错误状态码的含义。

SDK 不用换，密钥填在原本填厂商密钥的位置。API 密钥页顶部的 API 接入点面板列了全部路径，每条都带复制按钮。复制基础地址复制的是不带 /v1 的域名 https://ai.topxea.com：Anthropic SDK 直接用它；OpenAI 风格的 SDK 要自己补上 /v1，或者复制对应的端点那一行。

完成首次调用

打开 API 密钥，为要测试的模型系列创建密钥。密钥的路由和模型限制决定可调用范围；在客户端选择模型不会扩大密钥权限。
查看钱包。新账户目前会获得 $0.50 欢迎余额。已有正余额时可以先做简短测试，无需先充值；密钥自身的额度也需要覆盖请求预扣。
使用下方对应示例，在本地替换密钥并运行一次，限制输出长度。不要将密钥发给客服或贴到公开 issue。
收到响应后，在用量中核对模型、路由和费用。/v1/models 成功只代表模型列表可读取，不代表生成请求已经成功。

使用桌面客户端可以参考 Cherry Studio 接入指南。先用一个模型、一条路由完成调用，再扩展其他配置。

接入点

POST /v1/chat/completions：OpenAI Chat Completions，Authorization: Bearer <key>，除 Jev 以外的全部文本模型（GLM 和 Kimi 只在这里）
POST /v1/responses：OpenAI Responses，Bearer，GPT 模型和 grok-4.7
POST /v1/messages：Anthropic Messages，x-api-key: <key>，Claude 模型；裸请求还要带 anthropic-version: 2023-06-01，不带 max_tokens 就按模型的输出上限
POST /v1/images/generations 和 POST /v1/images/edits：OpenAI Images，Bearer，GPT Image 2.5 模型
POST /v1/videos/generations 提交任务，GET /v1/videos/{request_id} 查状态，GET /v1/videos/{request_id}/content 取视频：Bearer，Grok Imagine Video
POST /v1/systemone（/v1/system_one 也认）：TypeSafe System One，Bearer，Jev
GET /v1/models：这把密钥能调的模型列表

OpenAI Python SDK

Base URL 带 /v1，SDK 自己补上 /chat/completions。

from openai import OpenAI

client = OpenAI(base_url="https://ai.topxea.com/v1", api_key="sk-...")
reply = client.chat.completions.create(
    model="claude-sonnet-5-5",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(reply.choices[0].message.content)

Anthropic SDK

Anthropic SDK 会自己补上 /v1/messages，所以它的 Base URL 是不带 /v1 的域名；密钥放在 x-api-key 头里。

from anthropic import Anthropic

client = Anthropic(base_url="https://ai.topxea.com", api_key="sk-...")
reply = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=256,
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(reply.content[0].text)

编程工具

Claude Code：Claude 模型可以接 Claude Code 和任何兼容 Anthropic 的客户端。密钥行菜单里的 CC Switch 会打开一条 ccswitch:// 导入链接，带上接入点（Claude 用 https://ai.topxea.com，Codex 用 https://ai.topxea.com/v1）、密钥和你选的主模型；Claude 的导入还可以选填 Haiku 模型、Sonnet 模型、Opus 模型。
Codex CLI：GPT 和 Grok 模型，Base URL 填 https://ai.topxea.com/v1。
Trae 这类编辑器填同样两个值。Trae 添加模型时的测试请求会附一张小图，而 GLM-5.3-Abliterated 只支持文本；中转站会把图片换成 [Attachment omitted: this model accepts text only.]，测试能通过，但模型收不到附件。
Jev：TypeSafe 的 SDK 读取 TYPESAFE_BASE_URL=https://ai.topxea.com 和 TYPESAFE_API_KEY。Jev 密钥下方的一键接入命令会安装 TypeSafe 的 agent skill，写入 ~/.config/topxai/typesafe.env，在 ~/.zshrc 或 ~/.bashrc 里加一段带标记的配置，把环境变量写进 ~/.claude/settings.json，最后发一个 ping 请求；不带 --key 运行，脚本会让你输入密钥，输入时不回显。

第一次调用失败

401：密钥缺失或无效。
402：余额不足。
403：模型 ID 不在目录里、这把密钥的线路不提供这个模型，或者密钥的模型限制没包含它，错误信息里会写明是哪一种。
404：厂商那边回答模型不存在。
429：触发限速，Retry-After 头给出要等多久，最长 60 秒。
503：当下没有线路能提供这个模型，或者厂商过载，稍后重试。

每条错误信息末尾都带一个请求 ID，可以发给 support@topxea.com。