gemini-api

Gemini API

使用 Google 的 Gemini API 根据文本、图像、视频和音频生成文本。

模型

模型	代码	输入/输出	上下文	思考
Gemini 3 Pro	gemini-3-pro-preview	文本/图像/视频/音频/PDF -> 文本	1M/64K	是
Gemini 3 Flash	gemini-3-flash-preview	文本/图像/视频/音频/PDF -> 文本	1M/64K	是
Gemini 2.5 Pro	gemini-2.5-pro	文本/图像/视频/音频/PDF -> 文本	1M/65K	是
Gemini 2.5 Flash	gemini-2.5-flash	文本/图像/视频/音频 -> 文本	1M/65K	是
Nano Banana	gemini-2.5-flash-image	文本/图像 -> 图像	-	否
Nano Banana Pro	gemini-3-pro-image-preview	文本/图像 -> 图像（最高 4K）	65K/32K	是
Veo 3.1	veo-3.1-generate-preview	文本/图像/视频 -> 视频+音频	-	-
Veo 3	veo-3-generate-preview	文本/图像 -> 视频+音频	-	-
Veo 2	veo-2.0-generate-001	文本/图像 -> 视频（静音）	-	-
Lyria RealTime	lyria-realtime-exp	文本 -> 音乐（流式）	-	-
嵌入	gemini-embedding-001	文本 -> 嵌入	2K	否

免费层级：仅限 Flash 模型（API 中的 gemini-3-pro-preview 没有免费层级）。默认温度：1.0（Gemini 3 请勿更改）。

定价（每 1M 个令牌）：

• Gemini 3 Pro：$2/$12（<200k），$4/$18（>200k）
• Gemini 3 Flash：$0.50/$3
• Nano Banana Pro：$2（文本）/ $0.134（图像）

---

基本文本生成

Python

from google import genai

client = genai.Client()
response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents="How does AI work?"
)
print(response.text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});
const response = await ai.models.generateContent({
  model: "gemini-3-flash-preview",
  contents: "How does AI work?",
});
console.log(response.text);

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"contents": [{"parts": [{"text": "How does AI work?"}]}]}'

---

系统指令

response = client.models.generate_content(
    model="gemini-3-flash-preview",
    config=types.GenerateContentConfig(
        system_instruction="You are a helpful assistant."
    ),
    contents="Hello"
)

const response = await ai.models.generateContent({
  model: "gemini-3-flash-preview",
  contents: "Hello",
  config: { systemInstruction: "You are a helpful assistant." },
});

---

流式传输

for chunk in client.models.generate_content_stream(
    model="gemini-3-flash-preview",
    contents="Tell me a story"
):
    print(chunk.text, end="")

const response = await ai.models.generateContentStream({
  model: "gemini-3-flash-preview",
  contents: "Tell me a story",
});
for await (const chunk of response) {
  console.log(chunk.text);
}

---

多轮聊天

chat = client.chats.create(model="gemini-3-flash-preview")
response = chat.send_message("I have 2 dogs.")
print(response.text)
response = chat.send_message("How many paws total?")
print(response.text)

const chat = ai.chats.create({ model: "gemini-3-flash-preview" });
const response = await chat.sendMessage({ message: "I have 2 dogs." });
console.log(response.text);

---

多模态（图像）

from PIL import Image

image = Image.open("/path/to/image.png")
response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents=[image, "Describe this image"]
)

const image = await ai.files.upload({ file: "/path/to/image.png" });
const response = await ai.models.generateContent({
  model: "gemini-3-flash-preview",
  contents: [
    createUserContent([
      "Describe this image",
      createPartFromUri(image.uri, image.mimeType),
    ]),
  ],
});

---

文档处理（PDF）

使用原生视觉理解处理 PDF（最多 1000 页）。

from google.genai import types
import pathlib

filepath = pathlib.Path('document.pdf')
response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents=[
        types.Part.from_bytes(data=filepath.read_bytes(), mime_type='application/pdf'),
        "Summarize this document"
    ]
)

import * as fs from 'fs';

const response = await ai.models.generateContent({
    model: "gemini-3-flash-preview",
    contents: [
        { text: "Summarize this document" },
        {
            inlineData: {
                mimeType: 'application/pdf',
                data: Buffer.from(fs.readFileSync("document.pdf")).toString("base64")
            }
        }
    ]
});

对于大型 PDF，请使用 Files API（存储 48 小时）：

uploaded_file = client.files.upload(file=pathlib.Path('large.pdf'))
response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents=[uploaded_file, "Summarize this document"]
)

有关 Files API、多个 PDF 和最佳实践，请参阅 references/documents.md。

---

图像生成（Nano Banana）

