3. 请求体

3.1 请求体结构

{
  "model": "qwen3.6-plus",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "你好"}
  ],
  "images": ["https://example.com/a.png"],
  "videos": ["https://example.com/a.mp4"],
  "file_urls": ["https://example.com/a.pdf"],
  "voices": ["https://example.com/a.mp3"],
  "stream": false,
  "media_roles": {
    "images": ["first_frame"],
    "videos": ["first_clip"],
    "voices": ["driving_audio"]
  }
}

3.2 顶层参数

字段	类型	必填	说明
model	string	是	模型 id。
messages	object[]	是	会话消息数组。
stream	boolean	否	是否返回流式响应。默认 false。
images	string[]	否	图片 URL 数组。用于图片生成、视频生成或多模态理解。
videos	string[]	否	视频 URL 数组。用于视频续写或多模态理解。
file_urls	string[]	否	文件 URL 数组。用于支持文件理解的模型。
voices	string[]	否	音频 URL 数组。用于部分视频生成场景的驱动音频输入。
media_roles	object	否	多媒体角色映射参数，用于显式指定媒体语义。
未列出的其他顶层字段	mixed	否	作为模型扩展参数处理；仅在目标模型支持时生效，不保证跨模型通用。

3.3 消息数组（messages）子项

字段	类型	必填	说明
role	string	是	取值 system / user / assistant，不得为空。
content	string	是*	消息文本内容。文本、TTS 及图片/视频生成场景须至少有一条非空 content 的消息；多模态理解（glm-5v-turbo、kimi-k2.6）场景若已传 images/videos/file_urls，则 content 可为空字符串。

约束：

• messages 不能为空数组。
• messages[].role 不能为空字符串。
• TTS 及图片/视频生成场景：若所有消息 content 均为空，将分别返回 invalid request: text is required 或 invalid request: prompt is required。
• 多模态理解场景：若 images/videos/file_urls 均未传且 content 也为空，将返回 invalid request: text or at least one of images, videos, file_urls is required。
• 纯文本模型：内容格式的合法性由模型自身校验，违规时响应中会返回相应错误。

3.4 媒体角色（media_roles）说明

media_roles 用于在视频生成相关模型中精确指定媒体含义。

{
  "media_roles": {
    "images": ["first_frame", "last_frame"],
    "videos": ["first_clip"],
    "voices": ["driving_audio"],
    "bindings": {
      "reference_voice": {
        "ref_media_index": 0,
        "voice_index": 0
      }
    }
  }
}

字段说明：

字段	类型	说明
media_roles.images	string[]	与 images 等长。可选值：first_frame（首帧图）、last_frame（尾帧图）、reference_image（参考图片）。
media_roles.videos	string[]	与 videos 等长。可选值：first_clip（首段视频）、reference_video（参考视频）。
media_roles.voices	string[]	与 voices 等长；当前公开支持值为 driving_audio（驱动音频）。
media_roles.bindings.reference_voice.ref_media_index	integer	关联的参考媒体索引。
media_roles.bindings.reference_voice.voice_index	integer	关联的音频索引。

校验规则：

• media_roles.images/videos/voices 与对应媒体数组长度必须一致。
• ref_media_index、voice_index 必须在数组有效索引范围内。

3.5 能力约束

建议按以下方式组织请求：

• 文本模型：除已声明支持多模态理解的文本模型外，传入 images/videos/file_urls/voices 将返回 invalid_request_error。
• 多模态理解模型：使用 messages + images/videos/file_urls。
• 视频生成模型：使用 messages + images/videos/voices（按模型能力组合）。
• 语音合成模型：使用 messages 提供待合成文本。

能力入参矩阵：

能力	必需字段	常见可选字段
文本	model, messages	stream, temperature, top_p, max_tokens, enable_thinking, enable_search
多模态理解	model, messages	images, videos, file_urls, stream
图片生成	model, messages	images, size, n, watermark
视频生成	model, messages	images, videos, voices, duration, resolution, ratio
语音合成	model, messages	stream, voice, voice_id, language_type

补充说明：

• voices 用于音频输入场景，不等同于 TTS 音色参数。
• TTS 音色通常使用 voice 或 voice_id。
• glm-5v-turbo、kimi-k2.6 可用于多模态理解场景。
• 部分视频生成模型（如 wan2.7-i2v）要求 images（首帧）或 videos（首段）至少提供其一。

3.6 常用可选参数

字段	类型	说明
temperature	number	采样温度，值越高输出随机性越强。
top_p	number	核采样参数，控制候选 token 概率质量。
max_tokens	integer	最大输出 token 数。
max_completion_tokens	integer	部分模型使用的最大生成长度参数。
enable_thinking	boolean	开启思考模式。支持：Qwen3、DeepSeek-V4、GLM-5.1、Kimi-K2.6。不适用：MiniMax-M2.7/highspeed。
thinking_budget	integer	思维链最大 Token 数。仅 Qwen3 支持。
enable_search	boolean	开启联网搜索。支持：Qwen3、GLM-5.1、Kimi-K2.6。注意：Kimi 传 true 时会强制关闭思考模式；DeepSeek-V4 与 MiniMax 不生效。
stream_options	object	流式输出附加选项（如 include_usage）。
response_format	object	结构化输出参数（如 JSON 模式）。
tools	object[]	工具调用配置。
tool_choice	string/object	工具选择策略。
reasoning_effort	string	推理力度，可选值 high/max。支持：DeepSeek-V4 系列、Kimi-K2.6。

3.7 扩展参数与未知字段

为保证公开对外契约清晰，建议按以下原则理解请求字段：

• model、messages、stream、images、videos、file_urls、voices、media_roles 属于本接口的统一字段。
• 除统一字段外，其余顶层字段会作为模型扩展参数参与请求构建，例如 temperature、size、voice_id、negative_prompt 等。
• 模型扩展参数不是跨模型统一契约。某个字段在一个模型上可用，不代表在另一个模型上也可用。
• 对于本文档未明确说明支持范围的扩展参数，目标模型可能接受、忽略，或直接返回参数错误；调用方不应依赖“未知参数一定被忽略”的行为。
• 若你的接入需要稳定的跨模型兼容性，请仅使用统一字段与本文档明确标注支持范围的可选参数。