多模态对话¶

使用 Chat Completions API 向支持视觉输入的模型同时发送文本和图像。完成本页操作后，你将构造图文 messages，并从 Chat Completions 响应中读取模型对图像的回复。

前提条件¶

已从获取可用模型取得当前凭证可用的模型 ID，并在模型详情中确认其适用于多模态对话且支持视觉输入。
已使用最小图文请求验证所选模型可以处理图像。
已按身份认证配置访问令牌。
已准备可访问的图像 URL；如果使用内联图片，已准备 data:image/...;base64,... 形式的数据。

请求地址¶

POST <GENESIS_BASE_URL>/chat/completions

发送图文请求¶

在 user 消息中，将 content 设为数组。数组中的每一项是一个文本或图像内容片段。将 <MODEL_ID>、$GENESIS_ACCESS_TOKEN 和图片 URL 替换为当前环境的值：

curl -X POST "$GENESIS_BASE_URL/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -d '{
    "model": "<MODEL_ID>",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "这张图片里有什么？请描述细节。"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://<IMAGE_HOST>/<IMAGE_PATH>"
            }
          }
        ]
      }
    ],
    "max_tokens": 1024
  }'

图片 URL 必须能被当前模型服务读取。https://<IMAGE_HOST>/<IMAGE_PATH> 只是占位值，不能直接作为真实图片使用。

使用内联图片¶

不能提供可访问 URL 时，可以在同一个 image_url.url 字段中传入 Data URL。将图片编码为 Base64，并提供正确的媒体类型：

{
  "type": "image_url",
  "image_url": {
    "url": "data:image/jpeg;base64,<BASE64_ENCODED_IMAGE>"
  }
}

使用 Base64 会增大请求体。图片格式、大小限制和图像输入对应的用量以当前模型详情和实际响应为准。

请求参数¶

字段	类型	必需	说明
`model`	string	是	当前凭证可用、且已确认支持多模态对话和视觉输入的模型 ID。首次接入时先发送最小图文请求验证。
`messages`	array	是	按对话顺序传入的消息列表。图像输入放在 `user` 消息的 `content` 数组中。
`messages[].role`	string	是	图文请求使用 `user` 角色承载输入。继续对话时，可按顺序传入此前的消息。
`messages[].content`	array	是	文本和图像内容片段的有序数组。模型按该顺序接收片段。
`messages[].content[].type`	string	是	内容片段类型。当前图文请求使用 `text` 或 `image_url`。
`messages[].content[].text`	string	`type` 为 `text` 时	要发送的文本内容，例如提问或图片处理指令。
`messages[].content[].image_url.url`	string	`type` 为 `image_url` 时	可访问的图像 URL，或 `data:image/...;base64,...` 形式的内联图片。
`max_tokens`	integer	否	限制本次响应最多生成的 Token 数。输出因长度限制结束时，可在当前模型和接口允许的范围内调整。
`stream`	boolean	否	控制返回完整响应还是 SSE 增量事件。启用后按Chat Completions 流式输出处理事件。

不要将文本对话中的字符串 content 与图文请求中的数组 content 混用。其他可选参数是否支持，以当前模型和控制台接口说明为准。

成功响应¶

图文请求与文本对话使用相同的 Chat Completions 响应形态。模型对图像的理解或识别结果位于 choices[0].message.content：

{
  "id": "<request-id>",
  "object": "chat.completion",
  "created": 0,
  "model": "<MODEL_ID>",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "图中是一台银灰色工业设备，位于厂房环境中。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}

字段	类型	返回条件	说明
`id`	string	成功响应返回	本次响应的标识。排查调用问题时提供该值。
`model`	string	成功响应返回	实际处理本次请求的模型 ID。
`choices[].message.content`	string	模型返回文本时	模型对图文输入生成的回复。
`choices[].finish_reason`	string	成功响应返回	生成结束原因。`length` 表示输出达到当前长度限制，不能视为完整回答。
`usage`	object	当前响应包含时	本次请求的 Token 用量信息。只读取实际返回的字段。

常见问题¶

现象	先检查	下一步
模型不接受图像输入	模型是否适用于多模态对话、是否支持视觉输入，以及 `model` 值	更换为已确认支持视觉输入的多模态对话模型，再发送最小图文请求。
图像无法读取	图像 URL 是否可访问，或 Data URL 是否具有正确的媒体类型和 Base64 内容	使用可访问图片 URL 重新验证；不要将本地文件路径直接传入 `image_url.url`。
请求参数错误	`content` 是否为数组，以及每个片段的 `type` 和字段是否匹配	文本片段使用 `text`，图像片段使用 `image_url` 和 `image_url.url`。
服务端返回 `5xx`	HTTP 状态码、错误消息、`model` 值和图像输入形态	使用不含其他可选参数的最小图文请求重试；持续失败时，更换另一已验证的模型，并提供脱敏后的状态码、错误消息和模型 ID 进行排查。
输出因 `length` 结束	`choices[].finish_reason` 和 `max_tokens`	缩短输入或在允许范围内调整 `max_tokens` 后重试。
认证失败	请求地址、令牌和 `Authorization` Header	按身份认证重新配置当前环境的凭据。

下一步¶

最后更新于 2026 年 8 月 14 日