图片理解

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

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

接口地址

POST https://{your-domain}/v1/chat/completions

OpenAI SDK 的 base_url：

https://{your-domain}/v1

示例模型：

gemini-3.5-flash

鉴权

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 流；具体可用性以渠道能力为准。

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

非流式图片分析

curl

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

请求体

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

响应示例

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

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：

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]

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

Base64 图片

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

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

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

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 原生流式接口验证。

开始使用

API 参考

模型与计费

指南

参考

接口地址

鉴权

请求结构

非流式图片分析

curl

请求体

响应示例

流式图片分析

Base64 图片

Python SDK 示例

JavaScript SDK 示例

常见问题

​接口地址

​鉴权

​请求结构

​非流式图片分析

​curl

​请求体

​响应示例

​流式图片分析

​Base64 图片

​Python SDK 示例

​JavaScript SDK 示例

​常见问题

接口地址

鉴权

请求结构

非流式图片分析

curl

请求体

响应示例

流式图片分析

Base64 图片

Python SDK 示例

JavaScript SDK 示例

常见问题