AI API — 接口说明

本文档汇总并规范展示当前项目已支持的主要接口（OpenAI 兼容与视频任务相关）。各接口遵循统一鉴权与返回格式，便于集成与测试。

---

通用要求

• 域名：以选择部署域名为准，示例 xx.xx.com。
• 鉴权方式：HTTP Header 使用 Authorization: Bearer <YOUR_TOKEN>；示例：Authorization: Bearer sk-xxx（你的密钥）。
• Content-Type：除 WebSocket 外，均为 application/json。
• 错误返回：统一返回 error 对象，包含 code 与 message。

---

1) POST /v1/chat/completions

聊天补全（OpenAI 兼容）。

• 请求头：

  • Authorization: Bearer
  • Content-Type: application/json

• 请求体主要参数：

  • model (string, 必填)
  • messages (array, 必填)：消息列表，元素结构：
    • role (string)："user" | "assistant" | "system"
    • content (string | array)：可为纯文本，或由多媒体内容数组 [{ type, text|image_url|input_audio|file|video_url }] 组成。
  • stream (bool)：是否开启流式，默认 false；当设置为 true 时，服务端将以 SSE（Server-Sent Events）流式返回，响应头为 Content-Type: text/event-stream，并以多条 data: 行输出，最后以 data: [DONE] 结束；当为 false 或未设置时，返回一次性 JSON。
  • max_tokens (int)：最大生成 Token 数
  • temperature (float)：采样温度，默认 1.0
  • top_p (float)：核采样参数
  • stop (string | array)：停止符
  • tools (array)：工具调用定义
  • user (string)：调用方标识
  • response_format (object)：如 { type: "json_object" }

• 请求示例：

{
  "model": "gpt-4o-mini",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": [
      { "type": "text", "text": "帮我总结这段话" },
      { "type": "image_url", "image_url": { "url": "https://example.com/a.png" } }
    ] }
  ],
  "stream": false,
  "max_tokens": 512,
  "temperature": 0.7
}

• 响应示例（非流式）：

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "这是总结结果..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 100, "completion_tokens": 120, "total_tokens": 220 }
}

• 响应示例（流式 SSE）：
  • 服务端会设置 Content-Type: text/event-stream，并按行输出 data: <json>，以 [DONE] 结尾。
  • 示例（每行均由服务端以换行分隔发送；以下仅为演示，实际 chunk 内容会更细粒度）：

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1710000000,"model":"gpt-4o-mini","choices":[{"delta":{"role":"assistant","content":"这是"},"index":0}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1710000000,"model":"gpt-4o-mini","choices":[{"delta":{"content":"总结"},"index":0}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1710000000,"model":"gpt-4o-mini","choices":[{"delta":{"content":"结果..."},"index":0}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1710000000,"model":"gpt-4o-mini","choices":[{"finish_reason":"stop","index":0}],"usage":{"prompt_tokens":100,"completion_tokens":120,"total_tokens":220}}

data: [DONE]

• 验证规则与注意：
  • 必填：model、messages。
  • messages 中 content 可为字符串或多媒体内容数组；数组元素支持 type: text | image_url | input_audio | file | video_url。
  • max_tokens 不得超过系统上限；如超限将返回错误。

---

2) POST /v1/images/generations

图片生成（OpenAI 兼容）。

• 请求头：

  • Authorization: Bearer
  • Content-Type: application/json

• 请求体主要参数：

  • model (string, 必填)
  • prompt (string, 建议填写)
  • n (int)：返回数量，默认 1
  • size (string)：如 1024x1024，部分模型（如 dall-e-2/3）支持的尺寸有限制
  • quality (string)：如 standard、hd
  • response_format (string)：url 或 b64_json
  • watermark (bool)：是否叠加水印
  • user (string)：调用方标识

• 请求示例：

{
  "model": "gpt-image-1",
  "prompt": "一只在天空飞翔的蓝色鲸鱼，赛博朋克风",
  "n": 1,
  "size": "1024x1024",
  "response_format": "url",
  "quality": "standard"
}

• 响应示例：

{
  "created": 1710000000,
  "data": [ { "url": "https://example.com/image.png" } ]
}

• 验证规则与注意：
  • 必填：model。
  • prompt 在多数模型为必需；个别模型允许为空但会返回更保守的结果。
  • size 与 quality 的合法取值与模型相关，非法取值会被拦截。

---

3) WebSocket /v1/realtime

OpenAI Realtime API 兼容实时流接口。

• 连接地址：wss://<host>/v1/realtime?model=<model>（或通过 Header 指定模型）

• 握手请求头：

  • Authorization: Bearer
  • Upgrade: websocket
  • Sec-WebSocket-Protocol: realtime（或 json，视服务端与 SDK 要求）

