# qtai.work API 使用说明

> **这份文档可以直接交给 AI。**
> 把全文复制给 ChatGPT / Claude / 任意 AI，再补一句：
> 「请按这份说明帮我配置 XXX 客户端」
> 它就能给出完整的配置步骤，不需要你再去猜参数。

---

## 1. 基本信息

| 项目 | 值 |
|---|---|
| **Base URL** | `https://api.qtai.work/v1` |
| **API Key** | 向管理员索取，每人是独立的一把，形如 `sk-xxxxxxxxxxxx` |
| **协议** | 与 OpenAI 官方 API 完全兼容（Chat Completions / Images） |
| **认证方式** | 请求头 `Authorization: Bearer <你的 key>` |
| **是否支持流式** | 支持（`stream: true`） |
| **是否支持函数调用** | 支持 |

如果你用的是只填「服务器地址」的客户端，注意区分两种写法：

```
https://api.qtai.work        ← 有的客户端会自动补 /v1
https://api.qtai.work/v1     ← 有的要求写全
```

**如果填了之后报 404**，就是这里写错了，换成另一种试试。

---

## 2. 可用模型

### 文本 / 对话

| 模型 | 说明 |
|---|---|
| `gpt-6-astra` | **推荐**，速度与质量均衡 |
| `gpt-5.6-luna` | 较轻量 |
| `gpt-5.6-sol` | 强推理 |
| `gpt-5.6-terra` | 长上下文 |
| `gpt-6-sol` | 高配推理 |
| `gpt-6.1-sol` | 高配推理（新一代） |
| `gpt-6-luna` | 轻量快速 |
| `codex-auto-review` | 代码审查专用 |

### 图像生成

`gpt-image-1.5`、`gpt-image-2`、`gpt-image-2.5`、`gpt-image-2.5-flare`、`gpt-image-2.5-sunburst`

走 `/v1/images/generations` 接口。

> 上游模型会不定期调整，以实际可用为准。查当前完整列表：
> `curl https://api.qtai.work/v1/models -H "Authorization: Bearer sk-你的key"`

---

## 3. 先用一行命令验证

拿到 key 之后，先跑这个（把 `sk-你的key` 换成自己的）：

```bash
curl https://api.qtai.work/v1/chat/completions \
  -H "Authorization: Bearer sk-你的key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-astra",
    "messages": [{"role": "user", "content": "回两个字：收到"}],
    "max_tokens": 20
  }'
```

- 返回 `{"choices":[{"message":{"content":"收到"}}]}` → **配置成功**
- 返回 `401 Invalid token` → key 填错了
- 返回 `403 Insufficient user quota` → 你的额度用完了，找管理员加
- 返回 `503 ... server_is_overloaded` → 上游繁忙（不是你的问题），换模型或等几分钟

---

## 4. 常见客户端怎么填

### Cherry Studio

1. 设置 → 模型服务 → 添加提供商 → 类型选 **OpenAI**
2. API 地址：`https://api.qtai.work`（Cherry 会自动补 `/v1`；如果不行就写全 `https://api.qtai.work/v1`）
3. API 密钥：填你的 `sk-...`
4. 在「模型」里手动添加：`gpt-6-astra`、`gpt-5.6-luna` 等（列表里的模型名要和上面一致）
5. 点「检查」按钮，出现绿色对勾即成功


### Codex CLI（重点，容易踩坑）

Codex 的配置文件是 **TOML 不是 YAML**，路径 `~/.codex/config.toml`
（Windows：`C:\Users\你的用户名\.codex\config.toml`）。

**必须两处都配，缺一不可：**

```toml
model_provider = "qtai"

[model_providers.qtai]
name = "qtai.work"
base_url = "https://api.qtai.work/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
```

```bash
export OPENAI_API_KEY="sk-你的key"
```

