Gemini API 图片识别教程：通过中转站提取商品参数与 JSON

商品资料整理最耗时间的环节之一，是把图片里的信息重新录入系统。

供应商发来的包装照片、产品铭牌和详情页截图，往往包含商品名称、型号、功率、容量等参数。人工逐张查看、复制和填写，不仅重复，还容易遗漏单位或混淆不同型号。

Gemini API 可以用于这类图片信息提取任务：程序提交图片和字段要求，模型读取图片内容，再返回供程序处理的结果。

本文以 Gemini 3.8 Flash 为例，介绍如何通过 KoalaAPI 这类 API 中转站，用 Python 完成一次商品参数提取，并检查返回的 JSON 是否符合要求。

完成后，你会得到一个可以继续扩展到商品资料整理、内部录入工具和自动化工作流的基础脚本。

一、Gemini API 图片识别适合解决什么问题？

先明确任务：我们希望从图片中提取已经存在的信息。

例如，一张电热水壶的包装图片可能包含：

• 商品名称；
• 产品型号；
• 额定功率；
• 额定容量。

程序需要把这些内容整理成固定字段，方便后续导入表格或商品管理系统。

Google 的 Gemini 3.8 Flash 模型说明列出了图片输入和文本输出能力，并支持结构化输出。这意味着它可以作为图片理解与信息提取任务的候选模型。具体效果仍需要用自己的图片验证。

以下场景比较适合从小样本开始尝试：

其中有一个重要要求：看不清、没出现的信息，应当保留为空。

例如，图片没有显示容量，就不能根据商品外观猜测“1.5L”；图片中的型号模糊，也不能补成一个看起来合理的型号。

这条规则应该写进提示词，也应该体现在后续验收中。

二、官方 Gemini API Key 与中转站 Key 怎么区分？

搜索 Gemini API Key 时，容易把两种接入方式混在一起。

如果直接调用 Google 的接口，需要使用对应的 Google 凭证与官方地址。

如果通过 KoalaAPI 调用，则需要使用 KoalaAPI 创建的密钥，并把请求发送到它提供的接口地址。

密钥、接口地址和模型权限必须对应。

本文采用 KoalaAPI 的 OpenAI 兼容接入方式，其公开示例使用的 API Base URL 为：

https://koalaapi.com/v1

这里填写的是 SDK 的基础地址，不需要在后面再拼接 /chat/completions，SDK 会根据调用方法构造请求路径。KoalaAPI 的图片理解文档使用的完整接口路径是 /v1/chat/completions。

开始前，准备好这三项：

截至本文核对时，KoalaAPI 的公开模型列表包含 gemini-3.8-flash。实际调用前，还需要确认自己的令牌分组和权限是否支持该模型及图片输入。

可以先打开 KoalaAPI 模型广场，核对模型名称和当前计费信息，再准备测试。

三、先规定输出字段，避免模型自由发挥

图片识别任务中，提示词如果只有“帮我看看这张图”，模型通常会返回一段介绍。

这对人工阅读有帮助，但不方便程序直接处理。

更适合业务接入的方式，是事先规定字段、类型和缺失值处理方式。

本文使用以下结构：

{
  "product_name": "商品名称或 null",
  "model_number": "型号或 null",
  "power": "功率及原始单位，或 null",
  "capacity": "容量及原始单位，或 null",
  "uncertain_fields": []
}

这里把功率和容量保留为字符串，是为了保留图片上的原始单位。

例如，图片写的是 1500W，先提取为 "1500W"。后续如果业务系统需要拆成数值和单位，再由程序按照明确规则处理。

不要在第一步同时要求模型识别、换算、补全和生成营销文案。任务越混杂，越难判断错误发生在哪个环节。

对于缺失或模糊的字段，返回 null，并把字段名放入 uncertain_fields，方便人工复核。

四、配置 Python 环境与 API Key

准备一张清晰的商品参数图片，例如 product.png。建议第一张图片只包含一个商品，文字方向正常，型号和规格完整可见。

安装 Python 客户端：

python -m pip install openai

然后设置环境变量。

Windows PowerShell 示例：

$env:KOALA_API_KEY="替换成你的KoalaAPI密钥"
$env:GEMINI_MODEL="gemini-3.8-flash"

macOS 或 Linux 示例：

export KOALA_API_KEY="替换成你的KoalaAPI密钥"
export GEMINI_MODEL="gemini-3.8-flash"

上述命令中的模型名称，需要与你账户实际支持的标识一致。

示例环境变量只影响当前终端及其启动的程序。如果你通过 IDE、容器或服务管理器运行脚本，还需要在相应运行环境中配置变量。

正式项目应通过部署环境或密钥管理服务保存凭证，不要把真实 Key 写入公开代码、网页前端或共享截图。