以对话方式生成和编辑图像。

response = client.models.generate_content(
    model="gemini-2.5-flash-image",
    contents="Create a picture of a sunset over mountains",
)

for part in response.parts:
    if part.inline_data is not None:
        part.as_image().save("generated.png")

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash-image",
  contents: "Create a picture of a sunset over mountains",
});

for (const part of response.candidates[0].content.parts) {
  if (part.inlineData) {
    const buffer = Buffer.from(part.inlineData.data, "base64");
    fs.writeFileSync("generated.png", buffer);
  }
}

Nano Banana Pro（gemini-3-pro-image-preview）：4K 输出、Google Search grounding、最多 14 张参考图像，以及使用思维签名进行对话式编辑。

有关编辑、多轮交互和高级功能，请参阅 references/image-generation.md。 有关 Gemini 3 的图像功能，请参阅 references/gemini-3.md。

---

视频生成（Veo）

使用 Veo 生成带有原生音频的 8 秒 720p、1080p 或 4K 视频。

import time
from google import genai

client = genai.Client()

operation = client.models.generate_videos(
    model="veo-3.1-generate-preview",
    prompt="A cinematic shot of a majestic lion in the savannah at golden hour",
)

# Poll until complete (video generation is async)
while not operation.done:
    time.sleep(10)
    operation = client.operations.get(operation)

# Download the video
video = operation.response.generated_videos[0]
client.files.download(file=video.video)
video.video.save("lion.mp4")

let operation = await ai.models.generateVideos({
    model: "veo-3.1-generate-preview",
    prompt: "A cinematic shot of a majestic lion in the savannah at golden hour",
});

while (!operation.done) {
    await new Promise(resolve => setTimeout(resolve, 10000));
    operation = await ai.operations.getVideosOperation({ operation });
}

ai.files.download({
    file: operation.response.generatedVideos[0].video,
    downloadPath: "lion.mp4",
});

Veo 3.1 功能：竖屏（9:16）、视频延长（最长 148 秒）、4K 分辨率、带有对白/音效的原生音频。

有关图像转视频、参考图像、视频延长和提示词指南，请参阅 references/veo.md。

---

音乐生成（Lyria RealTime）

实时生成连续的器乐，并动态调整生成方向。

import asyncio
from google import genai
from google.genai import types

client = genai.Client()

async def main():
    async with client.aio.live.music.connect(model='models/lyria-realtime-exp') as session:
        # Set prompts and config
        await session.set_weighted_prompts(
            prompts=[types.WeightedPrompt(text='minimal techno', weight=1.0)]
        )
        await session.set_music_generation_config(
            config=types.LiveMusicGenerationConfig(bpm=90, temperature=1.0)
        )

        # Start streaming
        await session.play()

        # Receive audio chunks
        async for message in session.receive():
            if message.server_content and message.server_content.audio_chunks:
                audio_data = message.server_content.audio_chunks[0].data
                # Process audio...

asyncio.run(main())

const session = await ai.live.music.connect({
    model: "models/lyria-realtime-exp",
    callbacks: {
        onmessage: (message) => {
            if (message.serverContent?.audioChunks) {
                for (const chunk of message.serverContent.audioChunks) {
                    const audioBuffer = Buffer.from(chunk.data, "base64");
                    // Process audio...
                }
            }
        },
    },
});

await session.setWeightedPrompts({
    weightedPrompts: [{ text: "minimal techno", weight: 1.0 }],
});

await session.setMusicGenerationConfig({
    musicGenerationConfig: { bpm: 90, temperature: 1.0 },
});

await session.play();

输出：48kHz 立体声 16 位 PCM。仅限器乐。可配置 BPM、音阶、密度和明亮度。

有关音乐调整、配置和提示词指南，请参阅 references/lyria.md。

---

嵌入

生成文本嵌入，用于语义相似度、搜索和分类。

result = client.models.embed_content(
    model="gemini-embedding-001",
    contents="What is the meaning of life?"
)
print(result.embeddings)

const response = await ai.models.embedContent({
    model: 'gemini-embedding-001',
    contents: 'What is the meaning of life?',
});
console.log(response.embeddings);

任务类型：SEMANTIC_SIMILARITY、CLASSIFICATION、CLUSTERING、RETRIEVAL_DOCUMENT、RETRIEVAL_QUERY

输出维度：768、1536、3072（默认）

有关批处理、任务类型和归一化，请参阅 references/embeddings.md。

---

思考（Gemini 3）

使用 thinking_level 控制推理深度：minimal（仅限 Flash）、low、medium（仅限 Flash）、high（默认）。

from google.genai import types

response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents="Solve this math problem...",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="high")
    ),
)

import { ThinkingLevel } from "@google/genai";

