原创文章

Gemini API 图片识别怎么调用?国内接入与 Python 示例

Gemini API 怎么识别图片?本文介绍通过支持图片输入的中转接口调用 Gemini,提供 Python 图片问答示例,讲解 Base64 图片传输、截图分析、模型选择及常见报错,适合国内开发者接入多模态应用。

作者: 发布时间: 更新时间:

如果你已经用 Gemini API 实现了文本问答,接下来可能会想:

能不能把图片一起发给模型,让它分析截图、识别商品,或者提取图片里的文字?

可以,但需要同时满足两个条件:

  • 选择的 Gemini 模型支持图片输入。
  • 使用的 API 服务支持对应的图片传输格式。

对于国内开发者,如果希望通过大模型 API 中转站接入,可以先确认平台是否支持 Gemini 的多模态调用,以及是否提供 OpenAI 兼容图片输入格式。

这篇文章以支持 image_url 消息格式的兼容接口为例,介绍 Gemini API 图片识别、图片问答和 Python 调用方法。

大模型 API 中转服务入口:

平台地址:https://quanzil.com

平台地址:https://quanzil.net

具体模型、图片格式、请求大小限制和价格,请以平台当前开发文档为准。


Gemini API 图片识别可以做什么

图片识别不只是判断“这是一只猫”或“这是一件商品”。

支持图片输入的 Gemini 模型,可以结合图片和文字问题完成多种任务。

场景 输入内容 可以提出的问题
商品图分析 商品照片 图片中有哪些可见的外观特点?
页面截图分析 网站或 App 截图 页面上有哪些按钮和提示信息?
图片文字提取 海报、截图、文档照片 请提取图片中的可见文字
表格截图分析 表格图片 请按行整理表格中的数据
图表解读 折线图、柱状图 图表展示了什么趋势?
客服辅助 用户上传的截图 图片中显示了什么报错?

实际效果会受到图片清晰度、文字大小、版式复杂度和模型能力影响。

涉及金额、编号、日期等关键字段时,建议增加规则校验或人工复核,不应直接假定识别结果完全准确。


Gemini 图片理解和图片生成有什么区别

接入前,先明确自己的需求。

图片理解是将已有图片作为输入,让模型描述、分析或回答问题。

例如:

请分析这张商品图片,列出可见的颜色、形状和配件。

图片生成是让模型创建新的图片,可能需要不同的模型、接口和参数。

本文介绍的是图片理解调用,不是图片生成教程。支持图片输入的聊天模型,也不一定支持输出图片。


国内调用 Gemini 图片接口,需要准备什么

在写代码前,先确认以下配置。

1. 平台 API Key

如果使用中转接口,应填写中转平台签发的 Key,并搭配该平台提供的请求地址。

不要混用不同平台的 Key 和接口地址。

2. 完整聊天接口地址

本文使用 Python requests 直接发送 HTTP 请求,因此需要完整接口地址。

地址结构可能类似:

https://your-api-domain.com/v1/chat/completions

这里的域名仅用于说明格式,需要替换成平台实际提供的地址。

3. 支持图片输入的模型 ID

从平台模型列表确认:

  • 当前 Gemini 模型是否支持图片输入。
  • 当前 Key 是否具备调用权限。
  • 是否支持本文使用的 image_url 格式。
  • 是否接受 Base64 Data URL。

文本请求成功,并不代表图片请求一定能使用同样的配置。

4. 一张用于测试的图片

建议第一次测试使用:

  • 内容简单的 JPG 或 PNG 图片
  • 清晰、方向正确的截图
  • 不包含敏感资料的测试图片

先用单张图片跑通接口,再测试多图或复杂文档。


Gemini API 怎么传入图片

通过支持图片输入的 OpenAI 兼容接口调用时,一条用户消息可以同时包含文字和图片。

示例结构如下:

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "请描述这张图片中的主要内容。"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "这里填写平台支持的图片URL或Data URL"
      }
    }
  ]
}

注意这里的 content 是数组,而不是普通文本字符串。

文字部分用于告诉模型需要完成什么任务;图片部分提供分析对象。

常见的图片传输方式有两种。

使用图片 URL

如果平台支持,可以传入服务端能够访问的图片地址。

