315 lines
15 KiB
Markdown
315 lines
15 KiB
Markdown
# API 接口格式参考
|
||
|
||
本文档是 CLAUDE.md 中 API 接口规范的详细参考资料，包含完整的 JSON 示例、响应格式、错误类型映射等。开发时按需查阅。
|
||
|
||
## 统一响应格式详细示例
|
||
|
||
**适用范围**：`/api/admin/*`、`/api/tenant/*`、`/api/payment/*`、`/api/open/*`、`/api/status`。
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `code` | int | `0` = 成功，非 `0` = 错误。标准 HTTP 错误直接用状态码（400/401/403/404/409/500），业务错误用 >= 10000 的自定义码 |
|
||
| `message` | string | 用户可读的中文提示。成功时固定 `"ok"`，错误时描述具体原因，禁止暴露技术细节 |
|
||
| `data` | any | 成功时为业务数据（对象/数组/字符串），错误时为 `null` |
|
||
| `request_id` | string | 每个请求的唯一标识，贯穿全链路，用于日志追踪 |
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
// 成功（HTTP 200）
|
||
{"code": 0, "message": "ok", "data": {"id": 1, "name": "张三"}, "request_id": "req_abc123"}
|
||
|
||
// 参数错误（HTTP 400）
|
||
{"code": 400, "message": "用户名不能为空", "data": null, "request_id": "req_def456"}
|
||
|
||
// 业务错误（HTTP 422）
|
||
{"code": 10001, "message": "余额不足", "data": null, "request_id": "req_ghi789"}
|
||
```
|
||
|
||
### data 字段格式规范
|
||
|
||
| 接口类型 | data 结构 | 示例 |
|
||
|----------|----------|------|
|
||
| 分页列表 | `{list, total, page, page_size}` | `{"list": [...], "total": 100, "page": 1, "page_size": 20}` |
|
||
| 不分页列表 | `{list}` | `{"list": [...]}` |
|
||
| 创建资源 | `{id}` | `{"id": 42}` |
|
||
| 资源详情 | 直接返回对象 | `{"id": 1, "name": "张三", ...}` |
|
||
| 更新/删除 | `null` | `null` |
|
||
|
||
**规则**：
|
||
- 列表数据的数组字段名统一用 `list`，禁止使用 `data`、`items`、`records` 等其他名称
|
||
- 分页列表必须返回 `total`（总条数）和 `page`（当前页码），可选返回 `page_size`
|
||
- 创建操作只返回新资源的 `id`，不返回完整对象
|
||
- 更新/删除操作返回 `null`，前端通过 HTTP 200 + `code: 0` 判断成功
|
||
- 如果 list 内部可以为空，但是不能有 null 出现
|
||
|
||
### HTTP 状态码映射规则
|
||
|
||
| 业务场景 | HTTP 状态码 | code 值 | 说明 |
|
||
|----------|------------|---------|------|
|
||
| 成功 | 200 | `0` | 请求处理成功 |
|
||
| 参数校验失败 | 400 | `400` | 请求体格式错误、必填字段缺失、值不合法 |
|
||
| 未认证 | 401 | `401` | Token 缺失、过期、无效 |
|
||
| 无权限 | 403 | `403` | 已认证但无权访问该资源 |
|
||
| 资源不存在 | 404 | `404` | 查询的对象不存在 |
|
||
| 请求频率超限 | 429 | `429` | 触发限流 |
|
||
| 业务规则错误 | 422 | `>= 10000` | 业务逻辑不满足，使用自定义错误码（见 `consts.go`） |
|
||
| 服务器内部错误 | 500 | `500` | 未预期的异常 |
|
||
|
||
### 业务错误码定义（>= 10000）
|
||
|
||
业务错误码定义在 `internal/consts/consts.go` 中，每个错误码有对应的中文消息常量。新增业务错误时必须同时在 `consts.go` 中添加 `Code` 和 `Msg` 常量。
|
||
|
||
| 错误码 | 常量名 | 默认消息 |
|
||
|--------|--------|---------|
|
||
| 10001 | `CodeInsufficientBalance` | 余额不足 |
|
||
| 10002 | `CodeQuotaExceeded` | 额度已用完 |
|
||
| 10003 | `CodeChannelUnavailable` | 没有可用的渠道 |
|
||
| ... | 更多见 `consts.go` | ... |
|
||
|
||
## 大模型代理接口格式（`/v1/*`、`/v1beta/*`、`/v2/*`、`/suno/*`）
|
||
|
||
### 已注册的代理端点
|
||
|
||
| 方法 | 路径 | 功能 | 请求格式 | 流式支持 |
|
||
|------|------|------|---------|---------|
|
||
| POST | `/v1/chat/completions` | Chat Completions | OpenAI | SSE |
|
||
| POST | `/v1/completions` | Text Completions | OpenAI | SSE |
|
||
| POST | `/v1/embeddings` | 文本向量 | OpenAI | 否 |
|
||
| POST | `/v1/images/generations` | 图像生成 | OpenAI | 否 |
|
||
| POST | `/v1/images/edits` | 图像编辑 | OpenAI | 否 |
|
||
| POST | `/v1/messages` | Claude Messages | Claude | SSE |
|
||
| POST | `/v1/responses` | OpenAI Responses | OpenAI | SSE |
|
||
| POST | `/v1/audio/speech` | 语音合成 | OpenAI | 否 |
|
||
| POST | `/v1/audio/transcriptions` | 语音转文字 | OpenAI | 否 |
|
||
| POST | `/v1/audio/translations` | 语音翻译 | OpenAI | 否 |
|
||
| POST | `/v1/rerank` | 重排序 | OpenAI | 否 |
|
||
| POST | `/v1/moderations` | 内容审核 | OpenAI | 否 |
|
||
| GET | `/v1/models` | 模型列表 | — | 否 |
|
||
| GET | `/v1/models/{model_id}` | 模型详情 | — | 否 |
|
||
| GET | `/v1/realtime` | 实时对话（WebSocket） | OpenAI | WebSocket |
|
||
| POST | `/v1/video/generations` | 视频生成（异步任务） | 自定义 | 否 |
|
||
| GET | `/v1/video/generations/{task_id}` | 视频生成任务查询 | — | 否 |
|
||
| POST | `/v1/videos` | OpenAI Videos 视频生成（multipart/JSON） | OpenAI | 否 |
|
||
| GET | `/v1/videos/{video_id}` | OpenAI Videos 任务查询 | — | 否 |
|
||
| GET | `/v1/videos/{video_id}/content` | OpenAI Videos 成品下载 | — | 否 |
|
||
| DELETE | `/v1/videos/{video_id}` | OpenAI Videos 任务删除（终态软删） | — | 否 |
|
||
| GET | `/v1beta/models` | Gemini 模型列表 | Gemini | 否 |
|
||
| GET | `/v1beta/models/{model}` | Gemini 模型详情 | Gemini | 否 |
|
||
| POST | `/v1beta/models/{model}` | Gemini 内容生成 | Gemini | SSE |
|
||
| POST | `/suno/submit/{action}` | Suno 音乐生成提交 | 自定义 | 否 |
|
||
| POST | `/suno/fetch` | Suno 批量查询 | 自定义 | 否 |
|
||
| GET | `/suno/fetch/{task_id}` | Suno 任务查询 | — | 否 |
|
||
| POST | `/v2/video_generation` | MiniMax H3 视频生成（官方协议 v2） | MiniMax | 否 |
|
||
| GET | `/v2/query/video_generation/{task_id}` | MiniMax H3 任务查询（v2） | — | 否 |
|
||
| DELETE | `/v2/video_generation/{task_id}` | MiniMax H3 任务取消（仅排队中，v2） | — | 否 |
|
||
| POST | `/v1/video_generation` | MiniMax Hailuo 视频生成（官方协议 v1，四形态共用） | MiniMax | 否 |
|
||
| GET | `/v1/query/video_generation?task_id=` | MiniMax Hailuo 任务查询（v1，query 参数） | — | 否 |
|
||
|
||
### MiniMax 官方视频协议（`/v2/*`，MiniMax-H3/H3-Max）
|
||
|
||
对 MiniMax v2 视频协议的原生接入：官方 SDK 把 base_url 指向网关即可直连。协议规格见 `docs/modeldocs/minimax/video/`。
|
||
|
||
**提交** `POST /v2/video_generation`（Bearer 平台 API Key）：
|
||
|
||
```json
|
||
{
|
||
"model": "MiniMax-H3",
|
||
"content": [{ "type": "text", "text": "海浪拍打礁石，慢镜头。" }],
|
||
"resolution": "768P",
|
||
"duration": 6,
|
||
"ratio": "16:9"
|
||
}
|
||
```
|
||
|
||
- `model` / `content`（含非空 text 项）/ `resolution` / `duration` 四项必填；`ratio` 文生视频时必填（不能为 `adaptive`）
|
||
- `callback_url` **会被剥离**：网关按自身任务体系轮询计费，上游回调携带的上游 task_id 与网关公开 ID 不互通
|
||
- 提交响应为官方形态：`{"task_id": "task_xxx"}`（网关公开任务 ID，非上游 ID）
|
||
|
||
**查询** `GET /v2/query/video_generation/{task_id}` → `{"task": {官方 VideoTask}}`：
|
||
状态机 `queued/running/succeeded/failed`（上游取消的任务回放为 `failed`）。`content.url` 为上游限时直链；
|
||
`usage/resolution/duration/ratio` 从最近一次上游查询响应回放，任务提交后首拍轮询前（≤15s）可能缺失。
|
||
|
||
**取消** `DELETE /v2/video_generation/{task_id}`：仅支持取消**排队中**（queued）的任务，取消结果以远程返回为准——
|
||
网关调用上游 DELETE，上游确认 `action=cancelled` 才向客户端返回成功
|
||
（`{"task_id": "...", "action": "cancelled", "status": "cancelled"}`）；上游拒绝时（如任务已进入 running）
|
||
原样透传上游错误。**不支持删除任务记录**（终态任务不可删，软删也不做，任务数据保留用于计费与审计；错误码 `task_not_cancellable`）。
|
||
取消确认后本地状态由轮询循环在下一拍（≤15s）对账收敛为 failed，预扣随之退款。
|
||
|
||
错误响应为 OpenAI 风格 OaiError（`{"error": {"type": "...", "message": "..."}}`），与官方 v2 一致。
|
||
|
||
**OpenAI 协议互通**：同一渠道下 `POST /v1/videos`（OpenAI Videos 协议）与 `POST /v1/video/generations`（通用任务体）可直接调用 MiniMax 视频模型（H3 与 Hailuo 系列按模型自动分派 v2/v1 上游协议）。`size` 只借 OpenAI 协议的字段形态、**值原样透传不换算**——请直接传目标供应商的原生分辨率词汇（H3：`768P`/`2K`/`480P`；Hailuo 2.x：`768P`/`1080P`）；非官方档位值会原样送达上游（上游 400 则任务提交失败、预扣全额退款）。时长取 `seconds`/`duration`/`metadata.duration`（缺省 6 秒），`input_reference`/`images[0]` 作为首帧图（v1 转为 `first_frame_image`），纯文生视频时 v2 ratio 默认 `16:9`。
|
||
|
||
### MiniMax 官方视频协议 v1（`/v1/video_generation`，Hailuo 系列）
|
||
|
||
Hailuo 2.x 及旧型号（T2V/I2V/S2V-01，传入即转发不拦截）走 v1 扁平字段协议：
|
||
|
||
- **提交** `POST /v1/video_generation`：文生（`prompt` 必填）/ 图生（`first_frame_image` 必填，支持 URL 或 data URI）/ 首尾帧（`last_frame_image`，仅 Hailuo-02）/ 主体参考（`subject_reference`，S2V-01）四形态共用；`duration`（默认 6，768P 支持 10）/`resolution`（Hailuo 2.x 默认 `768P`，旧型号默认 `720P`）可选；`prompt_optimizer`/`fast_pretreatment`/`aigc_watermark` 透传；`callback_url` 剥离。响应为官方 `{task_id, base_resp}` 形态（task_id 为网关公开 ID）
|
||
- **查询** `GET /v1/query/video_generation?task_id=`：官方 `{task_id, status, file_id, video_width, video_height, base_resp}` 形态，状态机 `Preparing/Queueing/Processing/Success/Fail`；**增补字段** `download_url`（网关轮询时经官方 files/retrieve 二跳解析的限时直链，官方查询响应无此字段）与 `error`（失败原因）
|
||
- **成品二跳由网关代取**：官方流程「file_id → GET /v1/files/retrieve → download_url」在轮询时链式完成，`download_url` 落任务记录并回放到查询响应；不暴露 files/retrieve 代理端点
|
||
- **取消/删除**：v1 上游无此能力，端点不提供（v2 的 DELETE 端点对 v1 任务返回 400）
|
||
- v1 无 usage 返回，计费按请求规格（per_second 矩阵 × 时长），与 v2 口径一致
|
||
|
||
### OpenAI 格式端点响应
|
||
|
||
**非流式响应**直接透传上游 JSON，典型结构：
|
||
|
||
```json
|
||
// Chat Completions 响应
|
||
{
|
||
"id": "chatcmpl-abc123",
|
||
"object": "chat.completion",
|
||
"created": 1677652288,
|
||
"model": "gpt-4o",
|
||
"choices": [
|
||
{
|
||
"index": 0,
|
||
"message": {"role": "assistant", "content": "Hello!"},
|
||
"finish_reason": "stop"
|
||
}
|
||
],
|
||
"usage": {
|
||
"prompt_tokens": 9,
|
||
"completion_tokens": 12,
|
||
"total_tokens": 21
|
||
}
|
||
}
|
||
```
|
||
|
||
```json
|
||
// Embeddings 响应
|
||
{
|
||
"object": "list",
|
||
"data": [
|
||
{"object": "embedding", "embedding": [0.1, 0.2, ...], "index": 0}
|
||
],
|
||
"model": "text-embedding-3-small",
|
||
"usage": {"prompt_tokens": 5, "total_tokens": 5}
|
||
}
|
||
```
|
||
|
||
**流式响应**使用 SSE（Server-Sent Events），`Content-Type: text/event-stream`：
|
||
|
||
```
|
||
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}
|
||
|
||
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}
|
||
|
||
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":9,"completion_tokens":12,"total_tokens":21}}
|
||
|
||
data: [DONE]
|
||
```
|
||
|
||
**OpenAI 格式错误响应**：
|
||
|
||
```json
|
||
{
|
||
"error": {
|
||
"type": "invalid_request_error",
|
||
"message": "余额不足，请联系管理员充值",
|
||
"param": null,
|
||
"code": null
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误类型映射**：
|
||
|
||
| 平台错误场景 | error.type | HTTP 状态码 |
|
||
|-------------|-----------|------------|
|
||
| 认证失败（API Key 无效） | `authentication_error` | 401 |
|
||
| 权限不足（Key 无权访问模型） | `permission_error` | 403 |
|
||
| 余额不足 / 额度耗尽 | `insufficient_quota` | 402 |
|
||
| 模型不存在 / 参数错误 | `invalid_request_error` | 400 |
|
||
| 请求频率超限 | `rate_limit_error` | 429 |
|
||
| 没有可用渠道 | `server_error` | 503 |
|
||
| 上游供应商错误 | 原样透传上游错误类型 | 上游状态码 |
|
||
| 平台内部错误 | `internal_error` | 500 |
|
||
|
||
### Claude 格式端点响应（`/messages`）
|
||
|
||
**非流式响应**：
|
||
|
||
```json
|
||
{
|
||
"id": "msg_abc123",
|
||
"type": "message",
|
||
"role": "assistant",
|
||
"content": [{"type": "text", "text": "Hello!"}],
|
||
"model": "claude-sonnet-4-20250514",
|
||
"stop_reason": "end_turn",
|
||
"usage": {
|
||
"input_tokens": 25,
|
||
"output_tokens": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
**流式响应（SSE）**：
|
||
|
||
```
|
||
event: message_start
|
||
data: {"type":"message_start","message":{"id":"msg_abc123","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-20250514","usage":{"input_tokens":25,"output_tokens":0}}}
|
||
|
||
event: content_block_delta
|
||
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello!"}}
|
||
|
||
event: message_delta
|
||
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":10}}
|
||
|
||
event: message_stop
|
||
data: {"type":"message_stop"}
|
||
```
|
||
|
||
**Claude 格式错误响应**：
|
||
|
||
```json
|
||
{
|
||
"type": "error",
|
||
"error": {
|
||
"type": "authentication_error",
|
||
"message": "余额不足，请联系管理员充值"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Gemini 格式端点响应（`/v1beta/models/*`）
|
||
|
||
使用 Google Gemini API 原生格式透传，错误格式：
|
||
|
||
```json
|
||
{
|
||
"error": {
|
||
"code": 400,
|
||
"message": "请求参数错误",
|
||
"status": "INVALID_ARGUMENT"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 错误处理实现规范
|
||
|
||
- `WriteRelayError(w, err)` — 写入 OpenAI 格式错误，用于 `/v1/chat/completions`、`/v1/embeddings` 等 OpenAI 格式端点
|
||
- `WriteClaudeRelayError(w, err)` — 写入 Claude 格式错误，用于 `/v1/messages` 端点
|
||
- 平台级错误（余额不足、渠道不可用、频率限制）转换为供应商原生格式的错误类型，消息使用中文
|
||
- 上游供应商错误原样透传，不做二次包装
|
||
- 限流错误额外设置 `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` 响应头
|
||
|
||
## 中间件配置差异
|
||
|
||
| 中间件 | 管理接口 | 代理接口 |
|
||
|--------|---------|---------|
|
||
| AdminAuth / TenantAuth（JWT） | 使用 | 不使用 |
|
||
| ApiKeyAuth（Bearer Token） | 不使用 | 使用 |
|
||
| MiddlewareHandlerResponse（统一响应） | 使用 | 不使用 |
|
||
| ErrorHandler | 使用（支付回调） | 不使用 |
|
||
| MaintenanceMode（维护模式） | 使用（租户） | 使用 |
|
||
| ContentFilter（内容过滤） | 不使用 | 使用 |
|
||
| OperationLog（操作日志） | 使用（管理后台） | 不使用 |
|
||
| OpenPlatformAuth（HMAC-SHA256） | 仅开放平台 | 不使用 |
|
||
| RBAC（权限校验） | 使用 | 不使用 |
|
||
| Idempotency（幂等性） | 按需使用 | 不使用 |
|
||
| RequestID 注入 | 使用 | 使用 |
|