GETTING STARTED

XQAPI API 文档

使用统一、兼容的 HTTP API 接入 XQAPI 模型。下面只保留从获得密钥到完成第一次请求所必需的内容。

Base URLhttps://xqapi.wkuola.workers.dev/v1

快速开始

1
创建 API Key
登录控制台，在 API Keys 页面创建密钥。密钥只会完整显示一次。
2
选择模型 ID
在模型库打开模型详情，复制页面展示的公开 Model ID。
3
发起请求
将密钥放入 Bearer Authorization 请求头。

客户端接入指南

Claude Code

Anthropic Messages 网关配置与模型发现

Codex

Responses API 自定义模型供应商

Cherry Studio

OpenAI 兼容自定义服务商

CC Switch

Claude Code 与 Codex 供应商切换

身份认证

所有模型调用都使用 Bearer Token。请只在服务端保存 API Key，不要把它放进浏览器代码或公开仓库。

HTTP

Authorization: Bearer $XQAPI_API_KEY

获取模型列表

使用模型列表接口读取当前账户可调用的公开模型 ID。

GET/v1/models

API Key 路由偏好与请求级覆盖

分流的单位是分组：同一个模型往往挂在多条来源不同的线路上，它们按分组归拢，价格与稳定性各不相同。

API Key 可以保存以下默认偏好：

优先策略：智能均衡兼顾速度与价格；也可明确选择价格优先或稳定优先。
绑定分组：可多选，所选分组组成优先池；留空时由平台自动选路。
模型限制：可另外限制这把 Key 能调用的模型；绑定分组后，配置界面只提供这些分组覆盖的模型。
切走之后：故障转移后保持当前分组，或在原绑定分组恢复后自动切回。
故障转移：线路失败后是否自动尝试其他可用线路。
仅限绑定分组：未显式覆盖线路时，只在优先池内故障转移；关闭时池内不可用还可继续尝试其他分组。

仅当 Key 开启允许请求覆盖时，调用方才能在 POST 模型接口中加入 routing，临时调整本次请求。省略的字段继续沿用 Key 默认值；请求不能突破 Key 的模型范围，也不能重新打开 Key 已关闭的故障转移。

JSON 字段	请求头	可选值	行为
`route`	`X-XQAPI-Route`	`channel-5` / `route-13b`	把指定公开线路放在首位；省略时沿用 Key 的分组与默认线路。若同时设 `failover: false`，该线路不可用就直接失败
`strategy`	`X-XQAPI-Routing`	`auto` / `price` / `stable`	本次请求使用智能均衡、价格优先或稳定优先；省略时沿用 Key 的优先策略
`failover`	`X-XQAPI-Failover`	`true` / `false`	控制失败后是否尝试下一条线路；省略时沿用 Key 设置，且请求不能重新打开 Key 已关闭的故障转移

JSON

{
  "model": "your-model-id",
  "messages": [{"role": "user", "content": "你好"}],
  "routing": {
    "route": "channel-5",
    "strategy": "price",
    "failover": true
  }
}

请求头与 JSON 字段一一对应；同时提供时请求头优先，并遵守同一套 Key 约束。routing 只用于平台选路，不会转发给上游。

文本生成

接口兼容常见的 Chat Completions 请求结构。更换模型时通常只需要修改 model。

POST/v1/chat/completions

cURL

curl https://xqapi.wkuola.workers.dev/v1/chat/completions \
  -H "Authorization: Bearer $XQAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "messages": [{"role": "user", "content": "你好"}]
  }'

图像生成

文生图与图生图是同一套约定:默认返回官方形状 { created, data[], usage }，图片链接托管在本站，可直接用官方 SDK 调用；response_format: "b64_json" 改为内联 base64。

同步等待上限 600 秒，与官方 SDK 默认请求超时一致；超过即按超时返回 504。想自己控制轮询节奏，可以加 "async": true 拿异步任务 ID。 resolution（1k / 2k / 4k）不区分大小写。可用的 quality、size、output_format 取值以模型详情页为准。

文生图

只给提示词，JSON 与官方 multipart 均可提交。

POST/v1/images/generations

cURL

curl https://xqapi.wkuola.workers.dev/v1/images/generations \
  -H "Authorization: Bearer $XQAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"your-image-model","prompt":"一座未来城市"}'

