参数

示例中的 <BASE_URL> 请从接入点选择并替换。

POST /v1/chat/completions 请求参数说明。

必需

参数	类型	说明
`model`	string	`GET /v1/models` 中的模型 id
`messages`	array	OpenAI 聊天消息；`content` 可为字符串，也可为 content part 数组（文本 + 图片 / 视频等）

常用可选参数

SupaNexus 在模型支持范围内透传 OpenAI 标准参数。可用性取决于模型 — 见模型对象的 supported_parameters。

参数	类型	说明	示例
`stream`	boolean	是否逐字流式返回；聊天界面通常设为 `true`，批处理可设为 `false`	`"stream": true`
`temperature`	number	随机程度：越高越发散、越有创意；越低越稳定、越可重复。日常对话常用 `0.7`，事实问答可降到 `0`–`0.3`	`"temperature": 0.7`
`top_p`	number	另一种控制随机性的方式（核采样），一般与 temperature 二选一微调即可	`"top_p": 0.9`
`max_tokens`	integer	回复长度上限（token 数），防止一次生成过长或超出预算	`"max_tokens": 1024`
`frequency_penalty`	number	少重复同一用词：越高越不爱「车轱辘话」	`"frequency_penalty": 0.5`
`presence_penalty`	number	鼓励聊新内容：越高越不容易一直卡在同一个话题上	`"presence_penalty": 0.3`
`stop`	string 或 array	模型生成到这些停止词时结束；可用来截断列表、段落等	`"stop": ["\n\n", "END"]`
`tools`	array	告诉模型可以调用哪些函数（如查天气、查订单）；需模型支持 Function Calling	见下方示例
`tool_choice`	string 或 object	是否必须调工具：`"auto"` 由模型决定，`"none"` 禁止，`"required"` 必须调	`"tool_choice": "auto"`
`response_format`	object	要求模型按指定格式输出，例如只要合法 JSON	`"response_format": {"type": "json_object"}`
`user`	string	终端用户 id（你的 App 里每个用户的标识），便于滥用追踪；OpenAI 模型还可提高 Prompt Cache 命中率	`"user": "user-42"`

tools 示例（简化）：

"tools": [
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "查询指定城市的当前天气",
      "parameters": {
        "type": "object",
        "properties": {
          "city": { "type": "string", "description": "城市名，如 上海" }
        },
        "required": ["city"]
      }
    }
  }
]

多模态输入

当模型支持视觉或视频时，messages[].content 可为 content part 数组（OpenAI 兼容格式）。

先通过 GET /v1/models 确认 architecture.input_modalities：含 "image" 可发图，含 "video" 可发视频。纯文本模型（仅 ["text"]）不接受媒体。

图片（`image_url`）

URL 图片示例

{
  "model": "google/gemini-2.5-flash",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "请描述这张图片的内容"},
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/photo.jpg"
          }
        }
      ]
    }
  ]
}

Base64 图片示例

将 image_url.url 设为 data URI：

{
  "type": "image_url",
  "image_url": {
    "url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  }
}

Base64 会使请求体体积膨胀约 33%。默认请求体上限为 64 MB，超限返回 413（error.code = request_too_large）。大图建议使用公网可访问的 URL。

视频（`video_url`）

当 input_modalities 包含 "video"（例如 minimax/minimax-m3、moonshot/kimi-k2.6）时，可使用 video_url content part。

Whale 第一版约定：

允许	不允许
公网 `http://` / `https://` 视频 URL（上游自行拉取）	`data:`（base64）、`file://`、`blob:`、厂商私有引用（如 `mm_file://`、`ms://`）

非法 video_url 网关返回 400，不会转发到上游。视频勿用 data URI 过网关，以免占用平台带宽。

公网视频 URL 示例

{
  "model": "minimax/minimax-m3",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "总结这个视频的主要内容"},
        {
          "type": "video_url",
          "video_url": {
            "url": "https://example.com/demo.mp4",
            "detail": "default"
          }
        }
      ]
    }
  ]
}

部分上游还支持 fps 等抽帧字段，在模型支持范围内会透传。

限制：Anthropic 上游模型

用 OpenAI 客户端（POST /v1/chat/completions）调用 anthropic/* 时，网关会做协议转换并将消息压成纯文本，图片会被静默丢弃且不报错。发图请用 POST /v1/messages。

建议：发图时客户端协议与上游一致——anthropic/* 用 /v1/messages，其余用 /v1/chat/completions。

请求处理说明

识别的字段

model — 本次调用的模型 id
stream — 是否返回 SSE 流式响应

流式 usage

stream: true 时，响应末尾可能包含 usage 对象（取决于模型支持情况）。

其它参数

请求体中其余 JSON 字段在体积限制内按 OpenAI 兼容方式处理。

请求体大小限制

默认最大 64 MB（GATEWAY_OPENAPI_MAX_REQUEST_BODY_BYTES）。

超限返回 413，error.code 为 request_too_large。大图可用 data URI；大视频必须用公网 URL，不要把视频 base64 塞进请求体。

模型默认参数

GET /v1/models 中的 default_parameters 为建议默认值，客户端可在请求中覆盖。

参数

必需