Google Gemini API 详解

Gemini API 是 Google 推出的多模态大模型接口，支持 Gemini 2.0、1.5 系列模型。该 API 原生支持文本、图像、音频、视频等多种输入格式。

Gemini 的独特优势

Gemini 的核心竞争力：

1. 超长上下文（2M tokens）

Gemini 1.5 Pro 支持高达 200 万 tokens 的上下文窗口，这是目前主流模型中最大的。这意味着你可以：

• 一次性处理整本书（约 150 万字）
• 分析数小时的视频内容
• 处理大型代码库（数十万行代码）
• 无需分块处理长文档

2. 原生多模态

与 GPT-4o 和 Claude 不同，Gemini 从架构层面就是多模态的，可以直接处理：

• 图像（PNG、JPEG、GIF、WebP）
• 视频（MP4、MOV 等，最长数小时）
• 音频（MP3、WAV 等）
• PDF 文档

3. 内置代码执行

Gemini 可以在安全沙箱中执行生成的代码，无需额外配置。这对于数据分析、数学计算等场景非常有用。

4. 成本优势

Gemini Flash 系列提供了极具竞争力的价格，免费层也相当慷慨，适合预算有限的项目。

与 OpenAI 的主要差异速览

端点与认证

端点

Gemini 使用 RPC 风格的端点命名，动作直接体现在 URL 中：

POST https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent
POST https://generativelanguage.googleapis.com/v1beta/models/{model}:streamGenerateContent
POST https://generativelanguage.googleapis.com/v1beta/models/{model}:countTokens

端点说明：

注意： 流式和非流式使用不同的端点，这与 OpenAI/Claude 的设计不同。

认证

API Key 方式（简单场景）

?key=$GOOGLE_API_KEY

这是最简单的认证方式，适合个人项目和快速原型。API Key 直接附加在 URL 参数中。

OAuth 2.0（企业场景）

Authorization: Bearer $ACCESS_TOKEN

对于生产环境，建议使用 OAuth 2.0 或 Service Account 认证，与 Google Cloud IAM 集成，提供更细粒度的权限控制。

请求参数

必需参数

contents 结构说明：

Gemini 的消息结构比 OpenAI 多一层嵌套：contents → parts。这种设计使得一条消息可以包含多种类型的内容（文本、图像、视频等）。

可选参数

generationConfig 参数

生成相关的参数都放在 generationConfig 对象中，与内容分离：

参数命名注意：

Gemini 使用 camelCase（如 maxOutputTokens），而 OpenAI 使用 snake_case（如 max_tokens）。在格式转换时需要注意。

消息格式

角色类型

注意：Gemini 使用 model 而非 assistant，这是与 OpenAI/Claude 的重要差异。

基础请求

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {"text": "Hello, Gemini!"}
      ]
    }
  ]
}

parts 数组的设计：

每条消息的内容放在 parts 数组中，每个 part 可以是不同类型：

• {"text": "..."} - 文本
• {"inlineData": {...}} - 图像/音频/视频
• {"fileData": {...}} - 文件引用

带系统指令

{
  "systemInstruction": {
    "parts": [
      {"text": "You are a helpful assistant."}
    ]
  },
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "Hello!"}]
    }
  ]
}

systemInstruction 是顶级参数，结构与 contents 中的消息类似，也使用 parts 数组。

多轮对话

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "What is 2+2?"}]
    },
    {
      "role": "model",
      "parts": [{"text": "2+2 equals 4."}]
    },
    {
      "role": "user",
      "parts": [{"text": "Multiply that by 3"}]
    }
  ]
}

多模态输入

Gemini 的多模态能力是其最大的差异化优势。它可以原生处理图像、视频、音频和 PDF，无需预处理或外部工具。

支持的媒体类型

图像（Base64）

适合小图像或需要直接嵌入请求的场景：

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "/9j/4AAQSkZJRg..."
          }
        },
        {"text": "What's in this image?"}
      ]
    }
  ]
}

图像（URL / Google Cloud Storage）

适合大文件或已存储在云端的文件：

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "fileData": {
            "mimeType": "image/jpeg",
            "fileUri": "gs://bucket/image.jpg"
          }
        },
        {"text": "Describe this image"}
      ]
    }
  ]
}

fileUri 支持的协议：

