> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wengaocloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 图片理解

> 通过 OpenAI 兼容的 /v1/chat/completions 调用 Gemini 图片理解能力。

Gemini OpenAI 兼容图片理解适合已经使用 OpenAI `messages[].content` 多模态数组的客户。文本问题和图片 URL 放在同一个 `user` 消息里，平台会按 OpenAI 兼容请求体转发到支持图片理解的 Gemini 渠道。

<Note>
  图片理解可以使用 OpenAI 兼容格式快速迁移；如果客户需要与 Gemini 官方格式完全一致，或要同时接入视频、文档等原生多模态能力，建议使用「Gemini / 原生格式」下的对应文档。
</Note>

## 接口地址

```http theme={null}
POST https://{your-domain}/v1/chat/completions
```

OpenAI SDK 的 `base_url`：

```text theme={null}
https://{your-domain}/v1
```

示例模型：

```text theme={null}
gemini-3.5-flash
```

## 鉴权

```http theme={null}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 请求结构

| 字段                           | 类型      | 必填   | 说明                                               |
| ---------------------------- | ------- | ---- | ------------------------------------------------ |
| `model`                      | string  | 是    | 支持图片理解的 Gemini 模型名称。                             |
| `messages`                   | array   | 是    | OpenAI 风格消息数组。                                   |
| `messages[].content`         | array   | 是    | 多模态内容数组，包含 `text` 和 `image_url`。                 |
| `content[].type`             | string  | 是    | 文本传 `text`，图片传 `image_url`。                      |
| `content[].text`             | string  | 文本必填 | 对图片提出的问题或输出要求。                                   |
| `content[].image_url.url`    | string  | 图片必填 | 公网可匿名访问的图片 URL，也可使用 `data:image/...;base64,...`。 |
| `content[].image_url.detail` | string  | 否    | 可传 `low`、`high` 或 `auto`，具体以模型支持为准。              |
| `max_tokens`                 | integer | 否    | 最大输出 token 数。                                    |
| `stream`                     | boolean | 否    | `true` 时返回 SSE 流；具体可用性以渠道能力为准。                   |

<Warning>
  不要把图片 URL 当作普通字符串发给模型。普通文本 URL 可能只会被模型当作一段文字，而不会触发图片读取。请使用 `type: "image_url"`。
</Warning>

## 非流式图片分析

### curl

```bash theme={null}
curl --request POST \
  --url 'https://{your-domain}/v1/chat/completions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gemini-3.5-flash",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "请分析这张图片，用中文说明主体、细节、文字信息和可能用途。"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQ-wKRN2hJ0qSIP_1W059Wr1rjeqM9BfEWS2Y9XuvCuRw&s",
              "detail": "high"
            }
          }
        ]
      }
    ],
    "max_tokens": 768,
    "temperature": 0.3,
    "stream": false
  }'
```

### 请求体

```json theme={null}
{
  "model": "gemini-3.5-flash",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "请分析这张图片，用中文说明主体、细节、文字信息和可能用途。"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQ-wKRN2hJ0qSIP_1W059Wr1rjeqM9BfEWS2Y9XuvCuRw&s",
            "detail": "high"
          }
        }
      ]
    }
  ],
  "max_tokens": 768,
  "temperature": 0.3,
  "stream": false
}
```

### 响应示例

```json theme={null}
{
  "id": "chatcmpl-img-abc123",
  "object": "chat.completion",
  "created": 1784700000,
  "model": "gemini-3.5-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "这张图片的主体是一只橙白相间的猫，画面聚焦在猫的脸部和身体姿态。图片细节包括毛色、眼睛、耳朵以及相对简洁的背景，未看到明显可读文字。它适合用于宠物识别、图片描述、标签生成或社交媒体内容理解。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 286,
    "completion_tokens": 83,
    "total_tokens": 369
  }
}
```

## 流式图片分析

如果模型和渠道支持图片流式输出，可以设置 `stream: true`。

```bash theme={null}
curl -N --request POST \
  --url 'https://{your-domain}/v1/chat/completions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gemini-3.5-flash",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "请流式分析这张图片，按主体、细节、用途三个小节输出。"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQ-wKRN2hJ0qSIP_1W059Wr1rjeqM9BfEWS2Y9XuvCuRw&s"
            }
          }
        ]
      }
    ],
    "max_tokens": 768,
    "stream": true,
    "stream_options": {
      "include_usage": true
    }
  }'
```

响应为 SSE：

```text theme={null}
data: {"id":"chatcmpl-img-abc123","object":"chat.completion.chunk","created":1784700000,"model":"gemini-3.5-flash","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-img-abc123","object":"chat.completion.chunk","created":1784700000,"model":"gemini-3.5-flash","choices":[{"index":0,"delta":{"content":"主体：图片主要展示一只猫。"},"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-img-abc123","object":"chat.completion.chunk","created":1784700000,"model":"gemini-3.5-flash","choices":[{"index":0,"delta":{"content":"\n细节：可以观察毛色、眼睛、姿态和背景。"},"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-img-abc123","object":"chat.completion.chunk","created":1784700000,"model":"gemini-3.5-flash","choices":[{"index":0,"delta":{"content":"\n用途：适合图片描述、标签生成和内容理解。"},"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl-img-abc123","object":"chat.completion.chunk","created":1784700000,"model":"gemini-3.5-flash","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":276,"completion_tokens":58,"total_tokens":334}}

data: [DONE]
```

<Note>
  如果客户第一次联调图片能力，建议先用非流式请求确认模型确实读到了图片，再切换到 `stream: true`。
</Note>

## Base64 图片

当图片不能提供公网 URL 时，可以把小图片转为 data URL。

```json theme={null}
{
  "model": "gemini-3.5-flash",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "请识别这张截图中的主要文字和按钮。"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
          }
        }
      ]
    }
  ],
  "max_tokens": 768
}
```

## Python SDK 示例

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://{your-domain}/v1",
)

completion = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "请分析这张图片，用中文说明主体、细节和可能用途。"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/image.jpg",
                        "detail": "high",
                    },
                },
            ],
        }
    ],
    max_tokens=768,
)

print(completion.choices[0].message.content)
```

## JavaScript SDK 示例

```javascript theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://{your-domain}/v1",
});

const completion = await client.chat.completions.create({
  model: "gemini-3.5-flash",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "请分析这张图片，用中文说明主体、细节和可能用途。" },
        {
          type: "image_url",
          image_url: {
            url: "https://example.com/image.jpg",
            detail: "high",
          },
        },
      ],
    },
  ],
  max_tokens: 768,
});

console.log(completion.choices[0].message.content);
```

## 常见问题

| 场景          | 表现               | 处理方式                                          |
| ----------- | ---------------- | --------------------------------------------- |
| 模型只复述图片 URL | 可能把 URL 当作普通文本传入 | 使用 `content` 数组，并把图片放在 `type: "image_url"` 中。 |
| 图片无法读取      | URL 需要登录、过期或不是直链 | 换成公网可匿名访问的图片直链，或使用 data URL。                  |
| 识别细节不准确     | 图片太小、模糊、文字被压缩    | 提高分辨率，必要时裁剪关键区域。                              |
| 流式请求失败      | 当前渠道不支持图片流式      | 先使用非流式，或改用 Gemini 原生流式接口验证。                   |