五、完整示例：上传商品图片并校验 JSON

下面的脚本完成四件事：

1. 读取一张本地图片；
2. 将图片编码后提交给兼容接口；
3. 要求模型提取指定商品字段；
4. 检查 JSON 的字段和数据类型。

Google 的兼容接口文档提供了使用 image_url 传入 Base64 图片的方式。下面沿用这一请求结构，通过 KoalaAPI 的兼容地址发送；所选模型通道需要支持这种图片输入格式。

将代码保存为 extract_product.py：

import base64
import json
import os
import sys
from pathlib import Path

from openai import OpenAI


FIELDS = (
    "product_name",
    "model_number",
    "power",
    "capacity",
)

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


def validate_result(data):
    expected_keys = set(FIELDS) | {"uncertain_fields"}

    if not isinstance(data, dict):
        raise ValueError("返回内容必须是 JSON 对象")

    if set(data) != expected_keys:
        raise ValueError("返回字段与预期不一致")

    for field in FIELDS:
        value = data[field]
        if value is not None and not isinstance(value, str):
            raise ValueError(f"{field} 必须是字符串或 null")

    uncertain = data["uncertain_fields"]

    if not isinstance(uncertain, list):
        raise ValueError("uncertain_fields 必须是数组")

    if any(
        not isinstance(item, str) or item not in FIELDS
        for item in uncertain
    ):
        raise ValueError("uncertain_fields 包含无效字段名")

    return data


def main():
    if len(sys.argv) != 2:
        raise SystemExit(
            "用法：python extract_product.py product.png"
        )

    image_path = Path(sys.argv[1])
    mime_type = MIME_TYPES.get(image_path.suffix.lower())

    if mime_type is None:
        raise ValueError("本示例支持 PNG、JPEG 和 WebP 图片")

    image_bytes = image_path.read_bytes()
    encoded_image = base64.b64encode(
        image_bytes
    ).decode("ascii")

    client = OpenAI(
        api_key=os.environ["KOALA_API_KEY"],
        base_url="https://koalaapi.com/v1",
        timeout=90.0,
        max_retries=0,
    )

    prompt = """
请提取图片中单个商品的参数，仅依据图片明确显示的内容。

规则：
1. 不根据常识、商品外观或相似型号补全信息。
2. 看不清、未出现或存在冲突的字段返回 null。
3. 功率和容量保留图片中的原始单位。
4. 缺失或不确定的字段名放入 uncertain_fields。
5. 只返回 JSON 对象，不要 Markdown 代码块或解释文字。

必须包含以下字段：
product_name：字符串或 null
model_number：字符串或 null
power：字符串或 null
capacity：字符串或 null
uncertain_fields：字段名字符串数组
"""

    response = client.chat.completions.create(
        model=os.environ["GEMINI_MODEL"],
        messages=[
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": prompt},
                    {
                        "type": "image_url",
                        "image_url": {
                            "url": (
                                f"data:{mime_type};base64,"
                                f"{encoded_image}"
                            )
                        },
                    },
                ],
            }
        ],
        stream=False,
    )

    if not response.choices:
        raise RuntimeError("接口没有返回可解析的结果")

    choice = response.choices[0]

    if choice.finish_reason != "stop":
        raise RuntimeError(
            f"生成未正常完成：{choice.finish_reason}"
        )

    content = choice.message.content

    if not content:
        raise RuntimeError("模型返回内容为空")

    data = validate_result(json.loads(content))

    print(json.dumps(data, ensure_ascii=False, indent=2))


if __name__ == "__main__":
    main()

运行：

python extract_product.py product.png

正常执行时，脚本会发起一次模型请求，可能产生 API 费用。示例关闭了自动重试，方便首次接入时判断具体错误。

下面仅展示返回结构，不是实际图片的识别记录：

{
  "product_name": "电热水壶",
  "model_number": "DEMO-K15",
  "power": "1500W",
  "capacity": null,
  "uncertain_fields": [
    "capacity"
  ]
}

实际结果应以你提交图片中的信息为准。

六、返回了 JSON，为什么还需要校验？

“接口成功返回”“JSON 格式正确”和“商品信息正确”，是三个不同的验收层次。

上面的程序会检查字段是否完整、类型是否正确。如果模型返回解释文字、错误字段或不完整 JSON，脚本会报错，避免把不符合格式的数据当成正常结果使用。

但格式校验无法判断：

• 型号中的 0 是否被识别成字母 O；
• 1500W 是否被看成 150W；
• 参数是否属于图片中的另一个商品；
• 某个字段是否由模型推测得出。

这些都需要通过图片对照和业务规则检查。

