Chat Completions — Markdown 源文

> **AI Agents**: 索引 `/api/llms.txt` | 英文全文 `/api/llms-full-en.txt` | 中文全文 `/api/llms-full-zh.txt` | OpenAPI `/api/openapi.yaml`
> Base URL: `<BASE_URL>/v1`

# Chat Completions

为多轮对话创建模型回复。

```
POST <BASE_URL>/v1/chat/completions
```

> **协议说明**：本接口是 OpenAI **形态**入口，可调用目录中任意可售卖模型。客户端形态与上游协议可不一致，由网关转换（如调 `anthropic/*` 时转 Anthropic Messages）。发图到 Claude 请用 [`/v1/messages`](./messages.md)。

## 认证

必需：`Authorization: Bearer <API_KEY>`

## 请求头

| 头 | 必需 | 说明 |
|----|------|------|
| `Authorization` | 是 | Bearer API Key |
| `Content-Type` | 是 | `application/json` |
| `Idempotency-Key` | 否 | 24 小时内防止重复调用 |
| `Accept-Language` / `X-Locale` | 否 | 影响部分错误的本地化文案 |

## 请求体

SupaNexus 接受 **OpenAI Chat Completions** JSON 格式，识别 `model` 与 `stream`；其余字段按 OpenAI 兼容方式处理。多模态（图片 `image_url`、视频 `video_url` 仅公网 URL）见 [参数 → 多模态输入](./parameters.md)。

```json
{
  "model": "deepseek/deepseek-chat",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "stream": false,
  "temperature": 0.7,
  "max_tokens": 1024
}
```

| 字段 | 必需 | 说明 |
|------|------|------|
| `model` | 是 | `GET /v1/models` 返回的模型 id（如 `deepseek/deepseek-chat`） |
| `messages` | 是 | OpenAI 格式消息数组 |
| `stream` | 否 | `true` 启用 SSE 流式 — 见 [流式响应](./streaming.md) |

## 非流式响应

返回 OpenAI 兼容 JSON。示例：

```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Hello! How can I help?"},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 2000,
    "completion_tokens": 300,
    "total_tokens": 2300,
    "prompt_tokens_details": {
      "cached_tokens": 1500
    }
  }
}
```

`prompt_tokens_details.cached_tokens`（OpenAI）表示 **命中 Prompt Cache** 的输入 token 数。SupaNexus 据此与平台配置的 [缓存输入单价](/help/prompt-cache-pricing) 计费；未配置分档时仍按全部输入 token 计 **输入价**。

## 用量与 Prompt Cache 计费

SupaNexus **不运行** Prompt Cache，但会 **读取** 响应 `usage` 中的缓存字段并计入账单：

| 服务商 | 典型字段 |
|------|----------|
| OpenAI | `usage.prompt_tokens_details.cached_tokens` |
| Anthropic | `usage.cache_read_input_tokens` |

计费（简化）：

```
费用 ≈ (prompt_tokens − cached_hit) × 输入单价
     + cached_hit × 缓存输入单价
     + completion_tokens × 输出单价
```

价目表以 [模型广场](https://console.supanexus.ai/models) 为准，详见 [模型定价](./model-pricing.md)。服务端用量明细可含 `cached_input_tokens`。

## 响应头（SupaNexus）

| 头 | 说明 |
|----|------|
| `X-SNX-Trace-ID` | 唯一请求 ID，联系支持时可提供 |
| `X-SNX-Model` | 本次请求使用的模型 id |
| `X-SNX-Provider` | 实际提供推理的服务商标识 |

## 幂等

发送 `Idempotency-Key: <唯一字符串>` 可在 **24 小时** 内按 API Key 去重。若 Key 已处理过：

- **HTTP 409**
- `error.code`: `duplicate_request`

未提供 `Idempotency-Key` 时，可能回退使用 `X-SNX-Trace-ID`。

## 路由

SupaNexus 根据你请求的模型 id 选择可用服务。若暂时无法完成请求，可能返回 **502** 或 **503**。

## 数据与隐私

SupaNexus **不保存跨请求的对话历史**：每次请求由调用方自行拼装 `messages[]`。

| 处理方式 | 说明 |
|----------|------|
| 请求体 | SupaNexus 默认**不持久化** prompt/completion 正文 |
| 用量记录 | 调用时间、模型、Token 数量等计费所需信息 |
| 排障 | 联系支持时可提供 `X-SNX-Trace-ID` |

开发者控制台**文本对话**体验窗中的聊天记录仅保存在**当前浏览器会话**；刷新或关闭页面后不会从 SupaNexus 服务端恢复。

详见 [隐私政策](/privacy) 与 [服务条款](/terms)。

## 常见错误

| HTTP | 说明 |
|------|------|
| 400 | 缺少 `model`、JSON 无效；非法 `video_url`（非公网 http(s)） |
| 401 | 认证失败 |
| 413 | 请求体超过默认 **64 MB** |
| 402 | 账户余额不足（`error.code=402`） |
| 404 | 未知或不可用模型 |
| 408 | 请求超时（默认 120s） |
| 409 | 幂等冲突 |
| 429 | 用量配额已用尽 |
| 502 | 服务暂时不可用 |
| 503 | 服务暂时不可用 |

完整说明见 [错误处理](./errors.md)。

## 相关

- [参数](./parameters.md)
- [流式响应](./streaming.md)
- [Messages（Anthropic）](./messages.md)
- [模型定价](./model-pricing.md)
- [响应头](./response-headers.md)