# 多模态对话

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

## 前提条件

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

## 请求地址

```text
POST <GENESIS_BASE_URL>/chat/completions
```

## 发送图文请求

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

```bash
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，并提供正确的媒体类型：

```json
{
  "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 流式输出](streaming-chat-completions.md)处理事件。 |

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

## 成功响应

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

```json
{
  "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 | 按[身份认证](../../getting-started/authentication.md)重新配置当前环境的凭据。 |

## 下一步

- [处理图文对话的流式输出](streaming-chat-completions.md)
- [查看当前凭证可用的模型](../../getting-started/available-models.md)
- [将文本或图文内容转换为向量](../../retrieval-vector/embeddings.md)