图片理解

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

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

接口地址

非流式：

POST https://{your-domain}/v1beta/models/{model}:generateContent

流式：

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

示例模型：

gemini-3.5-flash

鉴权

请求结构

字段	类型	必填	说明
`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`。

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

非流式图片分析

curl

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
    }
  }'

请求体

{
  "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
  }
}

响应示例

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

流式图片分析

curl

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
    }
  }'

响应示例

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 数组中可以放入多张图片，并在文本里说明比较任务。

{
  "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 示例

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 示例

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`。

开始使用

API 参考

模型与计费

指南

参考

接口地址

鉴权

请求结构

非流式图片分析

curl

请求体

响应示例

流式图片分析

curl

响应示例

多图片输入

Python 示例

JavaScript 示例

最佳实践

常见问题

​接口地址

​鉴权

​请求结构

​非流式图片分析

​curl

​请求体

​响应示例

​流式图片分析

​curl

​响应示例

​多图片输入

​Python 示例

​JavaScript 示例

​最佳实践

​常见问题

接口地址

鉴权

请求结构

非流式图片分析

curl

请求体

响应示例

流式图片分析

curl

响应示例

多图片输入

Python 示例

JavaScript 示例

最佳实践

常见问题