图生图 / 编辑

在参考图基础上改图，与官方 images.edit 同形状。参考图有两种给法，任选其一：

multipart：重复 image 字段上传文件，最多 16 张；需要局部重绘时再带一个 mask。
JSON：用 images 数组给已有直链或文件 ID，每项只能二选一 —— image_url 或 file_id。另有扩展字段 image_urls 直接收一组 URL。

POST/v1/images/edits

cURL · multipart

curl https://xqapi.wkuola.workers.dev/v1/images/edits \
  -H "Authorization: Bearer $XQAPI_API_KEY" \
  -F model="your-image-model" \
  -F prompt="把背景换成雪山" \
  -F image=@./cat.png \
  -F image=@./style.png

cURL · JSON

curl https://xqapi.wkuola.workers.dev/v1/images/edits \
  -H "Authorization: Bearer $XQAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-image-model",
    "prompt": "把背景换成雪山",
    "images": [{"image_url": "https://example.com/cat.png"}],
    "resolution": "2k"
  }'

视频生成

视频生成采用异步任务模式。创建成功后保存响应中的任务 ID，并轮询任务接口。

POST/v1/videos/generations

查询异步任务

当状态为 succeeded 时读取结果；为 failed 时根据安全错误信息调整请求。

GET/v1/tasks/:id

cURL

curl https://xqapi.wkuola.workers.dev/v1/tasks/{task_id} \
  -H "Authorization: Bearer $XQAPI_API_KEY"

额度查询

读当前 Key 所属账号的额度，用来在自己的系统里做余额告警。 balance 是可用额度，frozen_balance 是请求进行中被预扣、尚未结算的部分，total_balance 是两者之和。单位统一是 Credits。

GET/v1/credits

cURL

curl https://xqapi.wkuola.workers.dev/v1/credits \
  -H "Authorization: Bearer $XQAPI_API_KEY"

错误处理

状态码	含义	建议
400	请求参数错误	检查模型 ID 与参数格式
401	认证失败	确认 API Key 有效
402	余额不足	充值后重试
429	请求过快	指数退避后重试
5xx	服务暂不可用	稍后重试并保留请求信息

多模态 Responses API

使用 OpenAI Responses 结构提交文本、图片和工具调用。图片内容使用 input_image，文本使用 input_text。

POST/v1/responses

cURL

curl https://xqapi.wkuola.workers.dev/v1/responses \
  -H "Authorization: Bearer $XQAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-multimodal-model",
    "input": [{"role":"user","content":[
      {"type":"input_text","text":"描述这张图片"},
      {"type":"input_image","image_url":"https://example.com/image.jpg"}
    ]}]
  }'

向量与内容审核

使用 OpenAI 兼容格式调用已配置对应端点的向量或内容审核模型。

POST/v1/embeddings

cURL

curl https://xqapi.wkuola.workers.dev/v1/embeddings \
  -H "Authorization: Bearer $XQAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"your-embedding-model","input":"需要向量化的文本"}'

POST/v1/moderations

cURL

curl https://xqapi.wkuola.workers.dev/v1/moderations \
  -H "Authorization: Bearer $XQAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"omni-moderation-latest","input":"需要审核的内容"}'

Claude Messages 接口

原生 Anthropic Messages 请求使用 x-api-key 和 anthropic-version；也支持在 JSON 中加入同一份 routing 配置。

POST/v1/messages

cURL

curl https://xqapi.wkuola.workers.dev/v1/messages \
  -H "x-api-key: $XQAPI_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"your-claude-model",
    "max_tokens":1024,
    "messages":[{"role":"user","content":"你好"}]
  }'

Gemini 原生格式接口

Gemini SDK 风格的 contents、parts 和 generationConfig 会原样转发。模型路径使用平台公开模型 ID。

POST/v1beta/models/:model:generateContent

POST/v1beta/models/:model:streamGenerateContent

cURL

curl 'https://xqapi.wkuola.workers.dev/v1beta/models/your-gemini-model:generateContent' \
  -H "x-goog-api-key: $XQAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents":[{"role":"user","parts":[{"text":"你好"}]}],
    "routing":{"strategy":"stable","failover":true}
  }'