Developer Docs

QXAI 接入文档

OpenAI 兼容接口、余额查询、RikkaHub 配置与工具调用。

基础地址

Base URL:  https://qxai-org.xioru.com/org/v1
Auth:      Authorization: Bearer sk-...
GET        /org/v1/models
POST       /org/v1/chat/completions
GET        /org/v1/balance

OpenAI Chat CompletionsSSE StreamingTool Callsreasoning_effort

模型 ID 决定内部路由。公开模型 ID 与上游模型 ID 可以不同，调用方无需知道上游。

聊天与工具调用

标准 POST /chat/completions，参数与 OpenAI 一致。下面是一个工具调用示例：

{
  "model": "demo-chat",
  "messages": [{"role": "user", "content": "几点了？"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_current_time",
      "description": "Get the current time.",
      "parameters": {"type": "object", "properties": {}}
    }
  }]
}

工具调用 400 的常见原因：上游模型本身不支持 Tool Calls，或 RikkaHub 中该模型的 Tool 能力没有开启。QXAI 会原样转发标准 tools 参数，不会伪造工具调用。遇到该错误请更换支持工具的模型，或关闭这项测试。

服务端会统一返回 OpenAI 错误结构，不暴露上游域名、品牌和原始错误体。

余额接口

推荐使用标准路径：

GET /api/user/balance
GET /org/v1/balance

{
  "balance": "12.50",
  "used": "3.2000",
  "currency": "肥料"
}

兼容路径	JSON 取值路径	风格
/org/v1/balance	balance	QXAI 标准
/org/v1/user/balance	balance_infos[0].total_balance	DeepSeek
/org/v1/users/me/balance	data.available_balance	Moonshot
/org/v1/credits	data.total_usage（当前余额）	RikkaHub 兼容
/api/user/credits	data.total_credits - data.total_usage	OpenRouter
/api/user/quota	balance	别名
/api/user/wallet	balance	别名
/v1/balance	balance	旧版兼容
/v1/user/balance	balance_infos[0].total_balance	旧版兼容
/v1/credits	data.total_usage（当前余额）	RikkaHub 兼容

RikkaHub 配置

在 RikkaHub 添加 OpenAI 类型提供商：

Base URL	`https://qxai-org.xioru.com/org/v1`
API Key	`sk-...`
余额 URL	`{{baseUrl}}/balance`
余额 JSON 路径	`balance`
鉴权请求头	`Authorization: Bearer {{apiKey}}`

如果保留 RikkaHub 默认的 {{baseUrl}}/credits 和 data.total_usage，这里返回的是当前余额，不会显示成已消费金额。推荐仍使用 {{baseUrl}}/balance + balance。DeepSeek 风格则使用 {{baseUrl}}/user/balance + balance_infos[0].total_balance。

RikkaHub 的「测试连接」包含非流式、流式、工具调用三项。工具调用失败请先检查模型能力，而不是 Base URL 或 Key。

思考等级

网页「即刻对话」新增思考滑杆：自动、低、中、高、极高、极限。最高档会显示彩色轨道。对应 OpenAI 参数：

"reasoning_effort": "low" | "medium" | "high" | "xhigh" | "max"

自动档不发送该字段。第三方客户端也可以直接传 reasoning_effort；具体是否生效取决于上游模型是否支持思考参数。

错误与限流

余额不足：HTTP 402，insufficient_quota
请求过快：HTTP 429，带 Retry-After
模型不存在：HTTP 404，model_not_found
工具不支持：HTTP 400，tool_calls_not_supported
所有 Key 共享账户肥料、RPM、TPM
API Key 只在创建时显示一次明文

第三方收到 HTML 怎么办

如果客户端报 Unexpected JSON token ... <!doctype html>，说明请求没有进 API 路由，落到了首页或 404。

RikkaHub Base URL 必须填写完整的 https://qxai-org.xioru.com/org/v1，不要只填域名。
宝塔 Nginx 的「伪静态」需要加入 nginx.rewrite.conf，确保无后缀路径回退到 index.php。
确认 PHP 收到 HTTP_AUTHORIZATION。

location /org/ {
  try_files $uri $uri/ /index.php?$query_string;
}
location /v1/ {
  try_files $uri $uri/ /index.php?$query_string;
}

QXAI 3.3.0 也兼容只填域名、只填 /org 和 /v1 的 Base URL，但推荐统一使用 /org/v1。