# 4AICode 文档全文

> Claude / ChatGPT 订阅拼车平台：注册拿 sk- token 填进 AI 工具即可直接调用 Claude Sonnet / Opus、GPT-5 等模型，按 token 计费。
> 本文件由 https://4aicode.com/docs 自动汇总全部公开文档，供 LLM 直接读取。

---

源文档：https://4aicode.com/docs/getting-started

# 什么是 4AICode

4AICode 是 Claude / ChatGPT 订阅拼车平台。不用自己买 Claude Pro、ChatGPT Plus，注册拿 token 填进 AI 工具就能直接用 Claude Sonnet / Opus、GPT-5 等模型，按 token 计费。

## 适合谁

- 用 **Claude Code CLI** / **Codex CLI** 写代码的开发者
- 用 Cursor / Cline / Continue 等 IDE 插件的开发者
- 调 `/v1/messages` 或 `/v1/chat/completions` 做自己应用的人

## 和官方的区别

| | 官方 | 4AICode |
|---|---|---|
| 套餐 | 月付 $20 起 | 按 token 用量付费 |
| 额度 | 每 5 小时"消息数"软限制 | 只看 token 总量 |
| 接入 | 自己申请 API key | 一个 `sk-` token 全搞定 |
| 模型 | 一个账号一家模型 | 一个 token 同时调 Claude 和 GPT-5 |

## 三步开始

### 1. 注册