const response = await ai.models.generateContent({
  model: "gemini-3-flash-preview",
  contents: "Solve this math problem...",
  config: { thinkingConfig: { thinkingLevel: ThinkingLevel.HIGH } },
});

注意：不能将 thinking_level 与旧版 thinking_budget 混用（会返回 400 错误）。

对于 Gemini 2.5，请改用 thinking_budget（0-32768）。请参阅 references/thinking.md。

如需了解 Gemini 3 的完整功能（思维签名、媒体分辨率等），请参阅 references/gemini-3.md。

---

结构化输出

生成符合架构的 JSON 响应。

from pydantic import BaseModel
from typing import List

class Recipe(BaseModel):
    name: str
    ingredients: List[str]

response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents="Extract: chocolate chip cookies need flour, sugar, chips",
    config={
        "response_mime_type": "application/json",
        "response_json_schema": Recipe.model_json_schema(),
    },
)
recipe = Recipe.model_validate_json(response.text)

import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const recipeSchema = z.object({
  name: z.string(),
  ingredients: z.array(z.string()),
});

const response = await ai.models.generateContent({
  model: "gemini-3-flash-preview",
  contents: "Extract: chocolate chip cookies need flour, sugar, chips",
  config: {
    responseMimeType: "application/json",
    responseJsonSchema: zodToJsonSchema(recipeSchema),
  },
});

如需了解高级模式，请参阅 references/structured-outputs.md。

---

内置工具（Gemini 3）

可用：Google Search、File Search、Code Execution、URL Context、Function Calling

不支持：Google Maps grounding、Computer Use（这些功能请使用 Gemini 2.5）

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="What's the latest news on AI?",
    config={"tools": [{"google_search": {}}]},
)

const response = await ai.models.generateContent({
  model: "gemini-3-pro-preview",
  contents: "What's the latest news on AI?",
  config: { tools: [{ googleSearch: {} }] },
});

结构化输出 + 工具：Gemini 3 支持将 JSON 架构与内置工具（Google Search、URL Context、Code Execution）结合使用。请参阅 references/gemini-3.md。

如需查看所有工具模式，请参阅 references/tools.md。

---

函数调用

将模型连接到外部工具和 API。模型会决定何时调用函数并提供参数。

from google.genai import types

# Define function
get_weather = {
    "name": "get_weather",
    "description": "Get weather for a location",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {"type": "string", "description": "City name"},
        },
        "required": ["location"],
    },
}

response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents="What's the weather in Tokyo?",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[get_weather])]
    ),
)

# Check for function call
if response.function_calls:
    fc = response.function_calls[0]
    print(f"Call {fc.name} with {fc.args}")

const response = await ai.models.generateContent({
  model: "gemini-3-flash-preview",
  contents: "What's the weather in Tokyo?",
  config: {
    tools: [{ functionDeclarations: [getWeather] }],
  },
});

if (response.functionCalls) {
  const { name, args } = response.functionCalls[0];
  // Execute function and send result back
}

自动函数调用（Python）：直接将函数作为工具传入，即可自动执行。

如需了解执行模式、组合式调用、多模态响应、MCP 集成和最佳实践，请参阅 references/function-calling.md。

---

快速参考

功能	Python	JavaScript
生成	generate_content()	generateContent()
流式传输	generate_content_stream()	generateContentStream()
聊天	chats.create()	chats.create()
结构化输出	response_json_schema=	responseJsonSchema:
图像生成	gemini-2.5-flash-image	gemini-2.5-flash-image
视频生成	generate_videos()	generateVideos()
音乐生成	live.music.connect()	live.music.connect()
函数调用	function_declarations	functionDeclarations
嵌入	embed_content()	embedContent()
文件 API	files.upload()	files.upload()

---

Gemini 3 专属功能

如需了解 Gemini 3 的高级功能，请参阅 references/gemini-3.md：

• 思考级别：控制推理深度（minimal、low、medium、high）
• 媒体分辨率：精细控制多模态处理（media_resolution_low 到 ultra_high）
• 思维签名：函数调用和图像编辑上下文所必需
• 结构化输出 + 工具：将 JSON 架构与 Google Search、URL Context 结合使用
• 多模态函数响应：在工具响应中返回图像

---

资源

• Gemini 3 指南
• 模型概览
• 思考指南
• 思维签名
• 结构化输出
• 图像生成
• 视频生成（Veo）
• 音乐生成（Lyria）
• 函数调用
• 文档处理
• 嵌入
• Google AI Studio
• AI Studio 中的 Gemini 3 Pro
• AI Studio 中的 Gemini 3 Flash
• AI Studio 中的 Nano Banana Pro
• Veo Studio