> ## 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.

# 图片理解

> 使用 Gemini 原生 fileData.fileUri 分析公网图片 URL，并支持非流式与流式输出。

Gemini 原生图片理解适合图像描述、商品识别、截图解析、票据/表格初步理解、图片问答等场景。请求仍使用 `contents[].parts[]`，在同一条消息里同时放入文字问题和图片文件片段。

<Note>
  图片 URL 建议使用 Gemini 原生 `fileData.fileUri`。这比把图片伪装成普通文本 URL 更稳定，也比 OpenAI 兼容层更接近上游原生能力。
</Note>

## 接口地址

非流式：

```http theme={null}
POST https://{your-domain}/v1beta/models/{model}:generateContent
```

流式：

```http theme={null}
POST https://{your-domain}/v1beta/models/{model}:streamGenerateContent?alt=sse
```

示例模型：

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

## 鉴权

推荐：

```http theme={null}
x-goog-api-key: YOUR_API_KEY
Content-Type: application/json
```

兼容：

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

## 请求结构

| 字段                                     | 类型      | 必填 | 说明                                                   |
| -------------------------------------- | ------- | -- | ---------------------------------------------------- |
| `contents[].parts[].text`              | string  | 是  | 对图片提出的问题或输出要求。                                       |
| `contents[].parts[].fileData.mimeType` | string  | 是  | 图片 MIME 类型，例如 `image/jpeg`、`image/png`、`image/webp`。 |
| `contents[].parts[].fileData.fileUri`  | string  | 是  | 公网可匿名访问的图片 URL。                                      |
| `generationConfig.maxOutputTokens`     | integer | 否  | 最大输出 token 数。                                        |
| `generationConfig.temperature`         | number  | 否  | 需要稳定识别时建议较低，例如 `0.2` 到 `0.5`。                        |

<Warning>
  `fileUri` 必须是图片文件直链。不要传网页地址、登录后才可见的图片、内网地址、过期签名链接或本地文件路径。若图片来自对象存储，请确保上游模型可以匿名读取。
</Warning>

## 非流式图片分析

### curl

```bash theme={null}
curl --request POST \
  --url 'https://{your-domain}/v1beta/models/gemini-3.5-flash:generateContent' \
  --header 'x-goog-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "请分析这张图片，用中文说明主体、细节、文字信息和可能用途。"
          },
          {
            "fileData": {
              "mimeType": "image/jpeg",
              "fileUri": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQ-wKRN2hJ0qSIP_1W059Wr1rjeqM9BfEWS2Y9XuvCuRw&s"
            }
          }
        ]
      }
    ],
    "generationConfig": {
      "maxOutputTokens": 768,
      "temperature": 0.3
    }
  }'
```

### 请求体

```json theme={null}
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "请分析这张图片，用中文说明主体、细节、文字信息和可能用途。"
        },
        {
          "fileData": {
            "mimeType": "image/jpeg",
            "fileUri": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQ-wKRN2hJ0qSIP_1W059Wr1rjeqM9BfEWS2Y9XuvCuRw&s"
          }
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 768,
    "temperature": 0.3
  }
}
```

### 响应示例

```json theme={null}
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "这张图片的主体是一只橙白相间的猫，画面中猫靠近镜头，背景较为简洁。图片细节包括猫的面部、眼睛、毛色和姿态，整体适合做宠物识别、图片描述或社交媒体内容理解。画面中没有明显可读文字，因此可重点围绕主体、环境和情绪进行描述。"
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": []
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 280,
    "candidatesTokenCount": 92,
    "totalTokenCount": 372
  }
}
```

## 流式图片分析

### curl

```bash theme={null}
curl -N --request POST \
  --url 'https://{your-domain}/v1beta/models/gemini-3.5-flash:streamGenerateContent?alt=sse' \
  --header 'x-goog-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "请流式分析这张图片，按主体、细节、用途三个小节输出。"
          },
          {
            "fileData": {
              "mimeType": "image/jpeg",
              "fileUri": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQ-wKRN2hJ0qSIP_1W059Wr1rjeqM9BfEWS2Y9XuvCuRw&s"
            }
          }
        ]
      }
    ],
    "generationConfig": {
      "maxOutputTokens": 768
    }
  }'
```

### 响应示例