[4aicode.com](https://4aicode.com) → **注册**。注册完即有一个**个人账号**。

### 2. 创建 token

**仪表盘 → 管理 Tokens → 新建 Token** → 起个名字 → **创建**。

> ⚠️ token 只显示一次，立刻复制到密码管理器。关弹窗即丢，只能撤销重建。

形如：`sk-4ai-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`

### 3. 填进工具

```bash
export ANTHROPIC_BASE_URL=https://relay.4aicode.com
export ANTHROPIC_API_KEY=sk-4ai-xxxx...
```

跑 `claude` 就走 4AICode。GPT-5 / Codex 见 [ChatGPT 配置](/docs/guides/chatgpt)。

## 下一步

- [Claude 配置](/docs/guides/claude)
- [ChatGPT 配置](/docs/guides/chatgpt)
- [Token 使用](/docs/authentication)
- [配额](/docs/guides/quota)
- [限流](/docs/guides/rate-limit)

---

源文档：https://4aicode.com/docs/authentication

# Token 使用

`sk-4ai-...` 是调用 4AICode relay 的唯一凭证，每个请求必带。

## 创建

**仪表盘 → 管理 Tokens → 新建 Token** → 起个名字 → **创建**。

> ⚠️ token 只显示一次，立刻复制到密码管理器（1Password / Bitwarden 等）。关弹窗即丢，只能撤销重建。**不要贴聊天窗口、不要推 git**。

## 用法

用 `Authorization: Bearer` 头：

```
Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx
```

不支持 URL 查询参数（`?api_key=...`）或 `X-Api-Key` 头 —— 易被 HTTP 日志泄漏。

## 团队隔离

token 只能访问创建它时所在的那个团队：

- 换团队 → 重新创建 token
- 用量永远计在 token 所属团队的账单

不存在"一个 token 通吃所有团队"。

## 撤销

**管理 Tokens** 页面点**撤销**。不可逆、立即生效（≤1 秒所有请求返回 401）。撤销后可同名重建。

### 什么时候该撤销

| 场景 | 撤销？ |
|---|---|
| 贴到公开 repo / 聊天群 / 截图 | ✅ 立刻 |
| 离职员工的开发机 | ✅ 立刻 |
| 定期轮换（建议 90 天） | ✅ |
| 换笔记本 | ❌ 直接复用 |
| 怀疑被盗用 | ✅ 先撤再说 |

## 错误码

| 状态码 | 含义 |
|---|---|
| **401** | token 缺失 / 格式错 / 已撤销 |
| **403** | 团队被管理员暂停 |
| **429** | 超限流或超配额（详见 [限流](/docs/guides/rate-limit) / [配额](/docs/guides/quota)） |

## FAQ

**Q：能有几个 token？**
A：无硬上限。推荐一设备一个，便于单机吊销。

**Q：一个 token 能同时调 Claude 和 GPT-5 吗？**
A：可以，token 绑团队不绑模型。

---

源文档：https://4aicode.com/docs/changelog

# 更新日志

这里记录用户能直接感知的功能、页面和体验变化。

## 2026-05-02

- 图片生成支持后台任务，提交后可以离开页面，回来继续查看进度和结果。
- 图片生成支持同时处理多个任务，适合批量尝试不同描述词。
- 图片生成失败时提示更清楚，方便判断是余额、模型状态还是服务波动。
- 图片生成等待时间更宽裕，复杂图片请求更容易完成。
- 新增图片 API 接入文档，方便把 `gpt-image-2` 接入自己的应用。

## 2026-05-01

- 新增图片生成工作台，可以在控制台里选择 Token、尺寸、画质和参考图生成图片。
- `gpt-image-2` 支持按次计费，成功生成后从钱包余额扣费。
- 图片生成消费会出现在用量记录和钱包流水里，账目更容易核对。
- 价格页和账单页拆分，查看套餐、充值、钱包流水和订单记录更清楚。
- 用量页增加钱包余额展示，余额状态更容易掌握。
- 周卡剩余额度展示更贴近当前使用状态。

## 2026-04-30

- 上线一次性 7 天周卡，适合短期高频使用。
- 周卡额度按连续 24 小时计算，剩余额度展示更准确。
- 支付和周卡开通流程更顺畅。
- 客户端主动取消请求时，状态提示更准确。
- 错误信息速查文档补充更多常见场景。

## 2026-04-29

- 后台组织搜索和使用流水查看更清晰，管理员排查用量更方便。
- 用量页费用构成更透明。
- 后台增加充值概况，查看充值趋势更方便。
- 后台页面图表样式统一，阅读数据更顺手。
- 账号上传去重更可靠，减少重复账号记录。

## 2026-04-28

- 新增 Hermes Agent（爱马仕）配置教程。
- 模型计费展示更细，费用更容易理解。
- 浏览器扩展连接体验优化。
- 服务繁忙时后台提示更安静，减少无效告警。

## 2026-04-27

- 订单记录独立成一个页面，查看订单更清楚。
- Tokens 页面重新排版，Base URI 更容易查看和复制。
- Tokens 撤销确认改成弹窗，减少误操作。

## 2026-04-26

- 支持 Claude Code 使用 ChatGPT 模型。
- 新增订单记录，订阅和充值历史更容易查看。
- 控制台支持移动端浏览。
- 通过活动链接注册可以获得专属赠送额度。
- 推广返利升级为独立余额，支持转入钱包和提交提现申请。
- 推广中心页面重新整理，可以查看返利、转入和提现记录。
- 业务邮件样式更统一。

## 2026-04-25

- 新增公开状态页，可以查看服务可用情况。
- Token 创建和删除会发送邮件通知。
- 余额提醒更及时。
- Codex 使用稳定性优化。
- 登录页接入 GitHub 和 Google 登录。
- 登录后增加支持入口和状态入口。

## 2026-04-24

- 支持 GPT-5.5 Codex 模型。
- 钱包模式直接按余额检查配额。
- 新增推广返利功能。
- 首页品牌文案更新为 ChatGPT 账号拼车方向。
- 补齐 `/v1/models` 兼容接口。
- 支持 Google Gemini 模型。
- Usage 页面增加花费统计和筛选。
- 支付成功后发送邮件通知。

## 2026-04-23

- 支持 GPT 图片接口。
- 计费入口和组织列表展示更清楚。
- Tokens 页面补充 Base URI。
- 新增 Chrome 智能填表扩展。
- 最近请求和钱包流水支持更精确的金额展示。
- 支付流程稳定性优化。

## 2026-04-22

- 注册后钱包兜底和额度显示更可靠。
- 用量日志解析更准确，默认展示最近请求。
- 流式输出兼容性优化。
- Codex token 用量统计更准确。
- 模型价格展示更中文化。

## 2026-04-21

- 支持订阅、按需充值钱包和试用额度。
- 配额显示更清楚，区分钱包、订阅和试用额度。
- Windows Codex 配置脚本和文档更完整。
- 充值和订阅体验优化。

## 2026-04-20

- 注册支持邮箱验证码、滑块 CAPTCHA、已注册邮箱拦截。
- 支持邀请码强制注册。
- 控制台改成左侧导航布局。
- 简化工作区概念，页面在大屏下更好用。
- 增加 Cursor、VS Code、Windsurf 使用指南。
- 文档拆分 Mac、Windows、Linux 场景，并支持代码块复制。

## 2026-04-19

- 上线首页、文档站、登录注册和基础控制台。
- 接入邮件验证码、邮件通知和余额提醒能力。
- 去掉个人 / 团队工作区区分，每个账号默认一个个人空间。
- 支持 Claude 和 ChatGPT 接入。
- 建立按 token 计费的基础能力，支持钱包、流水和账期。
- 新增 Codex CLI 一键配置脚本和基础接入文档。
- 优化 Claude 和 Codex 请求兼容性，保证基础请求可用。

---

源文档：https://4aicode.com/docs/guides/claude

# Claude 配置

用 4AICode token 接入 Claude Code、Anthropic SDK 和 `/v1/messages`。Claude 端点使用：

- Base URL：`https://relay.4aicode.com`
- API Key：[仪表盘 → 管理 Tokens](https://4aicode.com/tokens) 创建的 `sk-4ai-...`

Claude Code 也能固定使用 ChatGPT 模型，配置在下方。Codex CLI 和 OpenAI SDK 见 [ChatGPT 配置](/docs/guides/chatgpt)。


**macOS / Linux**


## Claude Code CLI

```bash
export ANTHROPIC_BASE_URL=https://relay.4aicode.com
export ANTHROPIC_AUTH_TOKEN=sk-4ai-xxxxxxxxxxxxxxxx
export ANTHROPIC_API_KEY=sk-4ai-xxxxxxxxxxxxxxxx
claude
```

永久生效写入 shell 配置：

```bash
cat <<'EOF' >> ~/.zshrc
export ANTHROPIC_BASE_URL=https://relay.4aicode.com
export ANTHROPIC_AUTH_TOKEN=sk-4ai-xxxxxxxxxxxxxxxx
export ANTHROPIC_API_KEY=sk-4ai-xxxxxxxxxxxxxxxx
EOF
source ~/.zshrc
```

## Claude Code 使用 ChatGPT 模型

```bash
export ANTHROPIC_BASE_URL=https://relay.4aicode.com
export ANTHROPIC_AUTH_TOKEN=sk-4ai-xxxxxxxxxxxxxxxx
export ANTHROPIC_DEFAULT_OPUS_MODEL=gpt-5.5
export ANTHROPIC_MODEL=opus
claude
```

完整版本适合固定 `gpt-5.5` 超高推理，并在 Claude Code UI 里显示更友好的模型名：

```bash
export ANTHROPIC_BASE_URL=https://relay.4aicode.com
export ANTHROPIC_AUTH_TOKEN=sk-4ai-xxxxxxxxxxxxxxxx
export ANTHROPIC_DEFAULT_OPUS_MODEL=gpt-5.5
export ANTHROPIC_DEFAULT_OPUS_MODEL_NAME="4AICode GPT 5.5"
export ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES=effort,xhigh_effort,thinking,adaptive_thinking,interleaved_thinking
export ANTHROPIC_MODEL=opus
export ANTHROPIC_DEFAULT_HAIKU_MODEL=gpt-5.4-mini
export CLAUDE_CODE_EFFORT_LEVEL=xhigh
claude
```

`/v1/messages` 会按 `model` 自动路由：`claude-*` 走 Claude 账号池，`gpt-*` 走 ChatGPT Codex 账号池。

## Node / TypeScript

```ts
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://relay.4aicode.com",
  apiKey: "sk-4ai-xxxxxxxxxxxxxxxx",
});

const msg = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello!" }],
});
```

## curl

```bash
curl https://relay.4aicode.com/v1/messages \
  -H "Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 128,
    "messages": [{"role": "user", "content": "ping"}]
  }'
```


**Windows**


## Claude Code CLI

先安装 Claude Code：

### 方式一（推荐）：安装脚本

4AICode 脚本会优先尝试官方安装，失败后自动走 WinGet 和 npm fallback。脚本会自动检查并安装 Node.js、npm、Git。

```powershell
irm https://4aicode.com/claude-install.ps1 | iex
```

无人值守安装并写入 4AICode token：

```powershell
& ([scriptblock]::Create((irm https://4aicode.com/claude-install.ps1))) -ApiKey 'sk-4ai-xxxxxxxxxxxxxxxx'
```

### 方式二：手动配置

先安装 Claude Code：

```powershell
irm https://claude.ai/install.ps1 | iex
```

手动写入用户级环境变量：

```powershell
[Environment]::SetEnvironmentVariable('ANTHROPIC_BASE_URL', 'https://relay.4aicode.com', 'User')
[Environment]::SetEnvironmentVariable('ANTHROPIC_AUTH_TOKEN', 'sk-4ai-xxxxxxxxxxxxxxxx', 'User')
[Environment]::SetEnvironmentVariable('ANTHROPIC_API_KEY', 'sk-4ai-xxxxxxxxxxxxxxxx', 'User')
```

新开 PowerShell 后运行：

```powershell
claude
```

## Claude Code 使用 ChatGPT 模型

```powershell
[Environment]::SetEnvironmentVariable('ANTHROPIC_BASE_URL', 'https://relay.4aicode.com', 'User')
[Environment]::SetEnvironmentVariable('ANTHROPIC_AUTH_TOKEN', 'sk-4ai-xxxxxxxxxxxxxxxx', 'User')
[Environment]::SetEnvironmentVariable('ANTHROPIC_DEFAULT_OPUS_MODEL', 'gpt-5.5', 'User')
[Environment]::SetEnvironmentVariable('ANTHROPIC_MODEL', 'opus', 'User')
```

完整版本适合固定 `gpt-5.5` 超高推理，并在 Claude Code UI 里显示更友好的模型名：

```powershell
[Environment]::SetEnvironmentVariable('ANTHROPIC_BASE_URL', 'https://relay.4aicode.com', 'User')
[Environment]::SetEnvironmentVariable('ANTHROPIC_AUTH_TOKEN', 'sk-4ai-xxxxxxxxxxxxxxxx', 'User')
[Environment]::SetEnvironmentVariable('ANTHROPIC_DEFAULT_OPUS_MODEL', 'gpt-5.5', 'User')
[Environment]::SetEnvironmentVariable('ANTHROPIC_DEFAULT_OPUS_MODEL_NAME', '4AICode GPT 5.5', 'User')
[Environment]::SetEnvironmentVariable('ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES', 'effort,xhigh_effort,thinking,adaptive_thinking,interleaved_thinking', 'User')
[Environment]::SetEnvironmentVariable('ANTHROPIC_MODEL', 'opus', 'User')
[Environment]::SetEnvironmentVariable('ANTHROPIC_DEFAULT_HAIKU_MODEL', 'gpt-5.4-mini', 'User')
[Environment]::SetEnvironmentVariable('CLAUDE_CODE_EFFORT_LEVEL', 'xhigh', 'User')
```

`/v1/messages` 会按 `model` 自动路由：`claude-*` 走 Claude 账号池，`gpt-*` 走 ChatGPT Codex 账号池。

## Node / TypeScript

```ts
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://relay.4aicode.com",
  apiKey: "sk-4ai-xxxxxxxxxxxxxxxx",
});

const msg = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello!" }],
});
```

## curl.exe

```powershell
curl.exe https://relay.4aicode.com/v1/messages `
  -H "Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx" `
  -H "anthropic-version: 2023-06-01" `
  -H "content-type: application/json" `
  -d "{\"model\":\"claude-sonnet-4-6\",\"max_tokens\":128,\"messages\":[{\"role\":\"user\",\"content\":\"ping\"}]}"
```


## 错误码

| 状态码 | 原因 | 处理 |
|---|---|---|
| 401 | token 无效 / 已撤销 | 仪表盘重建 |
| 403 | 团队被暂停 | 联系管理员 |
| 429 | 超限流或超配额 | 看 `X-RateLimit-*` header；详见 [限流](/docs/guides/rate-limit) |
| 503 | 后端账号池临时不可用 | 稍后重试 |

---

源文档：https://4aicode.com/docs/guides/chatgpt

# ChatGPT 配置

用 4AICode token 接入 ChatGPT / Codex 账号池。OpenAI-compatible 端点使用：

- Base URL：`https://relay.4aicode.com/v1`
- API Key：[仪表盘 → 管理 Tokens](https://4aicode.com/tokens) 创建的 `sk-4ai-...`

## 账户准备

- API / SDK / 本机 CLI：只需 4AICode token；Codex App 建议先完成官方登录。
- 手机端远程控制：需要免费 ChatGPT 账户，且 host 必须是 macOS Codex App。

Claude Code 使用 ChatGPT 模型见 [Claude 配置](/docs/guides/claude)。


**macOS / Linux**


## Codex App / 手机端支持

下载页：[Codex App](https://developers.openai.com/codex/app)。

macOS 可作为手机端 host；Linux 走 CLI，本机配置如下。

## Codex CLI 方式一（推荐）：脚本配置

```bash
# 安装，默认 gpt-5.5 + xhigh
curl -fsSL https://4aicode.com/codex-setup.sh | bash -s install sk-4ai-xxxxxxxxxxxxxxxx

# 指定模型
curl -fsSL https://4aicode.com/codex-setup.sh | bash -s install sk-4ai-xxxxxxxxxxxxxxxx gpt-5.4

# 指定模型和推理强度
curl -fsSL https://4aicode.com/codex-setup.sh | bash -s install sk-4ai-xxxxxxxxxxxxxxxx gpt-5.5 high

# 状态
curl -fsSL https://4aicode.com/codex-setup.sh | bash -s status

# 卸载并恢复备份
curl -fsSL https://4aicode.com/codex-setup.sh | bash -s uninstall
```

跑完直接启动：

```bash
codex
```

## Codex CLI 方式二：手动配置

`~/.codex/auth.json`：

```json
{
  "auth_mode": "chatgpt",
  "OPENAI_API_KEY": null,
  "tokens": {
    "id_token": "...",
    "access_token": "...",
    "refresh_token": "...",
    "account_id": "..."
  },
  "last_refresh": "..."
}
```

保留官方登录生成的 `tokens`、`last_refresh` 等字段，只把 `auth_mode` 改为 `chatgpt`，把 `OPENAI_API_KEY` 改为 `null`。

`~/.codex/config.toml`：

```toml
model_provider = "OpenAI"
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
disable_response_storage = true

[model_providers.OpenAI]
name = "4aicode"
base_url = "https://relay.4aicode.com/v1"
wire_api = "responses"
experimental_bearer_token = "sk-4ai-xxxxxxxxxxxxxxxx"
requires_openai_auth = true
```

## Python SDK

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://relay.4aicode.com/v1",
    api_key="sk-4ai-xxxxxxxxxxxxxxxx",
)

resp = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hello!"}],
)
```


**Windows**


## Codex App / 手机端说明

Windows 支持 Codex App 和 Codex CLI 本机使用。下载页：[Codex App](https://developers.openai.com/codex/app)。

Windows 可本机使用 Codex；手机端 host 请用 macOS Codex App。

## Codex CLI 方式一（推荐）：脚本配置

```powershell
# 交互式安装
irm https://4aicode.com/codex-setup.ps1 | iex
```

```powershell
# 非交互安装：直接传 token
& ([scriptblock]::Create((irm https://4aicode.com/codex-setup.ps1))) install 'sk-4ai-xxxxxxxxxxxxxxxx'
```

```powershell
# 指定模型
& ([scriptblock]::Create((irm https://4aicode.com/codex-setup.ps1))) install 'sk-4ai-xxxxxxxxxxxxxxxx' 'gpt-5.4'
```

```powershell
# 指定模型和推理强度
& ([scriptblock]::Create((irm https://4aicode.com/codex-setup.ps1))) install 'sk-4ai-xxxxxxxxxxxxxxxx' 'gpt-5.5' 'high'
```

```powershell
# 状态
& ([scriptblock]::Create((irm https://4aicode.com/codex-setup.ps1))) status

# 卸载并恢复备份
& ([scriptblock]::Create((irm https://4aicode.com/codex-setup.ps1))) uninstall
```

跑完直接启动：

```powershell
codex
```

## Codex CLI 方式二：手动配置

两个文件放在 `%USERPROFILE%\.codex\`。

`auth.json`：

```json
{
  "auth_mode": "chatgpt",
  "OPENAI_API_KEY": null,
  "tokens": {
    "id_token": "...",
    "access_token": "...",
    "refresh_token": "...",
    "account_id": "..."
  },
  "last_refresh": "..."
}
```

保留官方登录生成的 `tokens`、`last_refresh` 等字段，只把 `auth_mode` 改为 `chatgpt`，把 `OPENAI_API_KEY` 改为 `null`。

`config.toml`：

```toml
model_provider = "OpenAI"
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
disable_response_storage = true

[model_providers.OpenAI]
name = "4aicode"
base_url = "https://relay.4aicode.com/v1"
wire_api = "responses"
experimental_bearer_token = "sk-4ai-xxxxxxxxxxxxxxxx"
requires_openai_auth = true
```

## Python SDK

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://relay.4aicode.com/v1",
    api_key="sk-4ai-xxxxxxxxxxxxxxxx",
)

resp = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hello!"}],
)
```


## 模型与推理强度

默认模型是 `gpt-5.5`，默认推理强度是 `xhigh`。

支持模型：`gpt-5.5`、`gpt-5.4`、`gpt-5.4-mini`、`gpt-5.3-codex`、`gpt-5.2`、`gpt-5.2-codex`、`gpt-5.1-codex`、`gpt-5.1-codex-max`。

推理强度：`low`、`medium`、`high`、`xhigh`。

## OpenAI-compatible curl

```bash
curl https://relay.4aicode.com/v1/chat/completions \
  -H "Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role": "user", "content": "ping"}]
  }'
```

## 其他工具

Droid / Pi 使用 OpenAI-compatible endpoint，见 [Droid / Pi](/docs/guides/droid-pi)。

---

源文档：https://4aicode.com/docs/guides/opencode

# OpenCode 配置

OpenCode GUI 客户端走 OpenAI-compatible `chat/completions` 协议。把自定义 provider 指到 4AICode 后，可以在 OpenCode 里使用 `gpt-5.5`、`gpt-5.4`、`gpt-5.4-mini`、`gpt-5.3-codex` 等模型。

## 准备

- 4AICode token：在 [仪表盘 → 管理 Tokens](https://4aicode.com/tokens) 创建，格式是 `sk-4ai-...`
- Provider ID：`4aicode`
- Base URL：`https://relay.4aicode.com/v1`
- 默认模型：`gpt-5.4`
- 代码模型：`gpt-5.3-codex`

## GUI 客户端配置

打开左下角齿轮设置，进入 Provider / Models 配置页，新增一个 OpenAI-compatible 或 Custom provider。

按界面字段填写：

| 字段 | 填写 |
|---|---|
| Provider / Type | `OpenAI Compatible` 或 `Custom` |
| Name / Display name | `4AICode` |
| Provider ID | `4aicode` |
| Base URL / API Base URL | `https://relay.4aicode.com/v1` |
| API Key | `sk-4ai-xxxxxxxxxxxxxxxx` |
| Model ID | `gpt-5.4` |
| Small model ID | `gpt-5.4-mini` |
| Timeout / Request timeout | `600000` ms 或 `600` s |
| Chunk timeout / Stream timeout | `120000` ms 或 `120` s |

保存后回到主界面，在底部模型选择器里选：

```text
4AICode / GPT-5.4
```

然后新建会话，发一句：

```text
你好
```

能正常回复就表示 GUI 配置完成。

## GUI 截图里的超时错误

看到下面这类错误时，重点检查 GUI 里的 timeout 字段：

```text
Provider response headers timed out after 10000ms
```

这是 OpenCode GUI 等待 provider 响应头超时。Codex 上游首包偶尔超过 10 秒，把 GUI 高级设置里的 timeout 调高：

| 字段 | 推荐值 |
|---|---|
| Request timeout / Timeout | `600000` ms |
| Chunk timeout / Stream timeout | `120000` ms |

GUI 没有 timeout 输入框时，用下方 `opencode.json` 方式补齐。

## 配置文件方式

适合 GUI 无法直接填写 timeout 的版本。创建或编辑：

```text
~/.config/opencode/opencode.json
```

写入：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "4aicode": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "4AICode",
      "options": {
        "baseURL": "https://relay.4aicode.com/v1",
        "apiKey": "sk-4ai-xxxxxxxxxxxxxxxx",
        "timeout": 600000,
        "chunkTimeout": 120000
      },
      "models": {
        "gpt-5.5": {
          "name": "GPT-5.5"
        },
        "gpt-5.4": {
          "name": "GPT-5.4"
        },
        "gpt-5.4-mini": {
          "name": "GPT-5.4 Mini"
        },
        "gpt-5.3-codex": {
          "name": "GPT-5.3 Codex"
        }
      }
    }
  },
  "model": "4aicode/gpt-5.4",
  "small_model": "4aicode/gpt-5.4-mini"
}
```

重启 OpenCode GUI 后，在模型选择器里选择 `4AICode / GPT-5.4`。

## 交互式添加凭据

进入项目目录，启动 OpenCode：

```bash
opencode
```

在 OpenCode 里运行：

```text
/connect
```

按提示选择并填写：

```text
Provider: Other
Provider ID: 4aicode
API key: sk-4ai-xxxxxxxxxxxxxxxx
```

然后创建或编辑项目根目录的 `opencode.json`，内容参考上方“配置文件方式”。

回到 OpenCode 后运行：

```text
/models
```

选择 `4AICode` 下的模型。

## 环境变量方式

把 token 放到环境变量里，适合团队共享 `opencode.json`。

```bash
export FOURAICODE_API_KEY="sk-4ai-xxxxxxxxxxxxxxxx"
```

`opencode.json`：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "4aicode": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "4AICode",
      "options": {
        "baseURL": "https://relay.4aicode.com/v1",
        "apiKey": "{env:FOURAICODE_API_KEY}",
        "timeout": 600000,
        "chunkTimeout": 120000
      },
      "models": {
        "gpt-5.5": {
          "name": "GPT-5.5"
        },
        "gpt-5.4": {
          "name": "GPT-5.4"
        },
        "gpt-5.4-mini": {
          "name": "GPT-5.4 Mini"
        },
        "gpt-5.3-codex": {
          "name": "GPT-5.3 Codex"
        }
      }
    }
  },
  "model": "4aicode/gpt-5.4",
  "small_model": "4aicode/gpt-5.4-mini"
}
```

## 全局配置路径

用户级配置放这里：

```text
~/.config/opencode/opencode.json
```

项目级配置放项目根目录：

```text
opencode.json
```

项目级配置优先级更高，适合给单个代码仓库固定 provider 和模型。

## 可用模型

| 模型 | OpenCode model 写法 | 适用场景 |
|---|---|---|
| `gpt-5.5` | `4aicode/gpt-5.5` | 复杂编码、长任务、多文件重构 |
| `gpt-5.4` | `4aicode/gpt-5.4` | 推荐默认选择，通用任务更稳 |
| `gpt-5.4-mini` | `4aicode/gpt-5.4-mini` | 轻量任务、快速验证、成本敏感场景 |
| `gpt-5.3-codex` | `4aicode/gpt-5.3-codex` | 代码优化、Codex 风格任务 |
| `gpt-5.2` | `4aicode/gpt-5.2` | 兼容旧配置 |
| `gpt-5.2-codex` | `4aicode/gpt-5.2-codex` | 兼容旧 Codex 配置 |
| `gpt-5.1-codex` | `4aicode/gpt-5.1-codex` | 兼容旧 Codex 配置 |
| `gpt-5.1-codex-max` | `4aicode/gpt-5.1-codex-max` | 兼容旧 Codex Max 配置 |

模型字段使用 OpenCode 的完整写法，例如 `4aicode/gpt-5.3-codex`。界面展示名可以写成 `GPT-5.3 Codex`。

## 常见问题

### Provider response headers timed out after 10000ms

这是 OpenCode GUI 等待 provider 响应头超时。Codex 上游首包偶尔超过 10 秒，配置里把 `timeout` 和 `chunkTimeout` 调高：

```json
{
  "provider": {
    "4aicode": {
      "options": {
        "baseURL": "https://relay.4aicode.com/v1",
        "timeout": 600000,
        "chunkTimeout": 120000
      }
    }
  }
}
```

然后用 `gpt-5.4-mini` 发一句 `你好` 做快速连通性测试。连通后再切回 `gpt-5.4` 或 `gpt-5.3-codex`。

### 401 Unauthorized

API key 已失效或复制错误。到 [仪表盘 → 管理 Tokens](https://4aicode.com/tokens) 重新创建 token，并更新 `/connect` 凭据或环境变量。

### 400 模型不支持

模型名使用表格里的字面 ID。常用选择是 `4aicode/gpt-5.4` 和 `4aicode/gpt-5.3-codex`。

### 配置后模型列表没出现

检查三项：

- `/connect` 里填写的 Provider ID 是 `4aicode`
- `opencode.json` 里的 provider key 是 `"4aicode"`
- `model` 使用 `4aicode/gpt-5.4` 这种完整写法

## 参考

- [OpenCode Providers](https://opencode.ai/docs/providers/)
- [OpenCode Config](https://opencode.ai/docs/config/)

---

源文档：https://4aicode.com/docs/guides/vscode

# 在 VS Code / Cursor / Windsurf 中使用 4AICode

Anthropic 官方的 **Claude Code 扩展**（2.0+）支持在 VS Code `settings.json` 里直接配置中转地址，**不依赖系统环境变量**，Windows / macOS / Linux 用法完全一致。

Cursor 和 Windsurf 都基于 VS Code，配置方式相同。

## 1. 装扩展

扩展面板搜 **Claude Code**，装作者是 **Anthropic** 的那一个。

## 2. 打开 settings.json

通过命令面板打开，最稳也最快。

1. 打开命令面板：
   - Windows / Linux：`Ctrl + Shift + P`
   - macOS：`Cmd + Shift + P`（⇧⌘P）
2. 输入 **Preferences: Open User Settings (JSON)**，回车

> 如果 `Ctrl/Cmd + Shift + P` 没反应（常见：被输入法或其他工具占用），用 `Ctrl + P` / `Cmd + P` 打开「快速打开」面板，在输入框**首字符打 `>`**（大于号），就会切成命令面板，一样能搜到这条命令。

## 3. 加配置

在 `settings.json` 最外层对象里加 `claudeCode.environmentVariables`：

```json
{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://relay.4aicode.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-4ai-xxxxxxxxxxxxxxxx" }
  ]
}
```

已有其他配置的话合并进去即可，**不要嵌套在别的 key 里**。

要在 Claude Code 面板里使用 ChatGPT `gpt-5.5` 超高推理，把模型和推理强度变量也放进去：

```json
{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://relay.4aicode.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-4ai-xxxxxxxxxxxxxxxx" },
    { "name": "ANTHROPIC_DEFAULT_OPUS_MODEL", "value": "gpt-5.5" },
    { "name": "ANTHROPIC_DEFAULT_OPUS_MODEL_NAME", "value": "4AICode GPT 5.5" },
    {
      "name": "ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES",
      "value": "effort,xhigh_effort,thinking,adaptive_thinking,interleaved_thinking"
    },
    { "name": "ANTHROPIC_MODEL", "value": "opus" },
    { "name": "ANTHROPIC_DEFAULT_HAIKU_MODEL", "value": "gpt-5.4-mini" },
    { "name": "CLAUDE_CODE_EFFORT_LEVEL", "value": "xhigh" }
  ]
}
```

`ANTHROPIC_DEFAULT_OPUS_MODEL` 把 Claude Code 的 `opus` alias 指到 `gpt-5.5`，`CLAUDE_CODE_EFFORT_LEVEL=xhigh` 对应超高推理。

`gpt-*` 会走 ChatGPT Codex 账号池，`claude-*` 会走 Claude 账号池。

## 4. 重启 VS Code

完全退出再重开（关窗口不算，进程起时读一次就不刷新了）：

- Windows：`File → Exit` / `Alt + F4`，再检查系统托盘、任务管理器里的 `Code.exe` 全部结束
- macOS：`Cmd + Q`
- Linux：`File → Exit`

Cursor / Windsurf 同理。

## 5. 验证

打开左侧 Claude Code 面板（装完扩展后有 Anthropic 图标），发一条 `ping`，能回复就通了。

再到 [仪表盘 → 使用记录](https://4aicode.com/dashboard) 确认对应调用。

## 常见问题

**Q：还是弹 "Welcome to Claude Code" 登录界面？**

别点那三个按钮（Claude.ai Subscription / Anthropic Console / Bedrock），点了会走 OAuth 到官方，之后要 `claude logout` 清本地登录态才能回 4AICode。多半是：

1. `claudeCode.environmentVariables` 拼错 / 嵌在别的 key 下 —— 回 settings.json 检查
2. 没完全重启 —— 托盘图标、任务管理器里的 `Code.exe` 全部杀掉再开
3. 用了 `ANTHROPIC_API_KEY` 而不是 `ANTHROPIC_AUTH_TOKEN` —— 扩展 2.0 认后者更稳

**Q：Cursor 自己的 Chat / Agent 会冲突吗？**

不会。Claude Code 是独立面板，Cursor 原生 Chat / Agent / Tab 走 Cursor 自己的后端，互不影响。

**Q：Workspace 配置还是 User 配置？**

推荐写 **User** 级（上面的 **Preferences: Open User Settings (JSON)**），所有项目共享。如果只想在某个项目生效，用 **Preferences: Open Workspace Settings (JSON)**，会写到项目下的 `.vscode/settings.json`。

> ⚠️ Workspace settings 别提交到 git，token 会泄漏。

---

源文档：https://4aicode.com/docs/guides/droid-pi

# 在 Droid 和 Pi 中使用 4AICode

Droid 和 Pi 都按 OpenAI-compatible 方式接入 4AICode。

- Base URL：`https://relay.4aicode.com/v1`
- API key：[仪表盘 → 管理 Tokens](https://4aicode.com/tokens) 创建的 `sk-4ai-...`
- 推荐模型：`gpt-5.5`，轻量任务用 `gpt-5.4-mini`

## Droid

Droid 是 Factory 的命令行编码 Agent。官方文档见 [Factory BYOK](https://docs.factory.ai/cli/byok/overview)。

先把 4AICode token 放进环境变量：

```bash
export RELAY4AI_API_KEY=sk-4ai-xxxxxxxxxxxxxxxx
```

编辑 `~/.factory/settings.json`：

```json
{
  "customModels": [
    {
      "model": "4aicode-gpt-5.5",
      "displayName": "4AICode GPT 5.5",
      "baseUrl": "https://relay.4aicode.com/v1",
      "apiKey": "${RELAY4AI_API_KEY}",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 16384,
      "index": 0,
      "id": "custom:4AICode-GPT-5.5-0"
    },
    {
      "model": "4aicode-gpt-5.4-mini",
      "displayName": "4AICode GPT 5.4 Mini",
      "baseUrl": "https://relay.4aicode.com/v1",
      "apiKey": "${RELAY4AI_API_KEY}",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 16384,
      "index": 1,
      "id": "custom:4AICode-GPT-5.4-Mini-1"
    }
  ],
  "model": "custom:4AICode-GPT-5.5-0",
  "sessionDefaultSettings": {
    "model": "custom:4AICode-GPT-5.5-0"
  }
}
```

保存后重开 Droid，交互模式里运行 `droid`，用 `/model` 选择 `4AICode GPT 5.5`。

这里故意使用 `4aicode-gpt-*` 别名，而不是直接写 `gpt-5.5`。这样 Droid 会按通用 Chat Completions 模型处理，4AICode 网关再把别名映射到真实的 Codex 模型，避免启动时触发 GPT-5 / Responses API 的 provider 校验提示。

Headless 模式示例：

```bash
droid exec --model "custom:4AICode-GPT-5.5-0" "summarize this repository"
```

第二个模型对应：

```bash
droid exec --model "custom:4AICode-GPT-5.4-Mini-1" "fix typos in docs"
```

## Pi

Pi 是 [pi.dev](https://pi.dev/) 的命令行编码 Agent。自定义模型配置文件是 `~/.pi/agent/models.json`，官方文档见 [Pi Custom Models](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/models.md)。

先把 4AICode token 放进环境变量：

```bash
export RELAY4AI_API_KEY=sk-4ai-xxxxxxxxxxxxxxxx
```

编辑 `~/.pi/agent/models.json`：

```json
{
  "providers": {
    "4aicode": {
      "baseUrl": "https://relay.4aicode.com/v1",
      "api": "openai-responses",
      "apiKey": "RELAY4AI_API_KEY",
      "authHeader": true,
      "models": [
        {
          "id": "gpt-5.5",
          "name": "4AICode GPT 5.5",
          "reasoning": true,
          "maxTokens": 16384
        },
        {
          "id": "gpt-5.4-mini",
          "name": "4AICode GPT 5.4 Mini",
          "reasoning": true,
          "maxTokens": 16384
        }
      ]
    }
  }
}
```

运行：

```bash
pi --provider 4aicode --model gpt-5.5
```

在 Pi 交互界面里也可以用 `/model` 切换到 `4AICode GPT 5.5`。

## 验证

配置完成后发一条 `ping`。再到 [仪表盘 → 使用记录](https://4aicode.com/dashboard) 看调用记录，能看到对应模型就配置成功。

---

源文档：https://4aicode.com/docs/guides/hermes

# Hermes Agent（爱马仕）

Hermes Agent 走 OpenAI-compatible `chat/completions` 协议。把它的自定义 endpoint 指到 4AICode，就能在 Hermes 里使用 `gpt-5.5`、`gpt-5.4`、`gpt-5.4-mini` 等模型。

## 准备

- 4AICode token：在 [仪表盘 → 管理 Tokens](https://4aicode.com/tokens) 创建，格式是 `sk-4ai-...`
- Base URL：`https://relay.4aicode.com/v1`
- 推荐模型：`gpt-5.4` 日常使用更稳，`gpt-5.4-mini` 适合轻量任务和成本敏感场景

## 配置

直接运行 Hermes 自带的模型配置向导：

```bash
hermes model
```

按提示依次选择：

```text
More providers...
Custom endpoint (enter URL manually)
```

然后填入：

```text
API base URL: https://relay.4aicode.com/v1
API key: sk-4ai-xxxxxxxxxxxxxxxx
```

接着在模型列表里选择：

```text
gpt-5.4
```

配置完成后运行：

```bash
hermes chat
```

## 可用模型

| 模型 | 适用场景 |
|---|---|
| `gpt-5.5` | 复杂编码、长任务、多文件重构 |
| `gpt-5.4` | 推荐默认选择，通用任务更稳 |
| `gpt-5.4-mini` | 普通问答、简单改文案、小段代码，速度快、成本低 |
| `gpt-5.3-codex` / `gpt-5.2-codex` / `gpt-5.1-codex` | 代码优化模型 |

## 测试

进入 Hermes 后，直接发一句话：

```text
你好，用一句话介绍你自己
```

能正常回复就表示配置成功。

## 常见问题

### Empty response from model

Hermes 使用的是 `/v1/chat/completions`。在 `hermes model` 里填写 Base URL：`https://relay.4aicode.com/v1`，让 Hermes 自动拼出 `/chat/completions`。

重新运行 `hermes model`，确认 Base URL、API key、Model name 三项。

### 看到 response.created / response.completed

这表示客户端收到了 Responses API 的 SSE 事件流。Hermes 需要 Chat Completions 格式，4AICode 的 `/v1/chat/completions` 会自动转换。遇到这种情况，优先检查：

- `base_url` 是否是 `https://relay.4aicode.com/v1`
- 请求路径是否是 `/v1/chat/completions`
- 4AICode 后端是否已经部署到最新版本

### 模型不支持

老模型名如 `gpt-5`、`gpt-5-codex` 已废弃。重新运行 `hermes model`，选择 `gpt-5.4`。

## 参考

- [Hermes Agent AI Providers](https://hermes-agent.nousresearch.com/docs/integrations/providers)
- [Hermes Agent Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration/)
- [掘金：在爱马仕里配置模型](https://juejin.cn/post/7629598396504834100)

---

源文档：https://4aicode.com/docs/guides/gemini

# 使用 Google Gemini

4AICode 的 Gemini 模型走 OpenAI-compatible `chat/completions` 协议。用户侧只需要使用自己的 `sk-4ai-...` token，并把 `model` 换成 `google/gemini-*`。平台后端会自动选择 AI Studio 或 Vertex AI 账号池。

## 可用模型

| 模型 | 推荐场景 |
|---|---|
| `google/gemini-3.1-pro-preview` | 复杂推理、长上下文、预览特性 |
| `google/gemini-3-flash-preview` | 更快响应、预览特性 |
| `google/gemini-2.5-flash` | 日常问答、轻量代码、低成本 |
| `google/gemini-2.5-pro` | 复杂任务、代码分析、稳定质量 |


## 账号池选择

- 用户始终使用 `google/gemini-*` 模型名。
- 平台后端优先使用 `google_vertex` 账号池，便于消耗 Google Cloud 项目额度 / $300 赠金。
- `google_vertex` 不作为用户模型名暴露，也不会在用户费率里单独展示。
- `google_vertex` 账号池不可用时，后端会继续尝试 `google` AI Studio 账号池。

## Python

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://relay.4aicode.com/v1",
    api_key="sk-4ai-xxxxxxxxxxxxxxxx",
)

resp = client.chat.completions.create(
    model="google/gemini-2.5-flash",
    messages=[
        {"role": "user", "content": "用一句话介绍 Gemini"},
    ],
)

print(resp.choices[0].message.content)
```

## TypeScript / Node.js

```ts
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://relay.4aicode.com/v1",
  apiKey: "sk-4ai-xxxxxxxxxxxxxxxx",
});

const resp = await client.chat.completions.create({
  model: "google/gemini-2.5-flash",
  messages: [{ role: "user", content: "写一个 TypeScript hello world" }],
});

console.log(resp.choices[0].message.content);
```

## curl

```bash
curl https://relay.4aicode.com/v1/chat/completions \
  -H "Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash",
    "messages": [
      {"role": "user", "content": "ping"}
    ]
  }'
```

## 流式输出

```bash
curl https://relay.4aicode.com/v1/chat/completions \
  -H "Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash",
    "stream": true,
    "messages": [
      {"role": "user", "content": "写一个 Go hello world"}
    ]
  }'
```

返回格式仍是 OpenAI SSE：

```text
data: {"choices":[{"delta":{"content":"Hello"}}]}
data: [DONE]
```

## 图片输入

Gemini 当前支持 base64 data URL 图片输入：

```python
resp = client.chat.completions.create(
    model="google/gemini-2.5-flash",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "描述这张图"},
            {
                "type": "image_url",
                "image_url": {
                    "url": "data:image/png;base64,iVBORw0KGgo..."
                },
            },
        ],
    }],
)
```

远程 `https://...` 图片 URL 当前会返回明确错误。先把图片下载并转成 base64 data URL 再发送。

## 常见错误

| 错误 | 处理 |
|---|---|
| `model not supported` | 确认模型名是上表之一 |
| `no available google account` | 平台 AI Studio 账号池暂时不可用，联系管理员 |
| `quota exceeded` | 余额或配额不足，充值或联系团队管理员 |
| `upstream error` | Google 上游波动或 API key 额度问题，稍后重试 |

## 管理员说明

普通用户只需要 `sk-4ai-...` token。平台管理员需要先把 Google API key 或 Vertex AI service account 加入账号池，见 [Google Gemini Relay 配置](/docs/ops/google-gemini-relay)（仅管理员可见）。

---

源文档：https://4aicode.com/docs/guides/account-cooldown

# 账号冷却机制

偶尔一个请求 503、下一秒重试又好了——这就是冷却机制在工作。

## 原理

4AICode 背后是**账号池**，请求自动分配到池里健康的账号。官方账号会临时不健康：

- 触发官方每 5 小时消息数墙
- 订阅到期 / 临时风控
- 网络抖动

检测到后，4AICode 会**临时冷藏这个账号**，避免下次再踩。冷藏结束自动回池。

## 99% 情况透明

只要池里还有至少一个健康账号，请求自动切过去，你看到的是正常 200。

## 极端：整个池同时冷却

非常罕见。响应：

```json
{
  "code": "no_account_available",
  "message": "all accounts cooling down, retry in 60s"
}
```

HTTP `503`。`retry in Xs` 告诉你预期多久恢复。

## 处理

✅ 指数退避重试（1s / 2s / 4s / 8s…），SDK 默认都带
✅ 把 503 当"短暂维护"处理

❌ 对 503 立即暴力重试——拖慢恢复
❌ 当永久故障报警——通常 1~5 分钟恢复
❌ 联系客服催，除非**持续 15 分钟以上**都 503

## 连续 15 分钟 503

池里账号批量出问题：

- 邮件 support@4aicode.com
- 查平台状态页

## FAQ

**Q：能手动指定账号吗？**
A：不能，调度器比你更清楚哪个健康。

**Q：冷却多长？**
A：几分钟到 24 小时不等，用户不用关心。

**Q：付费用户凭什么共享池？**
A：池够大、调度够聪明，可用率优于"自己开订阅"。单账号一个人用经常撞 5 小时墙，池化反而更稳。

---

源文档：https://4aicode.com/docs/guides/rate-limit

# 限流

4AICode 对每个团队和 token 都有**每分钟请求数**上限，防止脚本跑飞或泄漏 token 被刷爆。

## 两层

| 层级 | 默认 | 说明 |
|---|---|---|
| **团队**（org 级）| 120 次 / 分钟 | 团队所有 token 总和 |
| **单 token** | 60 次 / 分钟 | 每个 `sk-4ai-...` 独立 |

任一层触顶即 429，两层独立判定。

> 这是每分钟请求数，不是 token 消耗。token 消耗走 [配额](/docs/guides/quota)。

## 超限响应

HTTP `429`：

```json
{
  "code": "rate_limited",
  "message": "org rate limit exceeded, retry in 30s"
}
```

响应头：

| Header | 含义 |
|---|---|
| `X-RateLimit-Limit` | 本层级每分钟上限 |
| `X-RateLimit-Remaining` | 本分钟剩余次数 |
| `X-RateLimit-Reset` | 秒数到重置 |

## 处理

- **用 SDK** — OpenAI / Anthropic SDK 自带指数退避重试
- **自己写 HTTP** — 看 `X-RateLimit-Reset` 指数退避

```python
for attempt in range(5):
    r = requests.post(url, headers=..., json=...)
    if r.status_code != 429:
        break
    wait = int(r.headers.get("X-RateLimit-Reset", 2 ** attempt))
    time.sleep(wait)
```

**不要**：

- ❌ 无脑立即重试
- ❌ 多 token 绕限流（团队级照样挡，还会被标记可疑流量）

## 不够用？

- 找管理员调高团队限额
- 邮件 support@4aicode.com 说明用途

**不要多开账号绕过**，小号会被风控。

## 不计入限流的请求

- 401（鉴权失败）—— 没进入限流器
- 429 quota_exceeded —— 已在另一层被挡
- `/health` 等状态查询

大量 401 不会把团队刷死，但**暴露 token 有问题**，尽快修。

---

源文档：https://4aicode.com/docs/guides/quota

# 配额

4AICode 按 **token 总量**计费（prompt + completion 合算），每个团队有**月度配额**。

## 单位：什么是 token

不是字符也不是单词。粗估：

- 英文：1 token ≈ 3~4 字符 / 0.75 单词
- 中文：1 汉字 ≈ 1~2 token
- 代码：介于英中之间

例：1000 字中文文档 ≈ 1500~2000 输入 token；500 字回答 ≈ 800~1000 输出 token。

## 月度配额

- **个人账号**：注册送免费额度
- **团队**：按套餐设定

进度在**仪表盘 → 查看用量**里每分钟刷新。每月 **1 日 00:00 UTC** 清零重置。

## 超额

立即返回 HTTP `429`：

```json
{
  "code": "quota_exceeded",
  "message": "monthly quota reached, contact admin"
}
```

请求没打到上游，**不扣费**。下个月 1 号自动恢复。

## 控成本

### 选小模型

- `claude-haiku-*` 比 sonnet / opus 便宜一个数量级
- `gpt-5.4-mini` 比 `gpt-5.4` 便宜

简单任务（摘要、分类、翻译）**先试 haiku / mini**。

### 控 `max_tokens`

Anthropic `/v1/messages` 必传 `max_tokens`。按实际需要设，**别默认 4096**：

```json
{
  "max_tokens": 512,
  "messages": [...]
}
```

输出截短再续，永远比一次开天价便宜。

### 系统提示去重

长 `system`（几千字）每次重发很贵：

- 用 **Prompt Caching**（Claude 原生支持）让提示词只计费一次
- 稳定内容放开头，可变内容放末尾

### 流 / 非流同价

`stream: true` 不影响计费。

## 提额

联系管理员 / support@4aicode.com，管理员 30 秒改完。

## FAQ

**Q：能看每个 token 分别花了多少吗？**
A：能，用量页面按 token 筛。

**Q：什么时候计费？**
A：响应完成（或流式断开）那一刻。4xx / 5xx 不计费。

**Q：能限某个 token 只能花团队配额的 20% 吗？**
A：暂不支持子配额，目前靠**撤销 + 控发放**约束。

---

源文档：https://4aicode.com/docs/api/messages

# POST /v1/messages

Anthropic 官方 `/v1/messages` 协议，字段与官方完全一致，现有 Anthropic SDK 代码几乎可直接迁移。

## 端点

```
POST https://relay.4aicode.com/v1/messages
```

## 请求

```http
POST /v1/messages HTTP/1.1
Host: relay.4aicode.com
Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx
anthropic-version: 2023-06-01
content-type: application/json

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "stream": true,
  "messages": [
    { "role": "user", "content": "Say hi" }
  ]
}
```

### 必填

| 字段 | 说明 |
|---|---|
| `model` | Claude 模型（Sonnet / Haiku / Opus 系列）或支持的 `gpt-*` 模型 |
| `max_tokens` | 最多生成 token 数 |
| `messages` | 对话数组 |

`/v1/messages` 会按 `model` 自动路由：`claude-*` 走 Claude 账号池，`gpt-*` 走 ChatGPT Codex 账号池。ChatGPT 模型适合 Claude Code 这类固定 Anthropic Messages 协议的客户端。

### 常用可选

| 字段 | 说明 |
|---|---|
| `stream` | `true` 启用 SSE |
| `system` | 系统提示词 |
| `temperature` | 0~1 |
| `tools` | Function calling |
| `stop_sequences` | 遇到就停 |

## 流式响应

`stream: true` 返回 `text/event-stream`，事件序列与官方一致：

```
event: message_start
event: content_block_start
event: content_block_delta
event: content_block_stop
event: message_delta
event: message_stop
```

relay 全程不缓冲 SSE，首字节延迟基本等同直连。

## 非流式响应

```json
{
  "id": "msg_xxxx",
  "type": "message",
  "role": "assistant",
  "content": [{ "type": "text", "text": "Hi!" }],
  "model": "claude-sonnet-4-6",
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 8, "output_tokens": 3 }
}
```

`usage` 是计费依据（详见 [配额](/docs/guides/quota)）。

## ChatGPT 模型

Claude Code 使用 ChatGPT 模型时，只需要把模型设为支持的 `gpt-*`：

```bash
export ANTHROPIC_BASE_URL=https://relay.4aicode.com
export ANTHROPIC_AUTH_TOKEN=sk-4ai-xxxxxxxxxxxxxxxx
export ANTHROPIC_DEFAULT_OPUS_MODEL=gpt-5.5
export ANTHROPIC_DEFAULT_OPUS_MODEL_NAME="4AICode GPT 5.5"
export ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES=effort,xhigh_effort,thinking,adaptive_thinking,interleaved_thinking
export ANTHROPIC_MODEL=opus
export ANTHROPIC_DEFAULT_HAIKU_MODEL=gpt-5.4-mini
export CLAUDE_CODE_EFFORT_LEVEL=xhigh
claude --effort xhigh
```

`ANTHROPIC_DEFAULT_OPUS_MODEL` 会让 Claude Code 向 relay 请求 `gpt-5.5`。`CLAUDE_CODE_EFFORT_LEVEL=xhigh` 会通过 Anthropic `output_config.effort` 映射到 OpenAI Responses `reasoning.effort=xhigh`。

支持的模型与 `/v1/chat/completions` 一致：`gpt-5.5`、`gpt-5.4`、`gpt-5.4-mini`、`gpt-5.3-codex`、`gpt-5.2`、`gpt-5.2-codex`、`gpt-5.1-codex`、`gpt-5.1-codex-max`。

## 错误

| HTTP | 含义 |
|---|---|
| **400** | 字段错误（缺 `max_tokens`、`model` 不存在等） |
| **401** | token 无效 |
| **403** | 团队被暂停 |
| **429** | 超限流或超配额 |
| **502** | 上游 Claude 抖动，重试即可 |
| **503** | 账号池临时全冷却，详见 [账号冷却](/docs/guides/account-cooldown) |

`503` 示例：

```json
{
  "code": "no_account_available",
  "message": "all accounts cooling down, retry in 60s"
}
```

## 完整例子（Python）

```python
from anthropic import Anthropic

client = Anthropic(
    base_url="https://relay.4aicode.com",
    api_key="sk-4ai-xxxxxxxxxxxxxxxx",
)

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=512,
    messages=[{"role": "user", "content": "用一句话介绍你自己"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
```

---

源文档：https://4aicode.com/docs/api/responses

# POST /v1/responses

OpenAI 新一代"单轮输入 + 流式输出"接口，**Codex CLI** 和较新的 OpenAI SDK 使用。

只用 `/v1/chat/completions` 或 `/v1/messages` 的话，不需要了解这个。

## 端点

```
POST https://relay.4aicode.com/v1/responses
```

## 与 chat/completions 的区别

| 维度 | `/v1/chat/completions` | `/v1/responses` |
|---|---|---|
| 输入 | `messages` 数组 | `input` 数组（更像事件流） |
| 工具调用 | `tool_calls` / `tool_messages` | 内置 `function_call` / `function_call_output` 事件 |
| 流事件 | `data: {...}` chunk | 命名事件 `response.output_text.delta` 等 |
| 场景 | 聊天应用 | Codex CLI、Agent 框架 |

## 请求

```http
POST /v1/responses HTTP/1.1
Host: relay.4aicode.com
Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx
content-type: application/json

{
  "model": "gpt-5.5",
  "input": [
    { "role": "user", "content": "Refactor main.go" }
  ],
  "stream": true
}
```

### 支持的模型

与 `/v1/chat/completions` 一致：`gpt-5.5`、`gpt-5.4`、`gpt-5.4-mini`、`gpt-5.3-codex`、`gpt-5.2`、`gpt-5.2-codex`、`gpt-5.1-codex`、`gpt-5.1-codex-max`。`gpt-5.5` 跟随 OpenAI 在 ChatGPT / Codex 的渐进 rollout，relay 收到账号级模型不支持时会自动换号重试。其他模型 `400`。

## 流式响应

```
event: response.created
data: {"response": {"id": "resp_...", ...}}

event: response.output_text.delta
data: {"delta": "package main\n"}

event: response.output_text.done
data: {}

event: response.completed
data: {"response": {...}, "usage": {...}}
```

非流式返回 `{ response, usage }` 一次性包。

## Function calling / tools

`tools` 字段透传，行为与官方一致：

```
event: response.output_item.added
data: {"item": {"type": "function_call", "name": "...", "arguments": "..."}}
```

工具结果按官方协议发 `function_call_output`。

## 错误

| HTTP | 含义 |
|---|---|
| **400** | `input` 格式错 / `model` 不在 allowlist |
| **401** | token 无效 |
| **403** | 团队被暂停 |
| **429** | 超限流或超配额 |
| **502** | 上游 OpenAI 抖动 |
| **503** | 账号池临时全冷却，详见 [账号冷却](/docs/guides/account-cooldown) |

## 什么时候用

- ✅ 用 **Codex CLI**（官方走这个）
- ✅ 最新的 OpenAI Agents SDK
- ❌ 聊天机器人 → 用 [`/v1/chat/completions`](/docs/api/chat-completions)

---

源文档：https://4aicode.com/docs/api/chat-completions

# POST /v1/chat/completions

OpenAI 兼容协议，字段与官方一致。用于：

- OpenAI 官方 SDK（`openai-python` / `openai` npm）
- 任何改 `base_url` 即可对接的 OpenAI 兼容客户端
- Cursor / Cline / Continue 等 IDE 插件
- LangChain / LlamaIndex 等框架

## 端点

```
POST https://relay.4aicode.com/v1/chat/completions
```

## 请求

```http
POST /v1/chat/completions HTTP/1.1
Host: relay.4aicode.com
Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx
content-type: application/json

{
  "model": "gpt-5.5",
  "stream": true,
  "messages": [
    { "role": "system", "content": "You are helpful." },
    { "role": "user",   "content": "Write fizzbuzz in Go." }
  ]
}
```

## 支持的模型

GPT-5 系列：

| 模型 | 适用 |
|---|---|
| `gpt-5.5` | 新一代通用模型，复杂编码和长任务优先 |
| `gpt-5.4` | 通用，当前默认 |
| `gpt-5.4-mini` | 便宜 + 快，日常够用 |
| `gpt-5.3-codex` / `gpt-5.2-codex` / `gpt-5.1-codex` / `gpt-5.1-codex-max` | 代码优化 |
| `gpt-5.2` | 过渡版本 |

Google Gemini：

| 模型 | 适用 |
|---|---|
| `google/gemini-3.1-pro-preview` | Google Gemini Pro 预览 |
| `google/gemini-3-flash-preview` | Google Gemini Flash 预览 |
| `google/gemini-2.5-flash` | Google Gemini Flash 稳定款 |
| `google/gemini-2.5-pro` | Google Gemini Pro 稳定款 |

老名字（`gpt-5`、`gpt-5-codex`）已被上游废弃。其他模型（`gpt-4o`、`gpt-4` 等）会 `400` 拒绝，错误信息里带可用清单。

> 4AICode 池里是 ChatGPT Plus / Pro 订阅，`gpt-5.5` 跟随 OpenAI 在 ChatGPT / Codex 的渐进 rollout；relay 收到账号级模型不支持时会自动换号重试。

## 被忽略的参数

接受但不生效（兼容 SDK 不报错）：

- `logit_bias`
- `user`
- `functions`（用新版 `tools`）

## 响应

与 OpenAI 官方一致：

- `choices[].message.content`
- `choices[].finish_reason`
- `usage`（`prompt_tokens` / `completion_tokens` / `total_tokens`）

流式格式：

```
data: {"choices":[{"delta":{"content":"Hello"}}]}
data: {"choices":[{"delta":{"content":", world"}}]}
data: [DONE]
```

## 完整例子

### Python

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://relay.4aicode.com/v1",
    api_key="sk-4ai-xxxxxxxxxxxxxxxx",
)

resp = client.chat.completions.create(
    model="gpt-5.4",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "用一句话介绍你自己"},
    ],
)
print(resp.choices[0].message.content)
```

### TypeScript

```ts
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://relay.4aicode.com/v1",
  apiKey: process.env.OPENAI_API_KEY,
});

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

## 错误

| HTTP | 含义 |
|---|---|
| **400** | 字段错 / 模型不在 allowlist |
| **401** | token 无效 |
| **403** | 团队被暂停 |
| **429** | 超限流或超配额 |
| **502** | 上游 OpenAI 抖动 |
| **503** | 账号池临时全冷却，详见 [账号冷却](/docs/guides/account-cooldown) |

## 与 `/v1/messages` 的差异

| 维度 | `/v1/messages` | `/v1/chat/completions` |
|---|---|---|
| 协议 | Anthropic | OpenAI |
| 可用模型 | Claude 全系 | `gpt-5*` / `google/gemini-*` |
| 必填字段 | `max_tokens` | — |
| usage 字段 | `input_tokens` / `output_tokens` | `prompt_tokens` / `completion_tokens` |

---

源文档：https://4aicode.com/docs/api/images

# POST /v1/images/*

OpenAI Images 兼容接口，用 `gpt-image-2` 生成图片或基于参考图改图。使用方式和 OpenAI SDK 基本一致：把 `base_url` 指到 4AICode，把 `api_key` 换成你的 `sk-4ai-...` Token。

图片生成按次从钱包余额扣费。控制台的 [图片生成](/images) 页面适合手动使用；API 适合接入自己的应用、工作流和自动化脚本。

## 端点

```text
POST https://relay.4aicode.com/v1/images/generations
POST https://relay.4aicode.com/v1/images/edits
```

## 支持的模型

| 模型 | 用途 | 计费 |
|---|---|---|
| `gpt-image-2` | 文本生图、参考图改图 | 按次从钱包扣费 |

管理员启用 `gpt-image-2` 费率后可用。模型未启用时会返回 `503 model_unavailable`。

## 文本生图

### curl

```bash
curl https://relay.4aicode.com/v1/images/generations \
  -H "Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean product shot of a black mechanical keyboard on a white desk",
    "size": "1024x1024",
    "quality": "medium",
    "response_format": "b64_json"
  }'
```

### Python

```python
import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://relay.4aicode.com/v1",
    api_key="sk-4ai-xxxxxxxxxxxxxxxx",
)

resp = client.images.generate(
    model="gpt-image-2",
    prompt="A clean product shot of a black mechanical keyboard on a white desk",
    size="1024x1024",
    quality="medium",
    response_format="b64_json",
)

image_base64 = resp.data[0].b64_json
with open("keyboard.png", "wb") as f:
    f.write(base64.b64decode(image_base64))
```

### TypeScript

```ts
import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://relay.4aicode.com/v1",
  apiKey: process.env.OPENAI_API_KEY,
});

const resp = await client.images.generate({
  model: "gpt-image-2",
  prompt: "A clean product shot of a black mechanical keyboard on a white desk",
  size: "1024x1024",
  quality: "medium",
  response_format: "b64_json",
});

const image = resp.data[0]?.b64_json;
if (!image) throw new Error("image generation failed");
fs.writeFileSync("keyboard.png", Buffer.from(image, "base64"));
```

## 参考图改图

`/v1/images/edits` 支持两种输入方式：

- `multipart/form-data`：字段名用 `image` 或 `image[]` 上传文件，单文件最大 20MB。
- `application/json`：`images[].image_url` 传 base64 data URL 或可访问的图片 URL。

### multipart curl

```bash
curl https://relay.4aicode.com/v1/images/edits \
  -H "Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx" \
  -F model="gpt-image-2" \
  -F prompt="Keep the product, replace the background with a bright studio setup" \
  -F size="1024x1024" \
  -F quality="medium" \
  -F response_format="b64_json" \
  -F image="@./product.png"
```

多张参考图：

```bash
curl https://relay.4aicode.com/v1/images/edits \
  -H "Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx" \
  -F model="gpt-image-2" \
  -F prompt="Combine these references into one cohesive hero image" \
  -F image[]="@./subject.png" \
  -F image[]="@./style.png"
```

### JSON data URL

```bash
IMAGE_B64="$(base64 < product.png | tr -d '\n')"

curl https://relay.4aicode.com/v1/images/edits \
  -H "Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"gpt-image-2\",
    \"prompt\": \"Put this product in a premium ecommerce scene\",
    \"size\": \"1024x1024\",
    \"quality\": \"medium\",
    \"response_format\": \"b64_json\",
    \"images\": [
      { \"image_url\": \"data:image/png;base64,${IMAGE_B64}\" }
    ]
  }"
```

`file_id` 当前会返回明确错误。需要 mask 时用 `mask` 文件字段，或在 JSON 里传 `mask.image_url`。

## 参数

| 参数 | 适用端点 | 说明 |
|---|---|---|
| `model` | 全部 | 固定使用 `gpt-image-2` |
| `prompt` | 全部 | 生成或编辑指令，必填 |
| `size` | 全部 | `auto`、`1024x1024`、`1536x1024`、`1024x1536` |
| `quality` | 全部 | `auto`、`low`、`medium`、`high` |
| `response_format` | 全部 | `b64_json` 或 `url`；`url` 返回 data URL |
| `output_format` | 全部 | `png`、`jpeg`、`webp` |
| `background` | 全部 | 透传给上游图片工具 |
| `output_compression` | 全部 | 输出压缩比例，适用于支持压缩的格式 |
| `stream` | 全部 | `true` 时返回 SSE |
| `partial_images` | 全部 | 流式模式下请求部分图片事件 |
| `image` / `image[]` | edits | multipart 参考图 |
| `images[].image_url` | edits | JSON 参考图 URL 或 data URL |
| `mask` / `mask.image_url` | edits | 可选蒙版 |
| `input_fidelity` | edits | 参考图保真度，透传给上游图片工具 |

## 响应

非流式返回 OpenAI Images 风格结构：

```json
{
  "created": 1770000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgo...",
      "revised_prompt": "..."
    }
  ],
  "size": "1024x1024",
  "quality": "medium",
  "output_format": "png",
  "usage": {
    "images": 1
  }
}
```

`response_format=url` 时，`data[].url` 是 `data:image/png;base64,...`，图片内容直接在响应内返回。

## 流式响应

设置 `"stream": true` 后返回 SSE。

文本生图事件：

```text
event: image_generation.partial_image
data: {"type":"image_generation.partial_image","partial_image_index":0,"b64_json":"..."}

event: image_generation.completed
data: {"type":"image_generation.completed","b64_json":"...","usage":{"images":1}}
```

参考图改图事件前缀是 `image_edit`：

```text
event: image_edit.completed
data: {"type":"image_edit.completed","b64_json":"...","usage":{"images":1}}
```

## 计费与记录

每次成功生成按 `gpt-image-2` 的当前单次价格扣费。用量页、钱包流水和后台 usage log 会记录模型、次数、费用、状态和 trace id。平台默认不保存你的 prompt 和图片正文。

## 常见错误

| HTTP | code | 处理方式 |
|---|---|---|
| 400 | `invalid_request_error` | 检查 `prompt`、`model`、图片字段和 multipart 格式 |
| 401 | `unauthorized` | 检查 `Authorization: Bearer sk-4ai-...` |
| 429 | `insufficient_quota` / `rate_limit` | 充值钱包或降低并发 |
| 503 | `model_unavailable` | 联系管理员启用 `gpt-image-2` 单次费率 |
| 502 | `upstream_error` | 稍后重试；持续失败时带 trace id 联系支持 |