Gemini API 多模态调用教程

Gemini API 多模态调用完整教程

Google Gemini API 是目前最强大的多模态 AI 模型之一，能够同时处理文本、图片、音频和视频等多种输入格式。本教程将详细介绍如何使用 Gemini API 处理图片和文本，帮助开发者快速上手多模态应用开发。

什么是 Gemini API 多模态能力

Gemini API 的多模态能力允许开发者在单次请求中同时发送文本和图片，模型会理解图片内容并结合文本提示给出智能回复。这种能力特别适合图片分析、OCR 识别、视觉问答、内容审核等场景。

与传统的单模态 API 相比，Gemini 的多模态调用具有以下优势：

• 原生支持图片理解，无需额外的图像识别服务
• 上下文关联能力强，能够理解图片与文本之间的关系
• 支持多张图片同时输入，适合对比分析场景
• 响应速度快，单次 API 调用即可完成复杂任务

准备工作：获取 API Key

在开始使用 Gemini API 多模态调用之前，你需要先获取 API 密钥：

1. 访问 Google AI Studio
2. 使用 Google 账号登录
3. 点击「Get API Key」按钮
4. 创建新项目或选择现有项目
5. 复制生成的 API Key 并妥善保存

注意：如果你所在地区无法直接访问 Google AI Studio，可以考虑使用 API 中转服务来解决网络访问问题。

Python 实现 Gemini API 多模态调用

安装依赖库

首先安装 Google 官方的 Python SDK：

pip install google-generativeai pillow

基础图片分析示例

以下代码展示了如何使用 Gemini API 处理图片和文本的基本流程：

import google.generativeai as genai
from PIL import Image

# 配置 API Key
genai.configure(api_key="YOUR_API_KEY")

# 初始化模型
model = genai.GenerativeModel('gemini-2.0-flash-exp')

# 加载图片
image = Image.open('example.jpg')

# 发送多模态请求
response = model.generate_content([
    "请详细描述这张图片的内容，包括主要物体、颜色、场景等信息。",
    image
])

print(response.text)

处理多张图片

Gemini API 支持在单次请求中处理多张图片，这对于图片对比、系列分析非常有用：

import google.generativeai as genai
from PIL import Image

genai.configure(api_key="YOUR_API_KEY")
model = genai.GenerativeModel('gemini-2.0-flash-exp')

# 加载多张图片
image1 = Image.open('photo1.jpg')
image2 = Image.open('photo2.jpg')

# 多图片对比分析
response = model.generate_content([
    "比较这两张图片的异同点，重点关注构图、色调和主题。",
    image1,
    image2
])

print(response.text)

使用 Base64 编码传输图片

如果图片来自网络或内存，可以使用 Base64 编码方式：

import google.generativeai as genai
import base64
import requests
from io import BytesIO

genai.configure(api_key="YOUR_API_KEY")
model = genai.GenerativeModel('gemini-2.0-flash-exp')

# 从 URL 获取图片
image_url = "https://xiaomuai.cn"
response = requests.get(image_url)
image_data = base64.b64encode(response.content).decode('utf-8')

# 构建多模态请求
response = model.generate_content([
    "识别图片中的文字内容",
    {"mime_type": "image/jpeg", "data": image_data}
])

print(response.text)

Node.js 实现 Gemini API 多模态调用

安装依赖

npm install @google/generative-ai

基础实现代码

const { GoogleGenerativeAI } = require("@google/generative-ai");
const fs = require("fs");

// 初始化 API
const genAI = new GoogleGenerativeAI("YOUR_API_KEY");
const model = genAI.getGenerativeModel({ model: "gemini-2.0-flash-exp" });

async function analyzeImage() {
  // 读取图片文件
  const imageData = fs.readFileSync("example.jpg");
  const base64Image = imageData.toString('base64');

  // 构建请求
  const result = await model.generateContent([
    "请分析这张图片中的主要元素和场景",
    {
      inlineData: {
        mimeType: "image/jpeg",
        data: base64Image
      }
    }
  ]);

  console.log(result.response.text());
}

analyzeImage();

流式响应处理

对于长文本响应，可以使用流式输出提升用户体验：

