Google Gemini API 使用手册

一、概述

Google Gemini API 提供 Gemini 系列模型的访问，支持文本生成、多模态理解、代码执行、搜索增强、图像/视频/音乐生成等能力。以超长上下文（1M tokens）和丰富的多模态生态著称。

二、认证

API Key 方式（简单）

import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY")

API Key 在 Google AI Studio 创建。

服务账号方式（生产环境）

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

三、Base URL

REST API: https://generativelanguage.googleapis.com/v1beta
OpenAI兼容: https://generativelanguage.googleapis.com/v1beta/openai

四、模型列表

五、文本生成

import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY")
model = genai.GenerativeModel('gemini-3-pro')

# 单次生成
response = model.generate_content(
    "解释量子计算的原理",
    generation_config=genai.types.GenerationConfig(
        temperature=0.7,
        top_p=0.95,
        top_k=40,
        max_output_tokens=2048,
        candidate_count=1
    )
)
print(response.text)

参数说明

六、多轮对话

chat = model.start_chat(history=[])

response1 = chat.send_message("我想学习Python")
response2 = chat.send_message("推荐一些入门项目")

# 查看历史
for msg in chat.history:
    print(f"{msg.role}: {msg.parts[0].text}")

七、系统指令

model = genai.GenerativeModel(
    'gemini-3-pro',
    system_instruction=[
        "你是一位专业的Python讲师。",
        "回答使用Markdown格式，包含代码示例。",
        "语气友好且专业。"
    ]
)

八、多模态输入

图像

import PIL.Image

img = PIL.Image.open('photo.jpg')
response = model.generate_content(["描述这张图片", img])

多图

img1 = PIL.Image.open('img1.jpg')
img2 = PIL.Image.open('img2.jpg')
response = model.generate_content([
    "比较这两张图片的异同",
    img1, img2
])

视频

# 上传视频文件
video = genai.upload_file("video.mp4")

# 等待处理完成
while video.state.name == "PROCESSING":
    time.sleep(5)
    video = genai.get_file(video.name)

response = model.generate_content([
    "总结这个视频的内容",
    video
])

音频

audio = genai.upload_file("speech.mp3")
response = model.generate_content([
    "转录这段音频",
    audio
])

九、搜索增强（Grounding）

response = model.generate_content(
    "2026年最新的AI新闻",
    tools="google_search_retrieval"
)
# 回答中包含搜索来源引用

十、代码执行

response = model.generate_content(
    "计算斐波那契数列前100项的和",
    tools="code_execution"
)
# 模型自动编写并执行Python代码

十一、图像生成（多模态输出）

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro",
    contents="生成一张日落风景画",
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"]
    )
)

十二、文件上传与RAG

# 上传文件
file = genai.upload_file("document.pdf",
    mime_type="application/pdf"
)

# 缓存大文件（减少重复上传费用）
cache = genai.caching.CachedContent.create(
    model="gemini-3-pro",
    contents=[file],
    ttl=datetime.timedelta(hours=2)
)

model = genai.GenerativeModel.from_cached_content(cache)
response = model.generate_content("总结文档要点")

十三、流式输出

response = model.generate_content("写一首诗", stream=True)
for chunk in response:
    print(chunk.text, end="")

十四、定价

免费额度：15 RPM, 1M TPM, 1500 RPD（Flash模型）

十五、错误码