# API 参考

TokenFlows 提供 OpenAI 兼容协议和 Anthropic 兼容协议。你可以按 SDK、工具或模型类型选择对应端点。

## 基础 URL

| 协议 | Base URL | 说明 |
| --- | --- | --- |
| OpenAI 兼容协议 | `https://api.tokenflows.org/v1` | 适用于 OpenAI SDK、Chat Completions、Responses API、模型列表 |
| Anthropic 兼容协议 | `https://api.tokenflows.org` | Claude Code 环境变量使用根地址；直接请求 Messages API 时使用 `/v1/messages` |

> Claude Code 的 `ANTHROPIC_BASE_URL` 请填写 `https://api.tokenflows.org`，不要加 `/v1`。

## 认证

OpenAI 兼容协议使用 `Authorization` 头：

```http
Authorization: Bearer YOUR_API_KEY
```

Anthropic 兼容协议推荐使用 `x-api-key` 头，也兼容 Bearer Token：

```http
x-api-key: YOUR_API_KEY
```

```http
Authorization: Bearer YOUR_API_KEY
```

## OpenAI Chat Completions

```http
POST /v1/chat/completions
```

完整地址：

```text
https://api.tokenflows.org/v1/chat/completions
```

### 常用参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 模型 ID，见 [模型列表](/models) |
| `messages` | array | 是 | 消息列表 |
| `temperature` | number | 否 | 采样温度 |
| `max_tokens` | integer | 否 | 最大生成 token 数 |
| `stream` | boolean | 否 | 是否流式输出 |

### 示例请求

```json
{
  "model": "gpt-5.5",
  "messages": [
    {"role": "system", "content": "你是一个 helpful assistant。"},
    {"role": "user", "content": "介绍一下 TokenFlows"}
  ],
  "temperature": 0.7,
  "max_tokens": 1024
}
```

### 示例响应

```json
{
  "id": "chatcmpl_xxx",
  "object": "chat.completion",
  "created": 1718000000,
  "model": "gpt-5.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "TokenFlows 是一个面向开发者和 AI Agent 的模型网关。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 100,
    "total_tokens": 120
  }
}
```

## OpenAI Responses API

```http
POST /v1/responses
```

完整地址：

```text
https://api.tokenflows.org/v1/responses
```

Responses API 适合 GPT 系列、推理任务、工具调用和 Agent 工作流。

### 示例请求

```json
{
  "model": "gpt-5.5",
  "input": "用三句话介绍 TokenFlows"
}
```

## 图片生成（Images）

GPT 图片模型（`gpt-image-2.5-flare`、`gpt-image-2.5-sunburst`）使用 OpenAI Images 协议，按生成张数计费。在 Codex 中通过技能调用的方式见 [用 Codex 生成图片](/docs/codex-image)。

> GPT 图片模型一律返回 Base64 编码的图片（`b64_json`），不支持 `response_format` 参数；旧版 DALL·E 模型的 `url` 返回和 `style` 参数不适用于本系列。

### 文生图

```http
POST /v1/images/generations
```

完整地址：

```text
https://api.tokenflows.org/v1/images/generations
```

Content-Type: `application/json`

#### 常用参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | `gpt-image-2.5-flare` 或 `gpt-image-2.5-sunburst` |
| `prompt` | string | 是 | 图像描述，最长 32000 字符 |
| `n` | integer | 否 | 生成数量，1–10，默认 1 |
| `size` | string | 否 | 标准尺寸 `1024x1024`（默认）、`1536x1024`（横）、`1024x1536`（竖）、`auto`；也支持自定义 `宽x高`（见下方说明） |
| `quality` | string | 否 | `auto`（默认）、`low`、`medium`、`high`；`gpt-image-2.5` 系列还支持 `xhigh`、`max` |
| `background` | string | 否 | `auto`（默认）、`opaque`、`transparent`（透明背景需搭配 `png` 或 `webp` 输出） |
| `output_format` | string | 否 | `png`（默认）、`jpeg`、`webp` |
| `output_compression` | integer | 否 | 压缩率 0–100，仅 `jpeg` / `webp` 生效，默认 100 |
| `moderation` | string | 否 | 内容审核级别：`auto`（默认）或 `low` |

关于 `size` 自定义分辨率：宽高须均为 16 的倍数，宽高比在 1:3 到 3:1 之间，最高支持 `3840x2160`（超过 `2560x1440` 为实验性支持）。

#### 示例请求

```json
{
  "model": "gpt-image-2.5-flare",
  "prompt": "一只戴贝雷帽、坐在木桌上的小水獭，柔和光线",
  "size": "1024x1024",
  "quality": "high",
  "n": 1
}
```

#### 示例响应

```json
{
  "created": 1718000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgo..."
    }
  ],
  "output_format": "png",
  "quality": "high",
  "size": "1024x1024"
}
```

`data[].b64_json` 为 Base64 编码的图片内容，需自行解码保存为文件。

## Anthropic Messages

```http
POST /v1/messages
```

完整地址：

```text
https://api.tokenflows.org/v1/messages
```

### 常用参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 模型 ID，见 [模型列表](/models) |
| `messages` | array | 是 | 消息列表 |
| `system` | string | 否 | 系统提示词 |
| `max_tokens` | integer | 是 | 最大生成 token 数 |
| `temperature` | number | 否 | 采样温度 |
| `stream` | boolean | 否 | 是否流式输出 |

### 示例请求

```json
{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "system": "你是一个 helpful assistant。",
  "messages": [
    {"role": "user", "content": "介绍一下 TokenFlows"}
  ],
  "temperature": 0.7
}
```

### 示例响应

```json
{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-6",
  "content": [
    {
      "type": "text",
      "text": "TokenFlows 是一个面向开发者和 AI Agent 的模型网关。"
    }
  ],
  "usage": {
    "input_tokens": 20,
    "output_tokens": 100
  }
}
```

## 模型列表

```http
GET /v1/models
```

完整地址：

```text
https://api.tokenflows.org/v1/models
```

返回当前可用模型及元数据。站内可视化列表见 [模型列表](/models)。

## 错误码

| 状态码 | 说明 | 建议 |
| --- | --- | --- |
| 400 | 请求参数错误 | 检查 JSON 格式、模型 ID 和必填参数 |
| 401 | API Key 无效、缺失或账号状态异常 | 检查密钥、余额、套餐和到期状态 |
| 413 | 请求或上下文过大 | 新建会话，减少一次性输入内容 |
| 429 | 请求频率超限 | 稍等后重试，降低并发或请求频率 |
| 500 | 服务器内部错误 | 稍后重试；持续出现请联系支持 |

更多排查建议见 [常见问题](/docs/faq)。