Gemini API 可利用 Gemini 模型,根據各種輸入內容 (包括文字、圖片、影片和音訊) 產生文字輸出內容。
以下是採用單一文字輸入內容的基本範例:
Python
from google import genai client = genai.Client(api_key="GEMINI_API_KEY") response = client.models.generate_content( model="gemini-2.0-flash", contents=["How does AI work?"] ) print(response.text)
JavaScript
import { GoogleGenAI } from "@google/genai"; const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" }); async function main() { const response = await ai.models.generateContent({ model: "gemini-2.0-flash", contents: "How does AI work?", }); console.log(response.text); } await main();
Go
package main import ( "context" "fmt" "os" "google.golang.org/genai" ) func main() { ctx := context.Background() client, _ := genai.NewClient(ctx, &genai.ClientConfig{ APIKey: os.Getenv("GEMINI_API_KEY"), Backend: genai.BackendGeminiAPI, }) result, _ := client.Models.GenerateContent( ctx, "gemini-2.0-flash", genai.Text("Explain how AI works in a few words"), nil, ) fmt.Println(result.Text()) }
REST
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_API_KEY" \ -H 'Content-Type: application/json' \ -X POST \ -d '{ "contents": [ { "parts": [ { "text": "How does AI work?" } ] } ] }'
Apps Script
// See https://developers.google.com/apps-script/guides/properties // for instructions on how to set the API key. const apiKey = PropertiesService.getScriptProperties().getProperty('GEMINI_API_KEY'); function main() { const payload = { contents: [ { parts: [ { text: 'How AI does work?' }, ], }, ], }; const url = `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=${apiKey}`; const options = { method: 'POST', contentType: 'application/json', payload: JSON.stringify(payload) }; const response = UrlFetchApp.fetch(url, options); const data = JSON.parse(response); const content = data['candidates'][0]['content']['parts'][0]['text']; console.log(content); }
系統指示和設定
您可以透過系統指令引導 Gemini 模型的行為。如要這麼做,請傳遞 GenerateContentConfig
物件。
Python
from google import genai from google.genai import types client = genai.Client(api_key="GEMINI_API_KEY") response = client.models.generate_content( model="gemini-2.0-flash", config=types.GenerateContentConfig( system_instruction="You are a cat. Your name is Neko."), contents="Hello there" ) print(response.text)
JavaScript
import { GoogleGenAI } from "@google/genai"; const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" }); async function main() { const response = await ai.models.generateContent({ model: "gemini-2.0-flash", contents: "Hello there", config: { systemInstruction: "You are a cat. Your name is Neko.", }, }); console.log(response.text); } await main();
Go
package main import ( "context" "fmt" "os" "google.golang.org/genai" ) func main() { ctx := context.Background() client, _ := genai.NewClient(ctx, &genai.ClientConfig{ APIKey: os.Getenv("GEMINI_API_KEY"), Backend: genai.BackendGeminiAPI, }) config := &genai.GenerateContentConfig{ SystemInstruction: genai.NewContentFromText("You are a cat. Your name is Neko.", genai.RoleUser), } result, _ := client.Models.GenerateContent( ctx, "gemini-2.0-flash", genai.Text("Hello there"), config, ) fmt.Println(result.Text()) }
REST
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "system_instruction": { "parts": [ { "text": "You are a cat. Your name is Neko." } ] }, "contents": [ { "parts": [ { "text": "Hello there" } ] } ] }'
Apps Script
// See https://developers.google.com/apps-script/guides/properties // for instructions on how to set the API key. const apiKey = PropertiesService.getScriptProperties().getProperty('GEMINI_API_KEY'); function main() { const systemInstruction = { parts: [{ text: 'You are a cat. Your name is Neko.' }] }; const payload = { systemInstruction, contents: [ { parts: [ { text: 'Hello there' }, ], }, ], }; const url = `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=${apiKey}`; const options = { method: 'POST', contentType: 'application/json', payload: JSON.stringify(payload) }; const response = UrlFetchApp.fetch(url, options); const data = JSON.parse(response); const content = data['candidates'][0]['content']['parts'][0]['text']; console.log(content); }
GenerateContentConfig
物件還可讓您覆寫預設產生參數,例如溫度。
Python
from google import genai from google.genai import types client = genai.Client(api_key="GEMINI_API_KEY") response = client.models.generate_content( model="gemini-2.0-flash", contents=["Explain how AI works"], config=types.GenerateContentConfig( max_output_tokens=500, temperature=0.1 ) ) print(response.text)
JavaScript
import { GoogleGenAI } from "@google/genai"; const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" }); async function main() { const response = await ai.models.generateContent({ model: "gemini-2.0-flash", contents: "Explain how AI works", config: { maxOutputTokens: 500, temperature: 0.1, }, }); console.log(response.text); } await main();
Go
package main import ( "context" "fmt" "os" "google.golang.org/genai" ) func main() { ctx := context.Background() client, _ := genai.NewClient(ctx, &genai.ClientConfig{ APIKey: os.Getenv("GEMINI_API_KEY"), Backend: genai.BackendGeminiAPI, }) temp := float32(0.9) topP := float32(0.5) topK := float32(20.0) maxOutputTokens := int32(100) config := &genai.GenerateContentConfig{ Temperature: &temp, TopP: &topP, TopK: &topK, MaxOutputTokens: maxOutputTokens, ResponseMIMEType: "application/json", } result, _ := client.Models.GenerateContent( ctx, "gemini-2.0-flash", genai.Text("What is the average size of a swallow?"), config, ) fmt.Println(result.Text()) }
REST
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_API_KEY \ -H 'Content-Type: application/json' \ -X POST \ -d '{ "contents": [ { "parts": [ { "text": "Explain how AI works" } ] } ], "generationConfig": { "stopSequences": [ "Title" ], "temperature": 1.0, "maxOutputTokens": 800, "topP": 0.8, "topK": 10 } }'
Apps Script
// See https://developers.google.com/apps-script/guides/properties // for instructions on how to set the API key. const apiKey = PropertiesService.getScriptProperties().getProperty('GEMINI_API_KEY'); function main() { const generationConfig = { temperature: 1, topP: 0.95, topK: 40, maxOutputTokens: 8192, responseMimeType: 'text/plain', }; const payload = { generationConfig, contents: [ { parts: [ { text: 'Explain how AI works in a few words' }, ], }, ], }; const url = `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=${apiKey}`; const options = { method: 'POST', contentType: 'application/json', payload: JSON.stringify(payload) }; const response = UrlFetchApp.fetch(url, options); const data = JSON.parse(response); const content = data['candidates'][0]['content']['parts'][0]['text']; console.log(content); }
如需可設定參數和其說明的完整清單,請參閱 API 參考資料中的 GenerateContentConfig
。
多模態輸入
Gemini API 支援多模態輸入內容,可讓您將文字與媒體檔案結合。以下範例說明如何提供圖片:
Python
from PIL import Image from google import genai client = genai.Client(api_key="GEMINI_API_KEY") image = Image.open("/path/to/organ.png") response = client.models.generate_content( model="gemini-2.0-flash", contents=[image, "Tell me about this instrument"] ) print(response.text)
JavaScript
import { GoogleGenAI, createUserContent, createPartFromUri, } from "@google/genai"; const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" }); async function main() { const image = await ai.files.upload({ file: "/path/to/organ.png", }); const response = await ai.models.generateContent({ model: "gemini-2.0-flash", contents: [ createUserContent([ "Tell me about this instrument", createPartFromUri(image.uri, image.mimeType), ]), ], }); console.log(response.text); } await main();
Go
package main import ( "context" "fmt" "os" "google.golang.org/genai" ) func main() { ctx := context.Background() client, _ := genai.NewClient(ctx, &genai.ClientConfig{ APIKey: os.Getenv("GEMINI_API_KEY"), Backend: genai.BackendGeminiAPI, }) imagePath := "/path/to/organ.jpg" imgData, _ := os.ReadFile(imagePath) parts := []*genai.Part{ genai.NewPartFromText("Tell me about this instrument"), &genai.Part{ InlineData: &genai.Blob{ MIMEType: "image/jpeg", Data: imgData, }, }, } contents := []*genai.Content{ genai.NewContentFromParts(parts, genai.RoleUser), } result, _ := client.Models.GenerateContent( ctx, "gemini-2.0-flash", contents, nil, ) fmt.Println(result.Text()) }
REST
# Use a temporary file to hold the base64 encoded image data TEMP_B64=$(mktemp) trap 'rm -f "$TEMP_B64"' EXIT base64 $B64FLAGS $IMG_PATH > "$TEMP_B64" # Use a temporary file to hold the JSON payload TEMP_JSON=$(mktemp) trap 'rm -f "$TEMP_JSON"' EXIT cat > "$TEMP_JSON" << EOF { "contents": [ { "parts": [ { "text": "Tell me about this instrument" }, { "inline_data": { "mime_type": "image/jpeg", "data": "$(cat "$TEMP_B64")" } } ] } ] } EOF curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_API_KEY" \ -H 'Content-Type: application/json' \ -X POST \ -d "@$TEMP_JSON"
Apps Script
// See https://developers.google.com/apps-script/guides/properties // for instructions on how to set the API key. const apiKey = PropertiesService.getScriptProperties().getProperty('GEMINI_API_KEY'); function main() { const imageUrl = 'http://image/url'; const image = getImageData(imageUrl); const payload = { contents: [ { parts: [ { image }, { text: 'Tell me about this instrument' }, ], }, ], }; const url = `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=${apiKey}`; const options = { method: 'POST', contentType: 'application/json', payload: JSON.stringify(payload) }; const response = UrlFetchApp.fetch(url, options); const data = JSON.parse(response); const content = data['candidates'][0]['content']['parts'][0]['text']; console.log(content); } function getImageData(url) { const blob = UrlFetchApp.fetch(url).getBlob(); return { mimeType: blob.getContentType(), data: Utilities.base64Encode(blob.getBytes()) }; }
如要瞭解提供圖片的其他方法,以及更進階的圖片處理作業,請參閱圖像理解指南。這個 API 也支援文件、影片和音訊輸入內容和理解。
串流回應
根據預設,模型只會在整個生成程序完成後傳回回覆。
如要提供更流暢的互動體驗,請使用串流功能,逐步接收 GenerateContentResponse
例項。
Python
from google import genai client = genai.Client(api_key="GEMINI_API_KEY") response = client.models.generate_content_stream( model="gemini-2.0-flash", contents=["Explain how AI works"] ) for chunk in response: print(chunk.text, end="")
JavaScript
import { GoogleGenAI } from "@google/genai"; const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" }); async function main() { const response = await ai.models.generateContentStream({ model: "gemini-2.0-flash", contents: "Explain how AI works", }); for await (const chunk of response) { console.log(chunk.text); } } await main();
Go
package main import ( "context" "fmt" "os" "google.golang.org/genai" ) func main() { ctx := context.Background() client, _ := genai.NewClient(ctx, &genai.ClientConfig{ APIKey: os.Getenv("GEMINI_API_KEY"), Backend: genai.BackendGeminiAPI, }) stream := client.Models.GenerateContentStream( ctx, "gemini-2.0-flash", genai.Text("Write a story about a magic backpack."), nil, ) for chunk, _ := range stream { part := chunk.Candidates[0].Content.Parts[0] fmt.Print(part.Text) } }
REST
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:streamGenerateContent?alt=sse&key=${GEMINI_API_KEY}" \ -H 'Content-Type: application/json' \ --no-buffer \ -d '{ "contents": [ { "parts": [ { "text": "Explain how AI works" } ] } ] }'
Apps Script
// See https://developers.google.com/apps-script/guides/properties // for instructions on how to set the API key. const apiKey = PropertiesService.getScriptProperties().getProperty('GEMINI_API_KEY'); function main() { const payload = { contents: [ { parts: [ { text: 'Explain how AI works' }, ], }, ], }; const url = `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:streamGenerateContent?key=${apiKey}`; const options = { method: 'POST', contentType: 'application/json', payload: JSON.stringify(payload) }; const response = UrlFetchApp.fetch(url, options); const data = JSON.parse(response); const content = data['candidates'][0]['content']['parts'][0]['text']; console.log(content); }
多輪對話 (聊天)
我們的 SDK 提供功能,可將多輪提示和回覆收集到聊天中,讓您輕鬆追蹤對話記錄。
Python
from google import genai client = genai.Client(api_key="GEMINI_API_KEY") chat = client.chats.create(model="gemini-2.0-flash") response = chat.send_message("I have 2 dogs in my house.") print(response.text) response = chat.send_message("How many paws are in my house?") print(response.text) for message in chat.get_history(): print(f'role - {message.role}',end=": ") print(message.parts[0].text)
JavaScript
import { GoogleGenAI } from "@google/genai"; const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" }); async function main() { const chat = ai.chats.create({ model: "gemini-2.0-flash", history: [ { role: "user", parts: [{ text: "Hello" }], }, { role: "model", parts: [{ text: "Great to meet you. What would you like to know?" }], }, ], }); const response1 = await chat.sendMessage({ message: "I have 2 dogs in my house.", }); console.log("Chat response 1:", response1.text); const response2 = await chat.sendMessage({ message: "How many paws are in my house?", }); console.log("Chat response 2:", response2.text); } await main();
Go
package main import ( "context" "fmt" "os" "google.golang.org/genai" ) func main() { ctx := context.Background() client, _ := genai.NewClient(ctx, &genai.ClientConfig{ APIKey: os.Getenv("GEMINI_API_KEY"), Backend: genai.BackendGeminiAPI, }) history := []*genai.Content{ genai.NewContentFromText("Hi nice to meet you! I have 2 dogs in my house.", genai.RoleUser), genai.NewContentFromText("Great to meet you. What would you like to know?", genai.RoleModel), } chat, _ := client.Chats.Create(ctx, "gemini-2.0-flash", nil, history) res, _ := chat.SendMessage(ctx, genai.Part{Text: "How many paws are in my house?"}) if len(res.Candidates) > 0 { fmt.Println(res.Candidates[0].Content.Parts[0].Text) } }
REST
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_API_KEY \ -H 'Content-Type: application/json' \ -X POST \ -d '{ "contents": [ { "role": "user", "parts": [ { "text": "Hello" } ] }, { "role": "model", "parts": [ { "text": "Great to meet you. What would you like to know?" } ] }, { "role": "user", "parts": [ { "text": "I have two dogs in my house. How many paws are in my house?" } ] } ] }'
Apps Script
// See https://developers.google.com/apps-script/guides/properties // for instructions on how to set the API key. const apiKey = PropertiesService.getScriptProperties().getProperty('GEMINI_API_KEY'); function main() { const payload = { contents: [ { role: 'user', parts: [ { text: 'Hello' }, ], }, { role: 'model', parts: [ { text: 'Great to meet you. What would you like to know?' }, ], }, { role: 'user', parts: [ { text: 'I have two dogs in my house. How many paws are in my house?' }, ], }, ], }; const url = `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=${apiKey}`; const options = { method: 'POST', contentType: 'application/json', payload: JSON.stringify(payload) }; const response = UrlFetchApp.fetch(url, options); const data = JSON.parse(response); const content = data['candidates'][0]['content']['parts'][0]['text']; console.log(content); }
也可以用於多輪對話。
Python
from google import genai client = genai.Client(api_key="GEMINI_API_KEY") chat = client.chats.create(model="gemini-2.0-flash") response = chat.send_message_stream("I have 2 dogs in my house.") for chunk in response: print(chunk.text, end="") response = chat.send_message_stream("How many paws are in my house?") for chunk in response: print(chunk.text, end="") for message in chat.get_history(): print(f'role - {message.role}', end=": ") print(message.parts[0].text)
JavaScript
import { GoogleGenAI } from "@google/genai"; const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" }); async function main() { const chat = ai.chats.create({ model: "gemini-2.0-flash", history: [ { role: "user", parts: [{ text: "Hello" }], }, { role: "model", parts: [{ text: "Great to meet you. What would you like to know?" }], }, ], }); const stream1 = await chat.sendMessageStream({ message: "I have 2 dogs in my house.", }); for await (const chunk of stream1) { console.log(chunk.text); console.log("_".repeat(80)); } const stream2 = await chat.sendMessageStream({ message: "How many paws are in my house?", }); for await (const chunk of stream2) { console.log(chunk.text); console.log("_".repeat(80)); } } await main();
Go
package main import ( "context" "fmt" "os" "google.golang.org/genai" ) func main() { ctx := context.Background() client, _ := genai.NewClient(ctx, &genai.ClientConfig{ APIKey: os.Getenv("GEMINI_API_KEY"), Backend: genai.BackendGeminiAPI, }) history := []*genai.Content{ genai.NewContentFromText("Hi nice to meet you! I have 2 dogs in my house.", genai.RoleUser), genai.NewContentFromText("Great to meet you. What would you like to know?", genai.RoleModel), } chat, _ := client.Chats.Create(ctx, "gemini-2.0-flash", nil, history) stream := chat.SendMessageStream(ctx, genai.Part{Text: "How many paws are in my house?"}) for chunk, _ := range stream { part := chunk.Candidates[0].Content.Parts[0] fmt.Print(part.Text) } }
REST
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:streamGenerateContent?alt=sse&key=$GEMINI_API_KEY \ -H 'Content-Type: application/json' \ -X POST \ -d '{ "contents": [ { "role": "user", "parts": [ { "text": "Hello" } ] }, { "role": "model", "parts": [ { "text": "Great to meet you. What would you like to know?" } ] }, { "role": "user", "parts": [ { "text": "I have two dogs in my house. How many paws are in my house?" } ] } ] }'
Apps Script
// See https://developers.google.com/apps-script/guides/properties // for instructions on how to set the API key. const apiKey = PropertiesService.getScriptProperties().getProperty('GEMINI_API_KEY'); function main() { const payload = { contents: [ { role: 'user', parts: [ { text: 'Hello' }, ], }, { role: 'model', parts: [ { text: 'Great to meet you. What would you like to know?' }, ], }, { role: 'user', parts: [ { text: 'I have two dogs in my house. How many paws are in my house?' }, ], }, ], }; const url = `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:streamGenerateContent?key=${apiKey}`; const options = { method: 'POST', contentType: 'application/json', payload: JSON.stringify(payload) }; const response = UrlFetchApp.fetch(url, options); const data = JSON.parse(response); const content = data['candidates'][0]['content']['parts'][0]['text']; console.log(content); }
支援的模型
Gemini 系列的所有模型都支援文字生成功能。如要進一步瞭解模型及其功能,請參閱「模型」頁面。
最佳做法
提示訣竅
對於基本文字生成作業,只要使用零樣本提示,通常就足以產生結果,不需要範例、系統指示或特定格式。
如需更貼近需求的輸出內容:
如需更多提示,請參閱我們的提示工程指南。
結構化輸出內容
在某些情況下,您可能需要結構化輸出內容,例如 JSON。詳情請參閱結構化輸出內容指南。