需要注意:

  • 图片链接是否需要登录或额外鉴权。
  • 链接是否已经过期。
  • 是否存在防盗链限制。
  • API 服务是否能够访问该地址。

浏览器能够打开图片,不代表模型服务也能够下载图片。

使用 Base64 Data URL

将本地图片编码后,直接放入请求体:

data:image/jpeg;base64,图片的Base64编码

这种方式不需要将图片先上传到公开地址,但会增加请求体大小。

编码后的大小通常比原始文件大约增加三分之一,仍需遵守平台的请求大小限制。

下文使用这种方式演示。


Python 调用 Gemini 图片识别示例

安装依赖

python -m pip install requests

配置环境变量

在 macOS 或 Linux 终端中执行:

export AI_API_KEY="替换为你的中转平台API Key"
export AI_CHAT_URL="替换为平台提供的完整聊天接口地址"
export GEMINI_MODEL="替换为支持图片输入的Gemini模型ID"

如果使用 Windows PowerShell:

$env:AI_API_KEY="替换为你的中转平台API Key"
$env:AI_CHAT_URL="替换为平台提供的完整聊天接口地址"
$env:GEMINI_MODEL="替换为支持图片输入的Gemini模型ID"

创建调用脚本

准备一张名为 example.jpg 的图片,放在脚本所在目录。

创建 gemini_image.py:

import base64
import os
from pathlib import Path

import requests

required_vars = [
    "AI_API_KEY",
    "AI_CHAT_URL",
    "GEMINI_MODEL",
]

missing = [
    name for name in required_vars
    if not os.environ.get(name)
]

if missing:
    raise RuntimeError(
        "缺少环境变量:" + ", ".join(missing)
    )

image_path = Path(__file__).resolve().parent / "example.jpg"

mime_types = {
    ".jpg": "image/jpeg",
    ".jpeg": "image/jpeg",
    ".png": "image/png",
}

mime_type = mime_types.get(image_path.suffix.lower())

if mime_type is None:
    raise ValueError("本示例仅处理 JPG 和 PNG 图片。")

image_base64 = base64.b64encode(
    image_path.read_bytes()
).decode("ascii")

image_data_url = f"data:{mime_type};base64,{image_base64}"

payload = {
    "model": os.environ["GEMINI_MODEL"],
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": (
                        "请用中文描述图片中的主要内容。"
                        "只描述可见信息,无法确认的内容请说明。"
                    ),
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": image_data_url,
                    },
                },
            ],
        }
    ],
}