• gs:// - Google Cloud Storage
• https:// - 公开可访问的 URL

视频

Gemini 是目前唯一原生支持视频输入的主流模型。它可以理解视频内容、提取关键帧、分析动作和场景。

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "fileData": {
            "mimeType": "video/mp4",
            "fileUri": "gs://bucket/video.mp4"
          }
        },
        {"text": "Summarize this video"}
      ]
    }
  ]
}

视频处理能力：

• 内容理解和总结
• 关键时刻提取
• 动作识别
• 字幕生成
• 视频问答

注意事项：

• 长视频会消耗大量 Token
• 建议先用 countTokens 估算成本
• 可以指定时间范围减少处理量

音频

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "inlineData": {
            "mimeType": "audio/mp3",
            "data": "base64_encoded_audio..."
          }
        },
        {"text": "Transcribe this audio"}
      ]
    }
  ]
}

音频处理能力：

• 语音转文字（多语言）
• 音频内容理解
• 说话人识别
• 情感分析

PDF 文档

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "inlineData": {
            "mimeType": "application/pdf",
            "data": "base64_encoded_pdf..."
          }
        },
        {"text": "Summarize this document"}
      ]
    }
  ]
}

PDF 处理特点：

• 保留文档布局信息
• 理解表格和图表
• 支持扫描件（OCR）
• 可以处理多页文档

多模态组合

一条消息可以包含多种类型的内容：

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {"text": "Compare these two images:"},
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "image1_base64..."
          }
        },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "image2_base64..."
          }
        },
        {"text": "Which one is better for a website banner?"}
      ]
    }
  ]
}

响应格式

标准响应

{
  "candidates": [
    {
      "content": {
        "parts": [
          {"text": "Hello! How can I help you today?"}
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 10,
    "candidatesTokenCount": 8,
    "totalTokenCount": 18
  },
  "modelVersion": "gemini-1.5-flash"
}

finishReason 值

流式传输

请求

使用 streamGenerateContent 端点：

POST https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:streamGenerateContent?key=$API_KEY

响应格式

{"candidates":[{"content":{"parts":[{"text":"Hello"}],"role":"model"}}]}
{"candidates":[{"content":{"parts":[{"text":"!"}],"role":"model"}}]}
{"candidates":[{"content":{"parts":[{"text":" How"}],"role":"model"}}]}
{"candidates":[{"content":{"parts":[{"text":" can I help?"}],"role":"model"},"finishReason":"STOP"}],"usageMetadata":{"promptTokenCount":5,"candidatesTokenCount":10,"totalTokenCount":15}}

Function Calling

定义函数

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "What's the weather in Tokyo?"}]
    }
  ],
  "tools": [
    {
      "functionDeclarations": [
        {
          "name": "get_weather",
          "description": "Get the current weather for a location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "City name"
              },
              "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"]
              }
            },
            "required": ["location"]
          }
        }
      ]
    }
  ]
}

函数调用响应

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "get_weather",
              "args": {
                "location": "Tokyo",
                "unit": "celsius"
              }
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP"
    }
  ]
}

返回函数结果

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "What's the weather in Tokyo?"}]
    },
    {
      "role": "model",
      "parts": [
        {
          "functionCall": {
            "name": "get_weather",
            "args": {"location": "Tokyo"}
          }
        }
      ]
    },
    {
      "role": "user",
      "parts": [
        {
          "functionResponse": {
            "name": "get_weather",
            "response": {
              "temperature": 22,
              "condition": "sunny"
            }
          }
        }
      ]
    }
  ]
}

JSON Mode

启用 JSON 输出

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "List 3 colors with hex codes"}]
    }
  ],
  "generationConfig": {
    "responseMimeType": "application/json"
  }
}

结构化输出（JSON Schema）

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "List 3 colors"}]
    }
  ],
  "generationConfig": {
    "responseMimeType": "application/json",
    "responseSchema": {
      "type": "object",
      "properties": {
        "colors": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {"type": "string"},
              "hex": {"type": "string"}
            },
            "required": ["name", "hex"]
          }
        }
      },
      "required": ["colors"]
    }
  }
}

Code Execution

Gemini 支持内置代码执行：

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "Calculate the first 10 prime numbers"}]
    }
  ],
  "tools": [
    {"codeExecution": {}}
  ]
}