• 会话参数（session.update）：

  • 例如：{ type: "session.update", session: { input_audio_format: "wav", turn_detection: { type: "server" } } }

• 客户端常用事件：

  • session.update：更新会话配置
  • conversation.item.create：追加消息项（文本/音频）
  • response.create：请求服务端生成响应
  • input_audio_buffer.append / commit / clear：发送、提交或清空音频片段

• 服务端常见事件：

  • session.created：会话建立成功
  • response.delta / response.completed：文本增量与完成
  • response.audio.delta / response.audio.completed：音频增量与完成
  • response.error：错误
  • response.done：本轮响应结束

• 计费/用量：服务端事件中可包含 usage 字段，例如 { input_tokens, output_tokens, audio_seconds }。

---

4) POST /v1/video/generations

视频生成任务提交（OpenAI 兼容路径，路由已适配多平台）。

• 请求头：

  • Authorization: Bearer
  • Content-Type: application/json

• 请求体主要参数（以服务端实际解析的字段为准）：

  • model (string, 必填)
  • prompt (string)：文本生成必填之一；与 image 至少提供其一
  • image (string) 或 images (string[])：图生视频所需；若仅提供 image，服务端会转换为 images 统一处理
  • mode (string)：如 "std"（用于 Kling 等平台）；缺省时服务端默认 "std"
  • size (string)：如 "1920x1080"、"1080x1920" 等；Kling 适配器会基于 size 自动映射为 aspect_ratio（1:1/16:9/9:16）
  • duration (int)：视频时长（秒），部分平台用于帧数或计费估算
  • metadata (object)：供应商/平台自定义参数；用于传递未在顶层定义但平台需要的参数，例如：
    • aspect_ratio (string)：如 "16:9"（用于 Kling/Jimeng 等）
    • quality (string)：如 "standard"（平台自定义）
    • negative_prompt、cfg_scale、camera_control 等（Kling）
    • storageUri、sampleCount（Vertex AI）

• 请求示例（建议统一写法）：

{
  "model": "veo-3.0-generate-001",
  "prompt": "傍晚城市航拍，温暖色调，慢镜头",
  "duration": 5,
  "metadata": {
    "aspect_ratio": "16:9",
    "quality": "standard"
  }
}

• 响应示例（任务受理）：不同平台返回略有差异，但至少包含 task_id。
  • Vertex AI：

{ "task_id": "cGFyYW1zL3Byb2plY3RzL3..." }

• Jimeng：

{ "task_id": "vid-20240301-xyz" }

• Kling：返回平台原始结构，包含 code/data 等字段（其中 data.task_id 为任务ID）。

---

5) GET /v1/video/generations/:task_id

视频任务查询（OpenAI 兼容路径）。

• 请求头：

  • Authorization: Bearer

• 路径参数：

  • task_id (string)：提交任务时返回的 ID

• 响应说明：统一包装为 { code, data } 结构。

• 响应示例：

{
  "code": "success",
  "data": {
    "task_id": "vid-20240301-xyz",
    "status": "succeeded", // 枚举：queued | processing | succeeded | failed
    "url": "https://example.com/video.mp4",
    "format": "mp4",
    "metadata": null,
    "error": null
  }
}

• 说明：

  • 对 Vertex AI，服务端在查询时会尝试实时同步上游状态并解析视频格式；其余平台默认返回本地记录的标准化结果。
  • 对 Vertex Veo，上游返回的视频地址 url 也可能是 data URI 形式（例如 data:video/mp4;base64,<base64>），可直接解析其中的 base64 内容并保存为 .mp4 文件。

• 状态取值：queued | running | succeeded | failed。

---

错误返回与排查指引

为便于定位问题与自助排查，以下汇总各接口的错误返回格式、常见状态码与原因示例，并给出建议的处理方式。

• 统一说明（REST 类接口）
  • 出错时，除视频任务接口外，均返回如下结构：

{
  "error": {
    "message": "<错误信息>",
    "type": "new_api_error",
    "code": "<错误码可为空>"
  }
}

• 常见 HTTP 状态码与场景：
  • 400 Bad Request：参数不合法或缺失（invalid_request、read_request_body_failed、convert_request_failed 等）。
  • 401 Unauthorized：鉴权失败（access_denied，令牌无效或未提供）。
  • 403 Forbidden：权限或配额问题（无权访问分组/渠道、用户被封禁、IP 不在白名单、insufficient_user_quota、pre_consume_token_quota_failed）。
  • 429 Too Many Requests：达到频率限制（服务端会返回提示语，如“您已达到请求数限制…”）。
  • 503 Service Unavailable：模型不可用或当前分组下无可用渠道（model_not_found 或上游不可用）。
  • 5xx Server Error：服务端或上游异常（do_request_failed、bad_response_status_code、bad_response_body、empty_response、get_channel_failed 等）。