- `config.toml` 负责**告诉 Codex 用哪个地址**（默认它走自己的云端，光设环境变量不会改道）
- `env_key = "OPENAI_API_KEY"` 指的才是放 key 的那个环境变量
- `wire_api` **必须是 `"responses"`**：新版 Codex 已移除 `chat` 协议，写 `chat` 会直接报 `is no longer supported` 拒绝启动

**改完必须重启 Codex 守护进程，否则不生效：**

```bash
# macOS / Linux
codex app-server daemon restart
# 或者
pkill -f "codex app-server"
```

Windows 在任务管理器里结束 `codex.exe`；VS Code 的 Codex 插件还要 `Ctrl+Shift+P` → `Reload Window`。

> 原因：Codex 自带常驻的 `app-server` 守护进程（`codex app-server --managed-daemon`），
> 会把凭据和 provider 配置缓存在内存里，不重读磁盘。`daemon_auto_start = false`
> 只能阻止自启，解决不了"已运行的 daemon 用旧配置"。

### ChatBox

1. 设置 → 模型提供商 → **OpenAI API 兼容**
2. API Host：`https://api.qtai.work`（或 `/v1`）
3. API Key：你的 `sk-...`
4. 模型名手动输入：`gpt-6-astra`

### NextChat / ChatGPT-Next-Web

1. 设置 → 自定义接口
2. 接口地址：`https://api.qtai.work`
3. API Key：你的 `sk-...`
4. 自定义模型：`gpt-6-astra,gpt-5.6-luna`

### OpenAI 官方 SDK（Python）

```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-你的key",
    base_url="https://api.qtai.work/v1",
)

resp = client.chat.completions.create(
    model="gpt-6-astra",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)
```

### OpenAI 官方 SDK（Node.js）

```js
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-你的key",
  baseURL: "https://api.qtai.work/v1",
});

const resp = await client.chat.completions.create({
  model: "gpt-6-astra",
  messages: [{ role: "user", content: "你好" }],
});
console.log(resp.choices[0].message.content);
```

### 沉浸式翻译 / 浏览器插件

- 服务商选 **OpenAI**
- 自定义 API 地址：`https://api.qtai.work/v1`
- API Key：你的 `sk-...`
- 模型：`gpt-5.6-luna`（翻译用轻量模型就够）

---

## 5. 限制

| 项目 | 限制 |
|---|---|
| 频率 | **每人每分钟 30 次请求**，超了返回 `429` |
| 额度 | 每人独立额度，用完需管理员充值 |
| 并发 | 无单独限制，但上游账号容量有限，高并发会 `503` |

**限流是按用户算的**，别人刷得再猛也不会影响你的配额。

---

## 6. 常见错误对照

| 返回 | 含义 | 怎么办 |
|---|---|---|
| `401 Invalid token` | key 错了 / 被删了 | 找管理员要新的 |
| `403 Insufficient user quota` | 额度用完 | 找管理员加额度 |
| `404` | Base URL 少写或多写了 `/v1` | 换另一种写法 |
| `429` | 触发频率限制 | 等一分钟 |
| `502` / `503 server_is_overloaded` | OpenAI 上游过载 | 换模型，或等几分钟；这不是本站问题 |
| `model_not_found` | 模型名打错了 | 用第 2 节的模型名 |

---

## 7. 给 AI 的提示词模板

把上面的内容整段粘贴，然后接这段：

```
以上是 qtai.work 的 API 接入说明。
我的 API Key 是：sk-（在此填你自己的 key）
我要配置的客户端是：（例如 Cherry Studio / ChatBox / Python 脚本）
我的操作系统是：（例如 Windows 11 / macOS）
请给我一步一步的配置步骤，包括每个输入框该填什么。
如果配置后报错，我会把报错原文贴给你。
```

---

## 8. 安全提醒

- **key 等同于密码**，不要发到群里、不要提交到 GitHub、不要写进公开的前端代码
- 每个人的 key 是独立的，泄露了只影响你自己那把，告诉管理员可以单独吊销
- 本站仅供内部使用，请勿对外分享

---

*最后更新：2026-10-24*