安全设置

{
  "contents": [...],
  "safetySettings": [
    {
      "category": "HARM_CATEGORY_HARASSMENT",
      "threshold": "BLOCK_MEDIUM_AND_ABOVE"
    },
    {
      "category": "HARM_CATEGORY_HATE_SPEECH",
      "threshold": "BLOCK_ONLY_HIGH"
    }
  ]
}

安全类别

• HARM_CATEGORY_HARASSMENT
• HARM_CATEGORY_HATE_SPEECH
• HARM_CATEGORY_SEXUALLY_EXPLICIT
• HARM_CATEGORY_DANGEROUS_CONTENT

阈值级别

• BLOCK_NONE
• BLOCK_ONLY_HIGH
• BLOCK_MEDIUM_AND_ABOVE
• BLOCK_LOW_AND_ABOVE

完整示例

cURL

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key=$GOOGLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "Hello, Gemini!"}]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 1000
    }
  }'

Python

import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY")

model = genai.GenerativeModel("gemini-1.5-flash")

response = model.generate_content("Hello, Gemini!")
print(response.text)

Python 多轮对话

import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY")

model = genai.GenerativeModel("gemini-1.5-flash")
chat = model.start_chat()

response1 = chat.send_message("My name is Alice")
print(response1.text)

response2 = chat.send_message("What's my name?")
print(response2.text)

Python 流式

import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY")

model = genai.GenerativeModel("gemini-1.5-flash")

response = model.generate_content("Write a poem", stream=True)

for chunk in response:
    print(chunk.text, end="")

Python 多模态

import google.generativeai as genai
from PIL import Image

genai.configure(api_key="YOUR_API_KEY")

model = genai.GenerativeModel("gemini-1.5-flash")

image = Image.open("image.jpg")
response = model.generate_content(["Describe this image", image])
print(response.text)

Node.js

import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI("YOUR_API_KEY");
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });

const result = await model.generateContent("Hello, Gemini!");
console.log(result.response.text());

Go

import "github.com/google/generative-ai-go/genai"

client, _ := genai.NewClient(ctx, option.WithAPIKey("YOUR_API_KEY"))
model := client.GenerativeModel("gemini-1.5-flash")

resp, _ := model.GenerateContent(ctx, genai.Text("Hello, Gemini!"))
fmt.Println(resp.Candidates[0].Content.Parts[0])

模型列表

模型持续更新，请查阅 Google AI Models 获取最新列表。

模型选择建议

超长文档处理 → gemini-1.5-pro (2M context)
视频/音频分析 → gemini-1.5-pro
快速响应 → gemini-1.5-flash
成本优先 → gemini-1.5-flash-8b
免费使用 → 任意模型（有免费额度）

最佳实践

1. 处理超长文档

# Gemini 1.5 Pro 支持 2M tokens，适合处理整本书
with open("book.pdf", "rb") as f:
    pdf_data = base64.b64encode(f.read()).decode()

response = model.generate_content([
    {"inline_data": {"mime_type": "application/pdf", "data": pdf_data}},
    "请总结这本书的核心观点"
])

2. 视频分析

# 上传视频到 Google Cloud Storage 后分析
response = model.generate_content([
    {"file_data": {"mime_type": "video/mp4", "file_uri": "gs://bucket/video.mp4"}},
    "描述视频中发生了什么"
])

3. 使用免费额度

• 免费层每分钟 15 次请求
• 适合开发测试和个人项目
• 生产环境建议升级付费计划

4. 错误处理

from google.api_core import exceptions

try:
    response = model.generate_content(prompt)
except exceptions.ResourceExhausted:
    print("配额用尽，请稍后重试")
except exceptions.InvalidArgument as e:
    print(f"参数错误: {e}")

与 OpenAI 的主要差异

相关指南

• 12-多模态输入处理
• 09-错误处理与重试
• 06-传输协议对比

官方文档

• API Overview: https://ai.google.dev/api
• Generate Content: https://ai.google.dev/api/generate-content
• Python SDK: https://github.com/google/generative-ai-python
• Node.js SDK: https://github.com/google/generative-ai-js
• Function Calling: https://ai.google.dev/gemini-api/docs/function-calling
• Vision: https://ai.google.dev/gemini-api/docs/vision