• 提示：错误 message 中可能包含请求 ID，便于与服务端日志关联定位问题。

---

/v1/chat/completions 错误返回

• 格式（非流式与流式出错时统一为 JSON 错误，可能直接关闭连接）：

{
  "error": {
    "message": "未指定模型名称，模型名称不能为空",
    "type": "new_api_error",
    "code": "invalid_request"
  }
}

• 常见原因与排查：
  • 参数缺失/不合法：未提供 model、messages 为空或 content 类型错误。
  • 鉴权失败：Authorization 头未携带 Bearer Token 或令牌无效（401）。
  • 权限问题：令牌无权访问指定模型/分组，或分组已禁用（403）。
  • 频率限制：达到模型或全局频率上限（429）。
  • 模型不可用：当前分组下该模型无可用渠道（503）。
  • 上游异常：网络错误或上游响应错误（5xx，message 可能为“请求上游地址失败”或“bad response status code ”）。

---

/v1/images/generations 错误返回

• 格式：与 chat 接口一致，返回 error 对象。

{
  "error": {
    "message": "size 不合法，合法示例：1024x1024",
    "type": "new_api_error",
    "code": "invalid_request"
  }
}

• 常见原因与排查：
  • 参数缺失/不合法：未提供 model；size/quality/response_format 取值与模型不匹配。
  • 鉴权/权限：与 chat 相同（401/403）。
  • 频率限制：达到请求上限（429）。
  • 模型不可用或渠道不可用（503）。
  • 上游异常（5xx）。

---

/v1/realtime（WebSocket）错误返回

• 握手阶段（HTTP）失败：返回 JSON 错误，与 REST 类一致（例如 401/403/400）。

{
  "error": {
    "message": "无效的 API Key",
    "type": "new_api_error",
    "code": "access_denied"
  }
}

• 会话阶段（WS 事件）失败：以事件形式返回，type 为 "error"。

{
  "type": "error",
  "event_id": "evt_123456",
  "error": {
    "message": "请求格式不合法或上游错误",
    "type": "new_api_error",
    "code": "invalid_request"
  }
}

• 常见原因与排查：
  • 握手头部不正确：Sec-WebSocket-Protocol 不符合要求或未声明（400）。
  • 鉴权失败：Authorization 令牌无效（401）。
  • 权限/配额限制（403/429）：无权访问模型或达到频率/额度限制。
  • 上游异常或网络问题（5xx）：连接中断或响应错误。

---

POST /v1/video/generations 错误返回（任务提交）

• 格式（与 REST 不同）：任务接口统一返回 TaskError 结构。

{
  "code": "insufficient_user_quota",
  "message": "用户额度不足, 剩余额度: 0"
}

• 其他示例：

{ "code": "invalid_request", "message": "缺少 prompt 或 image" }
{ "code": "pre_consume_token_quota_failed", "message": "预扣费额度失败, 用户剩余额度: 10, 需要预扣费额度: 20" }
{ "code": "do_request_failed", "message": "请求上游地址失败" }

• 常见原因与排查：
  • 参数校验失败：缺少必要字段（如 model、prompt 与 image 至少其一）。
  • 渠道/模型不可用：目标模型在当前分组下无可用渠道（可能返回 503 或 5xx）。
  • 额度/预扣失败（403）：insufficient_user_quota、pre_consume_token_quota_failed。
  • 上游网络/响应错误（5xx）：do_request_failed、bad_response_status_code 等。
  • 服务端持久化失败（500）：insert_task_failed。

---

GET /v1/video/generations/:task_id 错误返回（任务查询）

• 格式：同为 TaskError 结构。

{ "code": "task_not_exist", "message": "task_not_exist" }

• 其他示例：

{ "code": "get_task_failed", "message": "数据库查询失败或服务端异常" }

• 常见原因与排查：
  • 任务不存在/ID 错误：task_not_exist（400）。
  • 服务端查询异常：get_task_failed（500）。
  • 上游实时同步失败：一般不影响返回结构，优先返回本地记录；如需实时状态，请稍后重试。

---

排查建议总览：

• 核对 Authorization: Bearer 是否正确；令牌是否具备模型/分组访问权限。
• 检查是否命中频率限制（429）或额度不足（403）；必要时降低调用频率或提升额度。
• 确认模型在当前分组下可用；如返回 503，请在控制台为该模型配置有效渠道。
• 对参数进行自检：model、messages（chat）、size/quality/response_format（images）、prompt/image（video）。
• 若提示“请求上游地址失败”或“bad response status code ”，请检查上游服务可用性与网络连接。
• 任务查询请确保 task_id 正确；如为新提交任务，稍候再查以避免短暂的未同步状态。

---