response = requests.post(
    os.environ["AI_CHAT_URL"],
    headers={
        "Authorization": f"Bearer {os.environ['AI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=(10, 120),
)

response.raise_for_status()
data = response.json()

choices = data.get("choices")
if not choices:
    raise RuntimeError(
        "响应中没有 choices,请检查平台返回格式。"
    )

print(choices[0]["message"].get("content"))

运行:

python gemini_image.py

示例按文件扩展名选择 MIME 类型,因此图片必须是对应格式的真实文件。不要仅通过修改后缀,将其他格式的文件伪装成 JPG。

如果要分析 PNG 图片,将代码中的 example.jpg 改为对应文件名即可。


图片识别提示词怎么写

图片问答的效果,不只取决于模型,也取决于问题是否明确。

例如:

看看这张图片。

模型可能给出泛泛的描述。

如果希望结果便于业务使用,可以明确任务、范围和输出格式。

商品图片分析

请分析商品图片中的可见信息,分别列出:

1. 商品类别
2. 主要颜色
3. 外观特点
4. 可见配件

不要推测图片无法证明的材质、品牌和功能。
无法确认的项目请写“无法确认”。

截图报错分析

请提取截图中的报错文字,并解释可能含义。
先列出截图中能直接看到的信息,再给出排查建议。
如果文字不清晰,请指出无法识别的位置。

表格文字提取

请按从上到下的顺序提取表格内容。
保留金额、单位和日期。
看不清的单元格请标记为“无法识别”,不要补写数据。

网页截图分析

请从截图中识别页面标题、主要按钮和提示文字。
根据可见内容分析用户可能在哪一步遇到操作困难。
不要假设截图之外的页面功能。

对于结构化结果,可以要求模型按固定字段回答;如果需要严格 JSON,还应确认接口是否支持相应结构化输出,并在业务层验证结果。


Gemini 图片调用常见报错

返回 400:图片格式或模型不支持

先检查:

  • 模型是否支持图片输入。
  • 平台是否支持 image_url。
  • 是否接受 Base64 Data URL。
  • MIME 类型是否与真实文件一致。
  • content 数组结构是否正确。
  • 请求体或图片尺寸是否超过限制。

可以先用一张较小、清晰的 JPG 图片测试,减少变量。

返回 413:请求体过大

如果平台返回 413 Payload Too Large,通常需要检查请求大小。

可以尝试:

  • 裁剪无关区域。
  • 适当降低图片分辨率。
  • 使用合理的压缩质量。
  • 减少单次传入的图片数量。

不要为了缩小文件而过度压缩,导致文字无法识别。

部分平台可能使用其他状态码表示大小限制,仍应查看错误详情。

返回 401 或 403

检查 API Key、模型权限和账户状态。

如果同一个 Key 能调用文本接口,但图片调用失败,还需要确认当前模型和多模态功能是否对该账户开放。

图片 URL 无法读取

检查链接是否公开可访问,是否过期,以及是否存在鉴权或防盗链限制。

如果平台允许,可以改用 Base64 Data URL 测试,判断问题是否来自图片下载环节。

请求超时

图片大小、数量和任务复杂度都可能影响响应时间。

可以先减少图片数量、缩短问题,检查服务状态,再根据业务要求调整读取超时。

更多报错排查方法可以查看:


Gemini 图片识别怎么控制成本

图片调用的计费方式可能与模型、分辨率、图片数量和输出长度有关,不能简单按“每张图片固定多少钱”理解。

建议从以下几个方面优化。

只传需要分析的区域

如果任务只是识别截图中的报错框,可以先裁剪相关区域,减少无关内容。

裁剪时保留必要上下文,避免影响判断。

保持足够清晰,不盲目追求大图

文字识别需要清晰度,但并非所有任务都需要原始高分辨率图片。

可以用真实样例比较不同尺寸的效果与费用,再确定上传规格。

避免重复分析同一张图片

对于输入图片、问题和模型配置完全相同的任务,可以考虑缓存结果。

缓存设计需要结合数据权限和业务时效要求,避免不同用户误用结果。

限制输出范围

如果只需要提取订单号,就明确要求返回订单号及识别状态,避免同时生成大段图片描述。

实际价格与用量规则可以查看:


常见问题

Gemini API 国内能识别图片吗?

可以通过支持图片输入的服务接入。

使用中转接口时,需要确认平台的模型支持、输入格式和访问条件,并在实际部署环境中测试。

Gemini 图片识别可以替代 OCR 吗?

部分图片文字提取任务可以使用多模态模型完成。

对于大量文档、严格字段识别或需要坐标信息的场景,建议与专业 OCR 方案对比,也可以将 OCR 提取和模型理解组合使用。

能不能一次发送多张图片?

如果模型和平台支持,可以按文档格式传入多张图片。

需要确认数量与大小限制,并在提示词中明确每张图片的任务或比较关系。

Gemini API 可以分析 PDF 吗?

PDF 文件输入与图片输入不是同一种调用方式。

需要确认平台是否支持原生文件输入。若将 PDF 页面转成图片,还要考虑页数、清晰度、请求大小和费用。

识别出来的金额和编号可以直接使用吗?

建议先校验。

金额、编号和日期容易受到图片质量影响。重要业务可以增加格式检查、来源对照或人工确认流程。


开始接入 Gemini 图片识别

完成第一次 Gemini API 图片调用,可以按以下顺序操作:

  1. 确认平台支持图片输入与所需格式。
  2. 选择可用的 Gemini 多模态模型。
  3. 配置 API Key 和完整请求地址。
  4. 用单张清晰图片运行最小示例。
  5. 根据业务调整问题与输出格式。
  6. 增加上传限制、结果校验和用量记录。

对于商品分析、截图问答和图片文字提取等功能,Gemini 图片理解可以作为应用中的一个能力模块。接入后,应使用真实业务图片验证识别效果。

大模型 API 中转服务入口:

https://quanzil.com

https://quanzil.net