# POST /v1/chat/completions

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

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

## 端点

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

## 请求

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

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

## 支持的模型

GPT-6 系列：

| 模型 | 适用 |
|---|---|
| `gpt-6-astra` | 新一代旗舰模型；短上下文输入 $1.50/M、输出 $7.50/M（官方价 1.5 折） |
| `gpt-6.1-sol` | GPT-6.1 旗舰，复杂编码和长任务；输入 $0.30/M、输出 $1.50/M（官方价 1.5 折） |
| `gpt-6-sol` | GPT-6 旗舰，复杂编码和长任务；输入 $0.30/M、输出 $1.50/M（官方价 1.5 折） |
| `gpt-6-luna` | GPT-6 轻量模型，快速日常任务；输入 $0.015/M、输出 $0.075/M（官方价 1.5 折） |

GPT-5 系列：

| 模型 | 适用 |
|---|---|
| `gpt-5.6-sol` | 旗舰，复杂编码和长任务优先，支持 `max` 推理强度 |
| `gpt-5.6-terra` | 均衡档，性价比高 |
| `gpt-5.6-luna` | 便宜 + 快，日常够用 |
| `gpt-5.5` | 上一代通用模型 |
| `gpt-5.4` | 通用 |
| `gpt-5.4-mini` | 便宜 + 快 |
| `gpt-5.3-codex` | 代码优化 |

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.2 及以下型号已被上游废弃。其他模型（`gpt-4o`、`gpt-4` 等）会 `400` 拒绝，错误信息里带可用清单。

> 模型可用性取决于上游支持范围和服务状态；上游返回模型不支持时，relay 会直接返回明确的 `400`。

## 被忽略的参数

接受但不生效（兼容 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.net/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.net/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` |