# API 参考

> 4 个 chat 协议端点 + GET /v1/models / 余额与计费端点的请求 / 响应 schema 与 curl 示例,以及媒体 / 数字人 / 知识库端点索引

来源：https://model.dflop.top/docs/reference/api-reference

本平台的全部对外端点都接受同一把 `sk-gpushare-*` API Key。本页详解 4 个 chat 协议端点、`GET /v1/models` 与两组余额端点;媒体(图像 / 视频 / 音乐 / 语音)、数字人与知识库端点在各自页面展开。

| 端点 | 协议 / 用途 | 详情 |
|---|---|---|
| [`POST /v1/chat/completions`](#post-v1-chat-completions) | OpenAI Chat —— 通用最广,跨厂商 | 本页 |
| [`POST /v1/messages`](#post-v1-messages) | Anthropic Messages —— Anthropic SDK 直连 | 本页 |
| [`POST /v1beta/models/{model}:generateContent`](#gemini-native) | Gemini Native —— Google `genai` SDK 直连 | 本页 |
| [`POST /v1/responses`](#post-v1-responses) | OpenAI Responses —— GPT-5.x 原生协议 + 内置工具 | 本页 |
| [`GET /v1/models`](#get-v1-models) | OpenAI 模型发现(SDK / 第三方客户端自动调用) | 本页 |
| [`GET /v1/key/balance`](#get-v1-key-balance) | 查询本 Key 的余额 / 已用 / 总额度 | 本页 |
| [`GET /v1/dashboard/billing/*`](#get-v1-dashboard-billing) | OpenAI 官方计费端点 —— 第三方客户端「查余额」自动调用 | 本页 |
| `POST /v1/images/generations` | 文生图 / 图生图(同步,或 `"async": true` 转任务),**按张计费** | [图像 / 视频 / 音乐 API](./media-apis.md) |
| `POST /v1/videos/generations`(+ `GET .../{id}` 轮询 / `GET` 列表) | 文生视频 / 图生视频(异步任务),**按秒计费** | [图像 / 视频 / 音乐 API](./media-apis.md) |
| `POST /v1/music/generations`(+ `GET .../{id}` 轮询) | AI 音乐生成(异步任务),**按次计费** | [图像 / 视频 / 音乐 API](./media-apis.md) |
| `POST /v1/audio/speech` / `/v1/audio/voices` | 语音合成(按字符)/ 声音克隆(按次) | [图像 / 视频 / 音乐 API](./media-apis.md#post-v1audiospeech) |
| `POST /v1/videos/avatars` + `GET /v1/videos/clip-templates` | 数字人形象库 / 智能剪辑模板 | [数字人 / 智能剪辑 API](./digital-human-apis.md) |
| `POST /v1/embeddings` | ⚠️ 平台已于 2026-07 下架 embedding SKU,**当前无可用模型**(调用返回 404 `model_not_found`) | — |
| `POST /v1/transcripts/extract` | 短视频链接 → 口播文案(同步),**按次计费** | [图像 / 视频 / 音乐 API](./media-apis.md) |
| `/api/v1/ext/wiki/*`(8 条只读 REST)+ `/mcp`(MCP server) | 知识库检索 | [知识库 API & MCP](./wiki-api.md) |

Base URL: `https://api.dflop.top`

## 鉴权

详见 [鉴权](./authentication.md)。四种方式任选一种,按以下优先级回退:

1. `x-api-key: sk-gpushare-xxx` header (推荐)
2. `x-goog-api-key: sk-gpushare-xxx` header (Google `genai` SDK 默认 —— Gemini SDK 用户无需任何改造)
3. `?key=sk-gpushare-xxx` query
4. `Authorization: Bearer sk-gpushare-xxx` header (OpenAI / Anthropic SDK 默认)

> **例外**: [`GET /v1/models`](#get-v1-models) 只认 `Authorization: Bearer` 和 `x-api-key` 两种 header,**不支持 `?key=` query**。

---

## POST /v1/chat/completions

OpenAI Chat Completions 兼容端点。**最通用**,支持全部 chat 类模型(101 个),完整列表见 [模型列表](./models.md) 或 [`GET /v1/models`](#get-v1-models)。

> 图像 / 视频专属 SKU(Seedream / Seedance 等)不走本端点(调用返 503 `no_channel_available`),请走各自端点 —— 见 [图像 / 视频 API](./media-apis.md)。

### 请求

```json
{
  "model": "claude-sonnet-4-6",
  "messages": [
    {"role": "system", "content": "You are helpful."},
    {"role": "user", "content": "Hello"}
  ],
  "stream": false,
  "max_tokens": 1024,
  "temperature": 0.7,
  "tools": [
    {"type": "function", "function": {...}}
  ]
}
```

| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| `model` | ✓ | string | 模型 ID,见 [模型列表](./models.md) |
| `messages` | ✓ | array | 对话历史,role ∈ {system, user, assistant, tool} |
| `stream` | | bool | `true` 启用 SSE 流式 |
| `max_tokens` | | int | 生成 token 上限 |
| `temperature` | | float | 0-2 |
| `tools` | | array | Function tools 或内置工具 `{type:"web_search"}` / `{type:"image_generation"}`(约束见下) |
| `tool_choice` | | string\|object | `auto` / `none` / `{type:"function","function":{...}}` |
| `stream_options` | | object | 流式时 `{"include_usage": true}` 让 trailing chunk 带 token 统计 |
| `response_format` | | object | `{"type":"json_object"}` 强制 JSON 输出 |

> **内置工具约束**(`{type:"web_search"}` / `{type:"image_generation"}`):
> - 这两个内置工具在本端点走 WebSocket V2 适配器,**必须 `stream: true`** —— 非流式直接 400 `invalid_request`(message: ``Tools `web_search` and `image_generation` require `stream: true` ``)
> - `image_generation` **仅 GPT-5.x**(X1 渠道)支持,其他模型返 400 `tool_not_supported`
> - `web_search` 按模型 / 渠道支持情况门控,不支持的组合返 400 `tool_not_supported`。各模型支持矩阵见 [模型列表](./models.md)
>
> Function tools(`{type:"function",...}`)不受以上约束,流式 / 非流式均可。

### 响应 (非流式)

```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1715845200,
  "model": "claude-sonnet-4-6",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Hello!"},
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 5,
    "total_tokens": 15
  }
}
```

### 响应 (流式)

`stream: true` 时返回 SSE 流,每条 `data:` 行为一个 chunk。详见 [流式响应](../guides/streaming.md)。

### curl

```bash
curl https://api.dflop.top/v1/chat/completions \
  -H "Authorization: Bearer $PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

---

## POST /v1/messages

Anthropic Messages 兼容端点。

### 请求

```json
{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "system": "You are helpful.",
  "messages": [
    {"role": "user", "content": "Hello"}
  ],
  "stream": false,
  "tools": [...]
}
```

| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| `model` | ✓ | string | 模型 ID |
| `max_tokens` | ✓ | int | Anthropic 协议必填 (跟 OpenAI 不同) |
| `messages` | ✓ | array | 对话,role ∈ {user, assistant} |
| `system` | | string | 系统提示 (顶层字段,不放 messages) |
| `stream` | | bool | |
| `tools` | | array | Anthropic 工具格式 (`name` / `description` / `input_schema`) |
| `tool_choice` | | object | `{"type":"auto"\|"any"\|"tool", "name": "..."}` |

### 响应 (非流式)

```json
{
  "id": "msg_...",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-6",
  "content": [
    {"type": "text", "text": "Hello!"}
  ],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 10, "output_tokens": 5}
}
```

### curl

```bash
curl https://api.dflop.top/v1/messages \
  -H "x-api-key: $PLATFORM_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

### 限制

- 主流 `gemini-2.5` / `gemini-3.x` SKU 建议走 [Gemini Native 端点](#gemini-native);部分 `gemini-*` SKU 也接入了本端点。模型 × 端点的精确支持矩阵见 [兼容矩阵](./compatibility-matrix.md)
- 模型存在但本端点没有可用渠道时返 503 `no_channel_available`
- `anthropic-version` header SDK 自动注入;curl 直调时填 `2023-06-01`

---

## Gemini Native

两条相关端点:

- `POST /v1beta/models/{model}:generateContent` —— 非流式
- `POST /v1beta/models/{model}:streamGenerateContent` —— 流式

`{model}` 占位符在 URL 里直接写,如 `/v1beta/models/gemini-2.5-pro:generateContent`。

### 请求

```json
{
  "contents": [
    {"role": "user", "parts": [{"text": "Hello"}]}
  ],
  "systemInstruction": {
    "parts": [{"text": "You are helpful."}]
  },
  "generationConfig": {
    "maxOutputTokens": 1024,
    "temperature": 0.7
  },
  "tools": [...]
}
```

### 响应

```json
{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [{"text": "Hello!"}]
    },
    "finishReason": "STOP",
    "index": 0
  }],
  "usageMetadata": {
    "promptTokenCount": 10,
    "candidatesTokenCount": 5,
    "totalTokenCount": 15
  }
}
```

### curl

```bash
curl "https://api.dflop.top/v1beta/models/gemini-2.5-pro:generateContent?key=$PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Hello"}]}]
  }'
```

### 限制

- GPT-5.x 暂不支持该端点(模型存在但无渠道时返 503 `no_channel_available`),精确矩阵见 [兼容矩阵](./compatibility-matrix.md)

---

## POST /v1/responses

OpenAI Responses API 兼容端点 —— GPT-5.x 系列的**原生协议**。比 `/v1/chat/completions` 多两条原生工具:**web_search**(联网检索)和 **image_generation**(GPT-image-2 出图),响应里有完整 `reasoning` / `output_text` / 工具调用结构化字段。

### 支持的模型

GPT-5 家族(原生)+ X1 渠道 Claude SKU,精确矩阵见 [兼容矩阵](./compatibility-matrix.md):

| 模型 | 备注 |
|---|---|
| `gpt-5.5` | |
| `gpt-5.5` | 推荐 —— 支持 reasoning summary + 内置工具 |
| `claude-opus-4-6` / `claude-opus-4-7` / `claude-opus-4-8` | X1 |
| `claude-sonnet-4-6` | X1 |
| `claude-haiku-4-5-20251001` | X1 |

调用其他模型时的错误语义:

- model id 不在模型列表 → 400 `model_not_found`
- 模型存在但本端点没有可用渠道 → 503 `no_channel_available`(改调 `/v1/chat/completions` 或该模型的 native 端点)
- `model_not_allowed` **仅**在你的 Key 配置了 `allowed_models` 白名单且不含该模型时出现

### 请求

```json
{
  "model": "gpt-5.5",
  "instructions": "You are concise.",
  "input": [
    {"role": "user", "content": "Say hello in 5 words."}
  ],
  "stream": false,
  "max_output_tokens": 1024,
  "temperature": 1.0,
  "top_p": 0.98,
  "reasoning": {"effort": "medium"},
  "tools": [
    {"type": "web_search"},
    {"type": "image_generation", "size": "1024x1024"},
    {"type": "function", "name": "get_weather", "description": "...", "parameters": {...}}
  ],
  "tool_choice": "auto",
  "parallel_tool_calls": true
}
```

| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| `model` | ✓ | string | 见 [支持的模型](#支持的模型) |
| `input` | ✓ | array \| string | **建议始终用消息数组**(见下)。GPT-5.x 的上游硬性要求 `input` 为数组,字符串形式会被上游拒绝 |
| `instructions` | | string | 系统提示。**顶层字段,不是 messages[0]**(跟 `/v1/chat/completions` 不同)。GPT-5.x 上游要求该字段存在,建议始终提供 |
| `stream` | | bool | `true` 返回 SSE 事件流 |
| `max_output_tokens` | | int | 生成上限(Responses API 用 `_output_`,不是 `max_tokens`) |
| `reasoning` | | object | `{"effort": "low"\|"medium"\|"high"}` 控制内部思考强度 |
| `temperature` / `top_p` / `frequency_penalty` / `presence_penalty` | | float | 标准采样参数 |
| `tools` | | array | 见 [工具类型](#工具-tools) |
| `tool_choice` | | string \| object | `auto` / `none` / `{type:"function","name":"..."}` |
| `parallel_tool_calls` | | bool | 默认 true |

#### `input` 数组形式 (多轮)

```json
"input": [
  {"role": "user", "content": "What is 2+2?"},
  {"role": "assistant", "content": "4"},
  {"role": "user", "content": "What was my first question?"}
]
```

数组元素的 `content` 可用 string 简写;**vision** 必须用 content parts:

```json
{"role": "user", "content": [
  {"type": "input_text", "text": "Describe this image."},
  {"type": "input_image", "image_url": "https://...", "detail": "auto"}
]}
```

> **注意**: `input_image.image_url` 必须是公网可访问的 URL(上游会自己拉),CDN 缩略图 / 鉴权 URL 可能返 `upstream_error`。

#### 工具 (tools)

```json
// 1. 内置 web 检索 —— 模型自行决定是否调用,直接返回带答案的 output_text
{"type": "web_search"}

// 2. 内置出图 —— output 里返回 image_generation_call 项 (含 base64 result)
{"type": "image_generation", "size": "1024x1024"}

// 3. 用户自定义 function —— output 里返回 function_call 项,你执行后回带 function_call_output
{
  "type": "function",
  "name": "get_weather",
  "description": "Get current weather",
  "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}
}
```

### 响应 (非流式)

```json
{
  "id": "resp_0a430185e6bd1abb016a1576c7bbb08198be6868b655d19349",
  "object": "response",
  "created_at": 1779791559,
  "status": "completed",
  "model": "gpt-5.5",
  "instructions": "...",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{"type": "output_text", "text": "Hello, hope you are well."}]
    }
  ],
  "reasoning": {"context": "current_turn", "effort": "medium", "summary": null},
  "usage": {
    "input_tokens": 25,
    "input_tokens_details": {"cached_tokens": 0},
    "output_tokens": 51,
    "output_tokens_details": {"reasoning_tokens": 38},
    "total_tokens": 76
  }
}
```

`output[]` 数组按出现顺序排列,每项 `type` 之一:

| `type` | 含义 |
|---|---|
| `message` | 助手文本回复,文本在 `content[].text` |
| `reasoning` | 内部推理 summary(可能为空) |
| `function_call` | 模型决定调用你的 function,字段 `call_id` / `name` / `arguments`(JSON 字符串) |
| `image_generation_call` | 内置 image_generation 工具执行结果,`result` 是 base64 PNG |

### 响应 (流式)

`stream: true` 时返回 SSE,事件名带 `response.` 前缀。关键事件序列:

```
event: response.created            // 整体 response 框架(usage=null)
event: response.in_progress
event: response.output_item.added  // 第 N 个 output 项开始
event: response.output_text.delta  // 文本增量,delta 字段是 chunk
event: response.output_text.done   // 第 N 项文本完成
event: response.output_item.done   // 第 N 项整体结束
event: response.completed          // 全部完成,usage 已填充
```

每个 `data:` 都是单条 JSON 对象,自带 `sequence_number` 单调递增。详见 [流式响应](../guides/streaming.md)。

### curl

```bash
# 基础调用
curl https://api.dflop.top/v1/responses \
  -H "Authorization: Bearer $PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "instructions": "You are helpful.",
    "input": [{"role": "user", "content": "Hello"}],
    "max_output_tokens": 100
  }'

# 联网检索
curl https://api.dflop.top/v1/responses \
  -H "Authorization: Bearer $PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "instructions": "You are helpful.",
    "input": [{"role": "user", "content": "What is today date in Shanghai?"}],
    "tools": [{"type": "web_search"}]
  }'

# 流式
curl -N https://api.dflop.top/v1/responses \
  -H "Authorization: Bearer $PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "instructions": "You are helpful.",
    "input": [{"role": "user", "content": "Count 1 to 3."}],
    "stream": true
  }'
```

### 限制

- **多轮对话只能用 `input` 数组自行维护历史**。上游不持久化会话 item(`store: false` 语义),`previous_response_id` 不可用 —— 请每轮都把完整历史放进 `input` 数组
- **模型范围见 [支持的模型](#支持的模型)**。其他模型改调 `/v1/chat/completions` 或各自的 native 端点(错误语义见上)
- **vision 受上游 URL 拉取限制** —— 部分 CDN 缩略图 / 鉴权 / 防盗链 URL 会失败。建议先把图传到自己的 R2 / S3 公开桶再传 URL
- **`image_generation` 工具不强制流式** —— 本端点是 HTTP 透传,`stream:false` 也能在响应的 `output[]` 里拿到 `image_generation_call.result` (base64 PNG)。这跟 `/v1/chat/completions` 不同:那条端点的 `image_generation` 走专用 WebSocket 流式适配器,会强制 `stream:true` 并把图塞进 `delta.content` 的 markdown 里

---

## GET /v1/models

OpenAI 兼容的模型发现端点。OpenAI SDK 的 `client.models.list()` 与多数第三方客户端(Open WebUI / Cline / Continue 等)的自动模型发现调的就是它。

### 鉴权差异

本端点只接受两种 **header** 鉴权,**不支持 `?key=` query**(与其他端点的四级回退不同,Gemini 风格的 query 调用会 401):

- `Authorization: Bearer sk-gpushare-xxx`
- `x-api-key: sk-gpushare-xxx`

### 响应

```json
{
  "object": "list",
  "data": [
    {"id": "claude-sonnet-4-6", "object": "model", "created": 0, "owned_by": "anthropic"},
    {"id": "gpt-5.5", "object": "model", "created": 0, "owned_by": "openai"}
  ]
}
```

- 返回 pricing 注册表全部条目,**含图像 / 视频 / embedding 专属 SKU 与暂不可调用的占位 SKU** —— 做模型菜单或脚本接入时建议按需过滤
- 如果你的 Key 配置了 `allowed_models` 白名单,只返回白名单内的条目
- 另有**免鉴权**的 `GET /api/v1/models/public`,返回带价格 / 能力字段(含 `callable` 标志与 `endpoint_type`)的完整注册表,适合做比价 / 筛选

### curl

```bash
curl https://api.dflop.top/v1/models \
  -H "Authorization: Bearer $PLATFORM_API_KEY"
```

---

## GET /v1/key/balance

查询本 Key 对应账户的余额。免费,无速率计费。

**余额为 0 时它照样正常返回**(其它计费端点在这种情况下会 402;`GET /v1/models` 同样不校验余额)—— 这正是它存在的意义:用来在扣光之前主动监控。

```bash
curl https://api.dflop.top/v1/key/balance \
  -H "Authorization: Bearer $PLATFORM_API_KEY"
```

```json
{
  "object": "key.balance",
  "remaining_usd": "12.3456",
  "used_usd": "7.6544",
  "total_usd": "20.0000",
  "expires_at": null
}
```

| 字段 | 含义 |
|---|---|
| `remaining_usd` | **这把 Key 现在实际还能花多少**(下限 0):账户余额与该 Key 消费上限剩余额度取小 |
| `used_usd` | **这把 Key 的累计消费**。设了消费上限的 Key 取上限计数器,未设上限的按本 Key 的调用日志累计 —— 始终只统计这一把,不会回显账户或企业老板池的总消费 |
| `total_usd` | `remaining_usd + used_usd`。预付费钱包没有「授予额度」这个概念,这是为下面的计费端点合成出来的分母 |
| `expires_at` | Key 过期时间,`null` = 永不过期 |

余额本身由账户下**所有 Key 共享**,不是每把 Key 独立的额度。

> ⚠️ **这把 Key 没设消费上限时,`remaining_usd` 就是背后钱包的余额本身** —— 企业签发的 Key 即为老板池余额。只有设了消费上限的 Key,回显的才是「这把 Key 的剩余额度」而非整池。**不希望持有方看到整池余额,就给这把 Key 设一个消费上限**(见 [Key 消费上限](https://model.dflop.top/dashboard/keys))。

金额是 JSON **字符串**(避免浮点精度损失),客户端请 `parseFloat` 后使用。

鉴权与其它端点一致(四种方式任选)。该端点不更新 Key 的「最近使用时间」——定期轮询它不会被当成流量。`used_usd` 有最多 60 秒的缓存延迟,`remaining_usd` 永远是实时值。

---

## GET /v1/dashboard/billing

```text
GET /v1/dashboard/billing/subscription
GET /v1/dashboard/billing/usage
```

上面的 `/v1/key/balance` 是本平台自己的端点名,第三方客户端不认识它。这两条是 **OpenAI 官方的计费端点**:New API / One API 这类中转平台点「更新余额」就是调它们,填好 Key 即可显示,**不需要任何额外配置**。许多桌面客户端(Cherry Studio、ChatBox、NextChat、LobeChat 等)的「查看余额」也走同一对端点,但具体以你使用的客户端版本为准。

> 未实现 `GET /v1/dashboard/billing/credit_grants`(OpenAI 的另一条旧计费端点),仍在调它的老客户端会拿到 404 —— 用上面两条。

两条路径同时挂在**带和不带 `/v1` 前缀**两个位置(不同客户端拼 URL 的习惯不一样),返回完全一致。

```bash
curl https://api.dflop.top/v1/dashboard/billing/subscription \
  -H "Authorization: Bearer $PLATFORM_API_KEY"
```

```json
{
  "object": "billing_subscription",
  "has_payment_method": true,
  "soft_limit_usd": 20.0,
  "hard_limit_usd": 20.0,
  "system_hard_limit_usd": 20.0,
  "access_until": 0
}
```

```bash
curl "https://api.dflop.top/v1/dashboard/billing/usage?start_date=2026-07-01&end_date=2026-08-01" \
  -H "Authorization: Bearer $PLATFORM_API_KEY"
```

```json
{
  "object": "list",
  "total_usage": 765.44,
  "daily_costs": []
}
```

- 与 `/v1/key/balance` 的对应关系:`hard_limit_usd` = `total_usd`,`total_usage` = `used_usd` **× 100**(`total_usage` 的单位是**美分**,这是 OpenAI 的原始口径)。客户端按 `hard_limit_usd - total_usage / 100` 算出的余额,恒等于 `remaining_usd`。
- 这两条端点的金额是 **JSON 数字**(不是字符串)—— 官方 schema 如此,客户端按浮点解析。
- `access_until` 是 Key 过期时间的 Unix 秒,永不过期时为 `0`。
- `start_date` / `end_date` **接受但忽略**,`total_usage` 一律返回累计值。原因:`subscription` 端点收不到时间窗参数,如果 `usage` 按窗口返回,客户端那道减法就会算出错误的余额。New API / One API 官方实现同样忽略这两个参数。
- `daily_costs` 恒为空数组。要按天 / 按模型的明细请用控制台的用量页面。
- 与 `/v1/key/balance` 一样:余额为 0 时照常 200 返回,不计费、不限流、不更新「最近使用时间」。

> 第三方客户端 / 中转平台的具体配置步骤见 [New API / 第三方客户端接入](../integrations/new-api.md)。

---

## 错误响应

所有端点返回 HTTP 4xx/5xx 时,响应体为**本协议官方错误 schema** —— 不混用:

### OpenAI 形状 (`/v1/chat/completions`、`/v1/responses`、`/v1/embeddings`)
```json
{"error": {"message": "...", "type": "...", "code": "..."}}
```

### Anthropic Messages (`/v1/messages`)
```json
{"type": "error", "error": {"type": "...", "message": "..."}}
```

### Gemini Native (`/v1beta/...`)
```json
{"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}}
```

> **流式中的错误**: 流式请求开流后(HTTP 200 已发出)再发生的上游错误**无法更改状态码** —— 表现为流提前终止或 SSE 错误帧,客户端需对"流未正常收尾"做兜底。详见 [错误码](./errors.md)。

最高频错误是余额耗尽:**HTTP 402**,OpenAI 形状 `code: "quota_exceeded"` / `type: "insufficient_quota"`(Anthropic 形状 `type: "billing_error"`,Gemini 形状 `status: "RESOURCE_EXHAUSTED"`)。完整错误码真值表见 [错误码](./errors.md)。

## 限制与超时

### 速率限制

平台按**账户**设两个上限(账户名下所有 API Key 共享,不是每把 Key 各一份):

| 维度 | 含义 |
|---|---|
| 每分钟请求数 | 最近 60 秒内的请求数(滑动窗口) |
| 最大并发 | 同一时刻在飞(未返回完)的请求数 |

**默认不限**;需要时由平台按账户配置,也可以给单个账户单独放开或收紧。**全部 `/v1/*` 请求都计入**,包括异步任务(视频 / 音乐 / 数字人)的状态轮询 —— 重度轮询的集成请把轮询间隔放宽,或联系我们调高上限。

触发时返回 **429** `rate_limit_exceeded`,并带这些头:

| 响应头 | 含义 |
|---|---|
| `Retry-After` | 建议等待秒数(直接照做即可) |
| `x-ratelimit-limit-requests` / `-remaining-requests` / `-reset-requests` | 每分钟请求数的上限 / 剩余 / 重置秒数 |
| `x-ratelimit-limit-concurrency` / `-remaining-concurrency` | 并发上限 / 剩余 |

限额存在时,**成功响应**同样带 `x-ratelimit-*` 头,客户端可据此自适应节流。当前账户的上限在 [model.dflop.top/dashboard/keys](https://model.dflop.top/dashboard/keys) 页面可以自查(未设上限的账户不显示该区块)。

> `429` 也可能来自上游限流透传(与平台限额无关)。区分方法:带 `x-ratelimit-*` 头的是平台限额,不带的是上游透传 —— 两者都按指数退避重试即可。

### 计费与余额

按**账户统一余额**(美元钱包)扣费,所有 API Key 共享同一余额 —— Key 本身没有独立预算池,余额耗尽时所有 Key 同时返 402(「新建 Key」不能解决额度问题)。注册即送 121.32 体验额度;充值入口在主站 dflop.top/dashboard/billing(与 model.dflop.top 同账号)。详见 [鉴权](./authentication.md)。

### 超时

| 端点 | 上游超时 |
|---|---|
| chat 四协议端点(`/v1/chat/completions`、`/v1/messages`、`/v1/responses`、`/v1beta/...`) | **180s 总时长**(流式同样受 180s 总上限约束 —— 流式只是更早拿到首 token,不是不限时) |
| `POST /v1/images/generations` | 单跳 240s / 渠道阶梯合计 280s(客户端建议 ≥300s;超 90s 的同步轮走保活,失败会以 `200` + error 体返回 —— 需要真实状态码请用 `"async": true`) |
| `POST /v1/videos/generations` | 60s(仅提交;生成是异步的,不占请求时长) |
| `POST /v1/embeddings` | 30s |
| `POST /v1/transcripts/extract` | ~55s(同步阻塞:内部创建任务 + 轮询上游至完成) |

建议客户端 SDK timeout 设 **≥ 200 秒**(长 reasoning turn / 工具调用 turn 可达数分钟,优先用流式);超长任务(视频)走异步轮询,见 [图像 / 视频 / 音乐 API](./media-apis.md)。

### 自动 failover 与重试

上游 5xx / 连接失败时 gateway 自动换渠道重试,单个请求最多尝试 3 个渠道(同一请求偶尔耗时翻倍即此原因)。客户端收到 502 `upstream_unreachable` / 504 `upstream_timeout` 时可安全重试。