建议第一轮准备 20 张左右的代表性样本，包括清晰图片、低清晰度图片、缺少字段的图片，以及包含相似型号的图片。

逐项记录正确值、错误值和空值，观察模型是否能够在信息不足时保留为空。

如果你的模型通道支持 JSON Schema 等结构化输出参数，可以在确认接口文档后进一步启用。但即使服务端约束了输出结构，也仍然需要核对字段内容。

七、从单张图片扩展到批量处理，先补齐哪些环节？

单张图片跑通之后，可以增加文件队列，把相同流程用于多张图片。

批量任务首先需要可追溯性。

每条结果至少关联原始文件名、请求模型、处理时间和任务状态。这样发现错误时，才能回到对应图片复核。

其次，应把失败和成功分开记录。

网络中断、限流、JSON 解析失败和字段待确认，不能都写成“识别失败”。它们需要不同的处理方式：

刚开始不要同时提交大量图片。先用低并发验证一小批样本，确认成本、耗时和结果质量，再逐步增加任务量。

在商品管理系统中，可以先把结果写入“待确认”区域。经过人工核对后，再进入正式商品资料。

八、Gemini API 图片识别成本应该怎么算？

如果你希望判断这个功能是否值得上线，需要统计一次完整任务的费用。

图片识别成本可能受到模型、图片尺寸、处理方式、输出长度和重试次数等因素影响，具体应以实际通道的计费规则和用量记录为准。

更有参考价值的指标是：

每张合格结果的平均 API 成本 = 本轮总调用费用 ÷ 验收合格的图片数量。

同时记录人工复核和修正所花费的时间。

例如，一个通道虽然单次请求更便宜，但经常识别错型号，需要反复重试和人工修改，最终未必更适合业务。

降低无效消耗，可以从以下几处入手：

• 保留需要识别的参数区域，减少无关画面；
• 保证文字清晰，避免过度压缩；
• 只提取必要字段，减少无关解释；
• 对已经成功处理的相同图片避免重复调用；
• 对失败任务设置重试上限。

选择 API 中转站时，也应同时查看模型权限、图片输入支持、计费说明和调用记录，而不只比较宣传中的单价。

九、为什么这个场景适合接入 API 中转站？

如果项目只使用一种模型，直接接入对应官方 API 也是一种选择。

当你需要对比多个图像理解模型，或者已有应用采用 OpenAI 兼容请求结构时，中转服务可以提供一个相对集中的接入入口。

在本文场景中，KoalaAPI 承担的是模型 API 接入层：

你的程序负责读取图片、发起请求和校验结果；所选 Gemini 模型负责理解图片；中转接口负责接收并转发相应请求。

后续如果需要比较其他支持图片理解的模型，可以保留同一批测试图片和验收规则，重新核对模型 ID、接口参数与权限，再进行测试。

这样得到的比较更贴近自己的业务。

需要强调的是，API 中转站不会消除图片模糊、文字歧义或模型识别错误。最终是否适合上线，仍应以具体任务的结果为依据。

十、常见问题

Gemini API 可以直接识别本地图片吗？

程序需要读取本地图片，并按照接口支持的方式上传图片内容。

仅把 C:\images\product.png 这样的本地路径写进提示词，远端模型无法读取你的电脑文件。

为什么文本调用成功，图片调用却失败？

需要检查模型是否支持图片输入、令牌所在分组是否开放相应能力，以及图片格式、请求体大小和传输方式是否符合通道要求。

可以先用一张较小的清晰图片排查，具体请求结构可参考 KoalaAPI 图片理解文档。

Gemini API 免费额度可以用于中转站吗？

官方服务与中转服务的账户、额度和计费需要分别核对。不能把官方免费额度直接视为 KoalaAPI 账户的可用余额。

测试前先确认所用平台的当前规则。

能不能直接把识别结果写进商品数据库？

技术上可以增加数据库写入步骤，但建议先完成格式校验、关键字段核验和重复记录检查。

型号、功率等重要字段存在疑问时，应进入人工复核流程。

这个示例能扩展成 AI Agent 工具吗？

可以把图片提取封装成一个受控函数，让 Agent 在需要整理商品资料时调用。

图片提取、结果复核和正式入库最好保留清晰的边界，便于检查错误和控制操作范围。

从一张图片开始，把 Gemini API 用进实际业务

如果你正在做商品资料录入、供应商图片整理或内部自动化工具，可以先选一张参数清晰的图片，验证模型能否准确提取所需字段。

注册 KoalaAPI 并创建 API Key，确认账户支持的 Gemini 图片理解模型，然后按本文示例完成首次调用。

先获得一条能解析、能核对、能进入后续流程的结果，再扩展到批量任务。这样才能把大模型 API 接入，逐步变成实际可用的业务功能。