async function streamAnalysis() {
  const imageData = fs.readFileSync("example.jpg");
  const base64Image = imageData.toString('base64');

  const result = await model.generateContentStream([
    "详细分析这张图片的构图、光线和情感表达",
    {
      inlineData: {
        mimeType: "image/jpeg",
        data: base64Image
      }
    }
  ]);

  for await (const chunk of result.stream) {
    process.stdout.write(chunk.text());
  }
}

实用场景与最佳实践

场景一：OCR 文字识别

Gemini API 多模态调用在 OCR 场景表现出色，无需额外的文字识别服务：

response = model.generate_content([
    "提取图片中的所有文字内容，保持原有格式和排版",
    image
])

场景二：商品图片分析

电商场景中可以自动生成商品描述：

response = model.generate_content([
    "这是一张商品图片，请生成详细的商品描述，包括：1. 商品类型 2. 主要特征 3. 颜色材质 4. 适用场景",
    product_image
])

场景三：内容审核

自动检测图片内容是否符合平台规范：

response = model.generate_content([
    "分析这张图片是否包含不适宜内容，包括暴力、色情、违法信息等，给出是/否的判断和理由",
    user_upload_image
])

最佳实践建议

• 图片大小优化：建议将图片压缩到 4MB 以下，既能保证识别效果又能提升响应速度
• 提示词设计：明确具体的分析需求，避免模糊的提示词如"分析这张图"
• 错误处理：添加完善的异常捕获机制，处理网络超时、API 限流等情况
• 批量处理：对于大量图片，建议使用异步队列避免 API 限流
• 成本控制：合理使用缓存机制，避免重复分析相同图片

常见问题与解决方案

API 限流问题

Gemini API 有请求频率限制，免费版每分钟 15 次请求。如果遇到 429 错误，可以：

• 添加重试机制，使用指数退避策略
• 升级到付费版本获得更高配额
• 使用请求队列控制并发数

图片格式支持

Gemini API 支持常见图片格式：JPEG、PNG、WebP、HEIC、HEIF。如果遇到不支持的格式，建议先转换为 JPEG：

from PIL import Image

img = Image.open('input.bmp')
img = img.convert('RGB')
img.save('output.jpg', 'JPEG')

网络访问问题

部分地区可能无法直接访问 Google API。除了使用代理外，也可以考虑使用专业的 API 中转服务，这些服务通常提供国内可访问的接口地址，同时保持与官方 API 完全兼容的调用方式，对于生产环境部署更加稳定可靠。

性能优化技巧

图片预处理

在发送请求前对图片进行适当处理可以提升效果：

from PIL import Image

def optimize_image(image_path, max_size=1024):
    img = Image.open(image_path)
    
    # 调整尺寸
    if max(img.size) > max_size:
        img.thumbnail((max_size, max_size), Image.Resampling.LANCZOS)
    
    # 转换为 RGB
    if img.mode != 'RGB':
        img = img.convert('RGB')
    
    return img

并发请求处理

使用异步编程提升批量处理效率：

import asyncio
import google.generativeai as genai

async def analyze_images_batch(image_paths):
    model = genai.GenerativeModel('gemini-2.0-flash-exp')
    
    tasks = []
    for path in image_paths:
        image = Image.open(path)
        task = model.generate_content_async([
            "简要描述图片内容",
            image
        ])
        tasks.append(task)
    
    results = await asyncio.gather(*tasks)
    return [r.text for r in results]

# 使用示例
image_list = ['img1.jpg', 'img2.jpg', 'img3.jpg']
results = asyncio.run(analyze_images_batch(image_list))

总结

Gemini API 的多模态调用能力为开发者提供了强大而灵活的图文处理方案。通过本教程的学习，你已经掌握了：

• Gemini API 多模态调用的基本原理和使用方法
• Python 和 Node.js 两种语言的完整实现代码
• 多种实用场景的应用示例
• 性能优化和问题排查技巧

在实际项目中，建议根据具体需求选择合适的模型版本（Flash 或 Pro），并做好错误处理和成本控制。随着 Gemini 模型的持续迭代，其多模态能力还将不断增强，值得开发者持续关注。

常见问题 FAQ