歡迎使用 Gemini API¶
透過 Gemini API,從簡單的提示詞出發,打造可正式上線的應用程式與代理。 運用 Gemini 處理複雜的程式設計與多模態推理,透過 Decisions API 取得經校準的決策結果,或將多步驟工作交給受管理代理完成。 透過 Live API 串流語音與影片,或使用 Nano Banana 生成圖片、使用 Gemini Omni 生成影片、使用 Lyria 生成音樂。
# Set up your coding agent with these tools
# Search live docs with the MCP server
npx add-mcp "https://gemini-api-docs-mcp.dev"
# Add skills for current SDK syntax and rules
npx skills add google-gemini/gemini-skills --skill gemini-api-dev
# In Antigravity, install both with one plugin
agy plugin install https://github.com/google-gemini/gemini-skills
# Let your agent call the API from the terminal
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-4-carbon",
input="Explain how AI works in a few words"
)
print(interaction.output_text)
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
model: "gemini-4-carbon",
input: "Explain how AI works in a few words",
});
console.log(interaction.output_text);
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-4-carbon",
"input": "Explain how AI works in a few words"
}'
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
Client client = new Client();
CreateModelInteraction params =
CreateModelInteraction.builder()
.model(Model.of("gemini-4-carbon"))
.input(InteractionsInput.of("Explain how AI works in a few words"))
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
Model: interactions.Model("gemini-4-carbon"),
Input: interactions.NewInteractionsInput("Explain how AI works in a few words"),
}),
})
if err != nil {
log.Fatal(err)
}
if res.Interaction.OutputText != nil {
fmt.Println(*res.Interaction.OutputText)
}
}
gemini-api generate "Explain how AI works in a few words" -m gemini-4-carbon
認識各款模型¶
Gemini 4 Carbon
我們能力最強的推理模型,具備共用的 1M 上下文視窗,長篇解碼長度最高可達 1M 權杖。
- 模型代碼 gemini-4-carbon
- 上下文 1M 權杖
- 輸出上限 64K / 1M 權杖
- 模態 文字、圖片、音訊、影片、PDF
在 AI Studio 中試用 查看 Gemini 4 Carbon 模型詳細資訊
Gemini 4 Hydrogen
讓所有人都能享有尖端智慧,兼具速度與效率,適合日常程式設計與代理工作流程,同樣具備共用的 1M 上下文視窗,長篇解碼長度最高可達 1M 權杖。
- 模型代碼 gemini-4-hydrogen
- 上下文 1M 權杖
- 輸出上限 64K / 1M 權杖
- 模態 文字、圖片、音訊、影片、PDF
在 AI Studio 中試用 查看 Gemini 4 Hydrogen 模型詳細資訊
Gemini Decision 1
專為快速決策設計的多模態模型,能以零輸出權杖完成經校準的是/否、選擇與評分量表決策。
- 模型代碼 gemini-decision-1
- 上下文 262K 權杖
- 輸出上限 0 權杖(1,000 個問題)
- 模態 文字、圖片、音訊、影片、PDF
在 AI Studio 中試用 查看 Gemini Decision 1 模型詳細資訊
Gemini 3.8 Flash TTS
旗艦級創意文字轉語音模型,具備錄音室等級的語音逼真度、富有表現力的演繹能力,以及 Voice design 與 Voice replication 功能。
- 模型代碼 gemini-3.8-flash-tts
- 上下文 8K 權杖
- 輸出上限 16K 權杖
- 模態 文字 → 音訊
在 AI Studio 中試用 查看 Gemini 3.8 Flash TTS 模型詳細資訊
Nano Banana 2.1
高效率的圖片生成與編輯模型,視覺品質、文字排版與多輪一致性皆有所提升。
- 模型代碼 gemini-nano-banana-2.1
- 上下文 128K 權杖
- 輸出上限 32K 權杖
- 模態 文字、圖片、影片、PDF → 圖片、文字
在 AI Studio 中試用 查看 Nano Banana 2.1 模型詳細資訊
探索各項功能¶
import base64
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-nano-banana-2.1",
input="Generate an image of a nano banana dish in a fancy restaurant",
response_format={"type": "image", "aspect_ratio": "16:9", "image_size": "2K"},
)
with open("nano_banana.png", "wb") as f:
f.write(base64.b64decode(interaction.output_image.data))
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";
const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
model: "gemini-nano-banana-2.1",
input: "Generate an image of a nano banana dish in a fancy restaurant",
response_format: { type: "image", aspect_ratio: "16:9", image_size: "2K" },
});
fs.writeFileSync("nano_banana.png", Buffer.from(interaction.output_image.data, "base64"));
圖片生成¶
使用 Nano Banana 模型原生生成與編輯高度貼合情境的圖片,可透過文字、圖片或交錯的多模態提示詞進行。
- 最高 4K 解析度,並可彈性調整長寬比
- 多輪編輯與角色一致性
- 以搜尋接地提升視覺準確度與文字呈現效果
import base64
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-omni-1.2-flash",
input="A cinematic close-up of two people talking by a window in the rain",
)
with open("dialogue_example.mp4", "wb") as f:
f.write(base64.b64decode(interaction.output_video.data))
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";
const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
model: "gemini-omni-1.2-flash",
input: "A cinematic close-up of two people talking by a window in the rain",
});
if (interaction.output_video?.data) {
fs.writeFileSync(
"dialogue_example.mp4",
Buffer.from(interaction.output_video.data, "base64")
);
}
影片生成¶
透過文字或圖片提示詞,建立具備原生同步對話、音效與環境音訊的高畫質影片。
- 原生音訊與對話,與畫面動作同步
- 影格插補,可控制首尾影格
- 參考圖片,用於保留角色與風格
import asyncio
from google import genai
from google.genai import types
client = genai.Client(http_options={"api_version": "v1beta"})
async def main():
config = types.LiveConnectConfig(response_modalities=["AUDIO"])
async with client.aio.live.connect(
model="gemini-3.8-live-preview", config=config
) as session:
await session.send_client_content(
turns={"parts": [{"text": "Hello! Tell me a quick fun fact."}]}
)
async for response in session.receive():
if response.data is not None:
# Stream raw PCM audio bytes to speaker
pass
asyncio.run(main())
import { GoogleGenAI, Modality } from "@google/genai";
const ai = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });
const session = await ai.live.connect({
model: "gemini-3.8-live-preview",
config: { responseModalities: [Modality.AUDIO] },
callbacks: {
onmessage: (message) => {
if (message.serverContent?.modelTurn) {
// Handle low-latency streaming audio chunks
}
},
},
});
session.sendClientContent({
turns: [{ parts: [{ text: "Hello! Tell me a quick fun fact." }] }],
});
使用 Live API 的語音代理¶
打造即時、雙向的語音與影片代理,具備次秒級延遲、自然的插話處理與即時工具呼叫能力。
- 即時 WebSocket 串流,適用於音訊與影片
- 自然的語音活動偵測與打斷處理
- 富有表現力的多語言語音,具備情感化對話
from google import genai
client = genai.Client(http_options={"api_version": "v1beta"})
result = client.decisions.create(
model="gemini-decision-1",
input="The blue mug I ordered on Monday arrived cracked on Wednesday.",
questions={
"is_damaged": {
"type": "noul",
"instructions": "Did the item arrive damaged?",
},
},
)
answer = result.answers["is_damaged"]
print(f"P(damaged)={answer.noul:.2f} confidence={answer.confidence:.2f}")
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiVersion: "v1beta" });
const result = await ai.decisions.create({
model: "gemini-decision-1",
input: "The blue mug I ordered on Monday arrived cracked on Wednesday.",
questions: {
is_damaged: {
type: "noul",
instructions: "Did the item arrive damaged?",
},
},
});
const answer = result.answers?.is_damaged;
if (answer?.type === "noul") {
console.log(`P(damaged)=${answer.noul} confidence=${answer.confidence}`);
}
經校準的決策¶
針對文字、圖片、影片、音訊與 PDF,評估具型別的是/否、單選與評分量表問題,透過 Gemini Decision 1 以零輸出權杖完成。
- 經校準的機率,涵蓋是/否、選擇與有序評分量表
- 最多 1,000 個獨立問題,共用同一份輸入,僅需單次預填即可完成
- 零輸出權杖,涵蓋文字、圖片、音訊、影片與 PDF 輸入
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="Find the flaw in this distributed lock protocol and fix it.",
generation_config={
"thinking_level": "high",
"thinking_summaries": "auto",
},
)
for step in interaction.steps:
if step.type == "thought":
for summary in step.summary or []:
print("Thought summary:", summary.text)
print("Answer:", interaction.output_text)
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
model: "gemini-4-hydrogen",
input: "Find the flaw in this distributed lock protocol and fix it.",
generation_config: {
thinking_level: "high",
thinking_summaries: "auto",
},
});
for (const step of interaction.steps) {
if (step.type === "thought") {
for (const summary of step.summary ?? []) {
console.log("Thought summary:", summary.text);
}
}
}
console.log("Answer:", interaction.output_text);
自適應思考¶
控制 Gemini 在回應前的推理深度,從低延遲的 low 思考,到深入的多步驟 xhigh 推理皆可調整。
- 可設定的思考等級(minimal、low、medium、high、xhigh)
- 透明的思考摘要,即時串流呈現
- 交錯推理,橫跨工具呼叫與程式碼執行
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="Who won the latest F1 Grand Prix and what were the lap times?",
tools=[{"type": "google_search"}, {"type": "code_execution"}],
)
print(interaction.output_text)
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
model: "gemini-4-hydrogen",
input: "Who won the latest F1 Grand Prix and what were the lap times?",
tools: [{ type: "google_search" }, { type: "code_execution" }],
});
console.log(interaction.output_text);
內建工具與函式呼叫¶
透過託管工具與自訂函式宣告,將 Gemini 連接到即時資訊、運算資源與您自己的後端 API。
- Google Search 與 URL Context,用於即時網路接地
- Code Execution,在安全的 Python 沙箱中執行
- Custom Function Calling,支援平行多工具協調
from google import genai
from pydantic import BaseModel, Field
class FeedbackAnalysis(BaseModel):
sentiment: str = Field(description="positive, neutral, or negative")
summary: str = Field(description="One-sentence summary of the feedback.")
action_items: list[str]
client = genai.Client()
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="The new dashboard is fast, but exporting CSVs fails on mobile.",
response_format={
"type": "text",
"mime_type": "application/json",
"schema": FeedbackAnalysis.model_json_schema(),
},
)
print(interaction.output_text)
import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
const FeedbackSchema = z.object({
sentiment: z.enum(["positive", "neutral", "negative"]),
summary: z.string(),
actionItems: z.array(z.string()),
});
const ai = new GoogleGenAI({});
const interaction = await ai.interactions.create({
model: "gemini-4-hydrogen",
input: "The new dashboard is fast, but exporting CSVs fails on mobile.",
response_format: {
type: "text",
mime_type: "application/json",
schema: z.toJSONSchema(FeedbackSchema),
},
});
console.log(JSON.parse(interaction.output_text));
結構化輸出¶
限制 Gemini 的回應遵循嚴格的 JSON Schema、Pydantic 模型或 Zod 型別,讓下游自動化更可靠。
- 保證符合 JSON Schema,每次回應皆然
- 原生 Pydantic 與 Zod 結構定義整合
- 與工具相容,例如 Google Search 與 Code Execution
from google import genai
client = genai.Client()
uploaded_file = client.files.upload(file="full_codebase_archive.txt")
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input=[
{"type": "file", "file_uri": uploaded_file.uri},
{
"type": "text",
"text": "Trace how authentication tokens are refreshed across all services.",
},
],
)
print(interaction.output_text)
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({});
const uploadedFile = await ai.files.upload({
file: "full_codebase_archive.txt",
});
const interaction = await ai.interactions.create({
model: "gemini-4-hydrogen",
input: [
{ type: "file", fileUri: uploadedFile.uri },
{
type: "text",
text: "Trace how authentication tokens are refreshed across all services.",
},
],
});
console.log(interaction.output_text);
長上下文¶
在單一提示詞中輸入多達 100 萬權杖的程式碼、影片、音訊或文件,進行深入的跨檔案推理與情境內學習。
- 超過 1M 權杖的上下文視窗(約 50,000 行程式碼或 8 本小說)
- 近乎完美的回想能力,涵蓋長篇多模態輸入
- 上下文快取,降低重複提示詞的成本與延遲
from google import genai
schedule_meeting = {
"type": "function",
"name": "schedule_meeting",
"description": "Schedules a meeting with attendees at a given date and time.",
"parameters": {
"type": "object",
"properties": {
"attendees": {"type": "array", "items": {"type": "string"}},
"date": {"type": "string"},
"time": {"type": "string"},
"topic": {"type": "string"},
},
"required": ["attendees", "date", "time", "topic"],
},
}
client = genai.Client()
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="Schedule a meeting with Bob and Alice tomorrow at 10:00 AM about Q3 planning.",
tools=[schedule_meeting],
)
for step in interaction.steps:
if step.type == "function_call":
print(step.name, step.arguments)
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({});
const scheduleMeeting = {
type: "function",
name: "schedule_meeting",
description: "Schedules a meeting with attendees at a given date and time.",
parameters: {
type: "object",
properties: {
attendees: { type: "array", items: { type: "string" } },
date: { type: "string" },
time: { type: "string" },
topic: { type: "string" },
},
required: ["attendees", "date", "time", "topic"],
},
};
const interaction = await ai.interactions.create({
model: "gemini-4-hydrogen",
input: "Schedule a meeting with Bob and Alice tomorrow at 10:00 AM about Q3 planning.",
tools: [scheduleMeeting],
});
for (const step of interaction.steps) {
if (step.type === "function_call") {
console.log(step.name, step.arguments);
}
}
函式呼叫¶
透過結構化函式宣告與自動引數擷取,將 Gemini 連接到您自己的 API、資料庫與後端服務。
- 平行與組合式多步驟函式呼叫
- 嚴格遵循結構定義的工具引數
- 無縫整合內建工具與思考功能
import base64
from google import genai
client = genai.Client()
with open("financial_report.pdf", "rb") as f:
pdf_base64 = base64.b64encode(f.read()).decode("utf-8")
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input=[
{
"type": "document",
"data": pdf_base64,
"mime_type": "application/pdf",
},
{
"type": "text",
"text": "Summarize the key revenue drivers and extract the Q4 table.",
},
],
)
print(interaction.output_text)
import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";
const ai = new GoogleGenAI({});
const pdfData = fs.readFileSync("financial_report.pdf", {
encoding: "base64",
});
const interaction = await ai.interactions.create({
model: "gemini-4-hydrogen",
input: [
{
type: "document",
data: pdfData,
mime_type: "application/pdf",
},
{
type: "text",
text: "Summarize the key revenue drivers and extract the Q4 table.",
},
],
});
console.log(interaction.output_text);
文件理解¶
處理多達 1,000 頁的 PDF,透過原生視覺與文字理解能力,解析表格、圖表、示意圖與版面配置。
- 原生視覺型 PDF 解析,超越單純的 OCR
- 單份文件最多 1,000 頁,單次請求即可處理
- 結構化擷取複雜表格、表單與圖形
建立代理¶
Managed Agents 為 Gemini 提供工作區,讓它能自行規劃並完成任務。只需單次請求,Gemini 就能在託管的沙箱環境中撰寫並執行程式碼、搜尋網路並建立檔案。您可以先使用我們預先建置的 Antigravity 代理,或以自己的指令與工具加以自訂。
from google import genai
client = genai.Client(http_options={"api_version": "v1beta"})
interaction = client.interactions.create(
agent="antigravity-preview-09-2026",
input=(
"Research the top 5 sustainable fashion brands, "
"compare their materials and pricing tiers, and "
"build an interactive dashboard in analysis.html."
),
environment="remote"
)
print(interaction.output_text)
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });
const interaction = await ai.interactions.create({
agent: "antigravity-preview-09-2026",
input:
"Research the top 5 sustainable fashion brands, " +
"compare their materials and pricing tiers, and " +
"build an interactive dashboard in analysis.html.",
environment: "remote",
});
console.log(interaction.output_text);
curl -X POST \
"https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"agent": "antigravity-preview-09-2026",
"input": "Research the top 5 sustainable fashion brands, compare their materials and pricing tiers, and build an interactive dashboard in analysis.html.",
"environment": "remote"
}'
import com.google.genai.Client;
import com.google.genai.types.HttpOptions;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
Client client = Client.builder().httpOptions(HttpOptions.builder().apiVersion("v1beta").build()).build();
CreateAgentInteraction params =
CreateAgentInteraction.builder()
.agent(AgentOption.of("antigravity-preview-09-2026"))
.input(
InteractionsInput.of(
"Research the top 5 sustainable fashion brands, "
+ "compare their materials and pricing tiers, and "
+ "build an interactive dashboard in analysis.html."))
.environment(CreateAgentInteractionEnvironment.of("remote"))
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params))
.interaction()
.get();
System.out.println(interaction.outputText().orElse(""));
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta"}})
if err != nil {
log.Fatal(err)
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("antigravity-preview-09-2026"),
Input: interactions.NewInteractionsInput(
"Research the top 5 sustainable fashion brands, " +
"compare their materials and pricing tiers, and " +
"build an interactive dashboard in analysis.html.",
),
Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment("remote")),
}),
})
if err != nil {
log.Fatal(err)
}
if res.Interaction.OutputText != nil {
fmt.Println(*res.Interaction.OutputText)
}
}
gemini-api agent run "Research the top 5 sustainable fashion brands, compare their materials and pricing tiers, and build an interactive dashboard in analysis.html." \
--agent antigravity-preview-09-2026 \
--body '{"environment":"remote"}'
Interactions API¶
Interactions API 自 2026 年 6 月起已成為我們的預設介面,也是今後使用 Gemini 模型與代理進行開發的最佳方式。若您要開始新專案,建議使用 Interactions API。generateContent API 雖然仍受支援,但目前已視為舊版 API。
了解 Interactions API 如何管理對話狀態、訊息與輸出格式。
逐步指南,協助您將程式碼從 generateContent 轉換至 Interactions API。
串流即時權杖、漸進式思考內容與工具呼叫事件。