```text theme={null}
data: {"candidates":[{"content":{"role":"model","parts":[{"text":"主体："}]},"finishReason":null,"index":0}],"usageMetadata":{"promptTokenCount":270,"totalTokenCount":270}}

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"图片中主要是一只猫，画面聚焦在它的面部和上半身。"}]},"finishReason":null,"index":0}],"usageMetadata":{"promptTokenCount":270,"totalTokenCount":270}}

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"\n细节：可以观察毛色、眼睛、姿态、背景和是否包含文字。"}]},"finishReason":null,"index":0}],"usageMetadata":{"promptTokenCount":270,"totalTokenCount":270}}

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"\n用途：适合宠物图片描述、内容审核、标签生成或相册检索。"}]},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":270,"candidatesTokenCount":63,"totalTokenCount":333}}
```

## 多图片输入

同一个 `parts` 数组中可以放入多张图片，并在文本里说明比较任务。

```json theme={null}
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "请比较两张图片的主体差异，并说明哪一张更适合作为商品主图。"
        },
        {
          "fileData": {
            "mimeType": "image/jpeg",
            "fileUri": "https://example.com/image-a.jpg"
          }
        },
        {
          "fileData": {
            "mimeType": "image/png",
            "fileUri": "https://example.com/image-b.png"
          }
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 1024
  }
}
```

## Python 示例

```python theme={null}
import requests

api_key = "YOUR_API_KEY"
model = "gemini-3.5-flash"
url = f"https://{{your-domain}}/v1beta/models/{model}:generateContent"

payload = {
    "contents": [
        {
            "role": "user",
            "parts": [
                {"text": "请分析这张图片，用中文说明主体、细节和可能用途。"},
                {
                    "fileData": {
                        "mimeType": "image/jpeg",
                        "fileUri": "https://example.com/image.jpg",
                    }
                },
            ],
        }
    ],
    "generationConfig": {"maxOutputTokens": 768},
}

resp = requests.post(
    url,
    headers={
        "x-goog-api-key": api_key,
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=90,
)
resp.raise_for_status()
print(resp.json())
```

## JavaScript 示例

```javascript theme={null}
const apiKey = "YOUR_API_KEY";
const model = "gemini-3.5-flash";

const response = await fetch(
  `https://{your-domain}/v1beta/models/${model}:generateContent`,
  {
    method: "POST",
    headers: {
      "x-goog-api-key": apiKey,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      contents: [
        {
          role: "user",
          parts: [
            { text: "请分析这张图片，用中文说明主体、细节和可能用途。" },
            {
              fileData: {
                mimeType: "image/jpeg",
                fileUri: "https://example.com/image.jpg",
              },
            },
          ],
        },
      ],
      generationConfig: {
        maxOutputTokens: 768,
      },
    }),
  }
);

if (!response.ok) {
  throw new Error(await response.text());
}

console.log(await response.json());
```

## 最佳实践

| 建议            | 说明                                                         |
| ------------- | ---------------------------------------------------------- |
| 使用真实 MIME 类型  | JPEG 传 `image/jpeg`，PNG 传 `image/png`，WebP 传 `image/webp`。 |
| 在文本里明确任务      | 例如「提取表格字段」「判断商品瑕疵」「按主体/背景/文字输出」。                           |
| 对 OCR 类任务降低温度 | 建议 `temperature` 设置为 `0.2` 到 `0.4`，减少发挥。                   |
| 图片过大时先压缩      | 保持关键文字和主体清晰，减少加载失败和 token 成本。                              |
| URL 有效期留足     | 临时签名链接应覆盖完整请求和上游读取时间。                                      |

## 常见问题

| 场景         | 表现                   | 处理方式                                   |
| ---------- | -------------------- | -------------------------------------- |
| 返回无法查看图片   | 图片 URL 不是公网直链或需要鉴权   | 换成匿名可访问直链，或先上传到可访问对象存储。                |
| 图片中文字识别不完整 | 图片分辨率低、压缩严重或文字过小     | 提高图片清晰度，必要时裁剪出包含文字的区域。                 |
| 多图比较结果混淆   | 模型不知道哪张是 A/B         | 在文本里明确「第一张」「第二张」，并按顺序放入 `parts`。       |
| 响应过短       | `maxOutputTokens` 太小 | 调大 `generationConfig.maxOutputTokens`。 |