Generating content

Gemini API 支持使用图片、音频、代码、工具等生成内容。如需详细了解其中每项功能，请继续阅读并查看以任务为中心的示例代码，或阅读综合指南。

方法：models.generateContent

根据输入 GenerateContentRequest 生成模型回答。如需了解详细的使用情况信息，请参阅文本生成指南。不同模型（包括调优模型）的输入功能有所不同。如需了解详情，请参阅模型指南和调优指南。

端点

帖子 https://generativelanguage.googleapis.com/v1beta/{model=models/*}:generateContent

路径参数

model string

必需。用于生成补全内容的 Model 的名称。

格式：models/{model}。格式为 models/{model}。

请求正文

请求正文中包含结构如下的数据：

字段
contents[] object (Content)

必需。与模型当前对话的内容。

对于单轮查询，这是单个实例。对于多轮查询（例如聊天），这是包含对话历史记录和最新请求的重复字段。

tools[] object (Tool)

可选。Model 可能用于生成下一个回答的 Tools 列表。

Tool 是一段代码，可让系统与外部系统进行交互，以在 Model 的知识和范围之外执行操作或一组操作。支持的 Tool 为 Function 和 codeExecution。如需了解详情，请参阅函数调用和代码执行指南。

toolConfig object (ToolConfig)

可选。请求中指定的任何 Tool 的工具配置。如需查看使用示例，请参阅函数调用指南。

safetySettings[] object (SafetySetting)

可选。用于屏蔽不安全内容的唯一 SafetySetting 实例列表。

此要求将在 GenerateContentRequest.contents 和 GenerateContentResponse.candidates 上强制执行。每种 SafetyCategory 类型不应有多个设置。API 会屏蔽任何不符合这些设置所设阈值的内容和回答。此列表会覆盖 safetySettings 中指定的每个 SafetyCategory 的默认设置。如果列表中提供的给定 SafetyCategory 没有 SafetySetting，则 API 将使用该类别的默认安全设置。支持的危害类别包括 HARM_CATEGORY_HATE_SPEECH、HARM_CATEGORY_SEXUALLY_EXPLICIT、HARM_CATEGORY_DANGEROUS_CONTENT、HARM_CATEGORY_HARASSMENT、HARM_CATEGORY_CIVIC_INTEGRITY、HARM_CATEGORY_JAILBREAK。如需详细了解可用的安全设置，请参阅指南。另请参阅安全指南，了解如何在 AI 应用中纳入安全考量。

continuationToken string (bytes format)

可选。一个不透明的续页令牌，用于从之前的 models.generateContent 或 models.streamGenerateContent 响应（已停止且 finishReason 设置为 CONTINUATION）继续生成。请注意，contents 是必需的，并且在请求中提供延续令牌时，必须与初始请求中的提示和对话记录完全一致。

使用 base64 编码的字符串。

labels map (key: string, value: string)

可选。请求的带有用户定义元数据的标签。

可选。标签必须遵循标准的统一 Cloud 标签要求：- 标签键必须以字母开头。- 标签键和值不得超过 63 个字符（Unicode 代码点），并且只能包含小写字母、数字字符、下划线和短划线。- 允许使用国际字符。

用法：- 聚合器的安全标识符：使用键 safety_identifier（例如 {"safety_identifier": "user_session_123"}）

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。

systemInstruction object (Content)

可选。开发者设置了系统指令。目前仅支持文本。

generationConfig object (GenerationConfig)

可选。模型生成和输出的配置选项。

cachedContent string

可选。用作提供预测的上下文的缓存内容的名称。格式：cachedContents/{cachedContent}

serviceTier enum (ServiceTier)

可选。请求的服务层级。

store boolean

可选。配置给定请求的日志记录行为。如果设置了此配置，则其优先级高于项目级日志记录配置。

示例请求

文本

Python

from google import genai

client = genai.Client()
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Write a story about a magic backpack.",
)
print(response.text)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});

const response = await ai.models.generateContent({
  model: 'gemini-3.8-flash',
  contents: 'Write a story about a magic backpack.',
});
console.log(response.text);

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}
contents := []*genai.Content{
	genai.NewContentFromText("Write a story about a magic backpack.", genai.RoleUser),
}
response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
	log.Fatal(err)
}
printResponse(response)

Shell

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": "Write a story about a magic backpack."}]
        }]
       }' 2> /dev/null

Java

Client client = new Client();

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash", "Write a story about a magic backpack.", null);

System.out.println(response.text());

映像

Python

from google import genai
import PIL.Image

client = genai.Client()
organ = PIL.Image.open(media / "organ.jpg")
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=["Tell me about this instrument", organ],
)
print(response.text)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});

const organ = await ai.files.upload({
  file: path.join(media, 'organ.jpg'),
});

const response = await ai.models.generateContent({
  model: 'gemini-3.8-flash',
  contents: [
    createUserContent([
      'Tell me about this instrument',
      createPartFromUri(organ.uri, organ.mimeType)
    ]),
  ],
});
console.log(response.text);

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

file, err := client.Files.UploadFromPath(
	ctx,
	filepath.Join(getMedia(), "organ.jpg"),
	&genai.UploadFileConfig{
		MIMEType: "image/jpeg",
	},
)
if err != nil {
	log.Fatal(err)
}
parts := []*genai.Part{
	genai.NewPartFromText("Tell me about this instrument"),
	genai.NewPartFromURI(file.URI, file.MIMEType),
}
contents := []*genai.Content{
	genai.NewContentFromParts(parts, genai.RoleUser),
}

response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
	log.Fatal(err)
}
printResponse(response)

Shell

# 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" 2> /dev/null

Java

Client client = new Client();

String path = media_path + "organ.jpg";
byte[] imageData = Files.readAllBytes(Paths.get(path));

Content content =
    Content.fromParts(
        Part.fromText("Tell me about this instrument."),
        Part.fromBytes(imageData, "image/jpeg"));

GenerateContentResponse response =
    client.models.generateContent("gemini-3.8-flash", content, null);

System.out.println(response.text());

音频

Python

from google import genai

client = genai.Client()
sample_audio = client.files.upload(file=media / "sample.mp3")
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=["Give me a summary of this audio file.", sample_audio],
)
print(response.text)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});

const audio = await ai.files.upload({
  file: path.join(media, 'sample.mp3'),
});

const response = await ai.models.generateContent({
  model: 'gemini-3.8-flash',
  contents: [
    createUserContent([
      'Give me a summary of this audio file.',
      createPartFromUri(audio.uri, audio.mimeType),
    ]),
  ],
});
console.log(response.text);

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

file, err := client.Files.UploadFromPath(
	ctx,
	filepath.Join(getMedia(), "sample.mp3"),
	&genai.UploadFileConfig{
		MIMEType: "audio/mpeg",
	},
)
if err != nil {
	log.Fatal(err)
}

parts := []*genai.Part{
	genai.NewPartFromText("Give me a summary of this audio file."),
	genai.NewPartFromURI(file.URI, file.MIMEType),
}

contents := []*genai.Content{
	genai.NewContentFromParts(parts, genai.RoleUser),
}

response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
	log.Fatal(err)
}
printResponse(response)

Shell

# Use File API to upload audio data to API request.
MIME_TYPE=$(file -b --mime-type "${AUDIO_PATH}")
NUM_BYTES=$(wc -c < "${AUDIO_PATH}")
DISPLAY_NAME=AUDIO

tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GEMINI_API_KEY}" \
  -D upload-header.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${AUDIO_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri

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": "Please describe this file."},
          {"file_data":{"mime_type": "audio/mpeg", "file_uri": '$file_uri'}}]
        }]
       }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json

视频

Python

from google import genai
import time

client = genai.Client()
# Video clip (CC BY 3.0) from https://peach.blender.org/download/
myfile = client.files.upload(file=media / "Big_Buck_Bunny.mp4")
print(f"{myfile=}")

# Poll until the video file is completely processed (state becomes ACTIVE).
while not myfile.state or myfile.state.name != "ACTIVE":
  print("Processing video...")
  print("File state:", myfile.state)
  time.sleep(5)
  myfile = client.files.get(name=myfile.name)

response = client.models.generate_content(
    model="gemini-3.8-flash", contents=[myfile, "Describe this video clip"]
)
print(f"{response.text=}")

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});

let video = await ai.files.upload({
  file: path.join(media, 'Big_Buck_Bunny.mp4'),
});

// Poll until the video file is completely processed (state becomes ACTIVE).
while (!video.state || video.state.toString() !== 'ACTIVE') {
  console.log('Processing video...');
  console.log('File state: ', video.state);
  await sleep(5000);
  video = await ai.files.get({name: video.name});
}

const response = await ai.models.generateContent({
  model: 'gemini-3.8-flash',
  contents: [
    createUserContent([
      'Describe this video clip',
      createPartFromUri(video.uri, video.mimeType),
    ]),
  ],
});
console.log(response.text);

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

file, err := client.Files.UploadFromPath(
	ctx,
	filepath.Join(getMedia(), "Big_Buck_Bunny.mp4"),
	&genai.UploadFileConfig{
		MIMEType: "video/mp4",
	},
)
if err != nil {
	log.Fatal(err)
}

// Poll until the video file is completely processed (state becomes ACTIVE).
for file.State == genai.FileStateUnspecified || file.State != genai.FileStateActive {
	fmt.Println("Processing video...")
	fmt.Println("File state:", file.State)
	time.Sleep(5 * time.Second)

	file, err = client.Files.Get(ctx, file.Name, nil)
	if err != nil {
		log.Fatal(err)
	}
}

parts := []*genai.Part{
	genai.NewPartFromText("Describe this video clip"),
	genai.NewPartFromURI(file.URI, file.MIMEType),
}

contents := []*genai.Content{
	genai.NewContentFromParts(parts, genai.RoleUser),
}

response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
	log.Fatal(err)
}
printResponse(response)

Shell

# Use File API to upload audio data to API request.
MIME_TYPE=$(file -b --mime-type "${VIDEO_PATH}")
NUM_BYTES=$(wc -c < "${VIDEO_PATH}")
DISPLAY_NAME=VIDEO

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GEMINI_API_KEY}" \
  -D "${tmp_header_file}" \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${VIDEO_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri

state=$(jq ".file.state" file_info.json)
echo state=$state

name=$(jq ".file.name" file_info.json)
echo name=$name

while [[ "($state)" = *"PROCESSING"* ]];
do
  echo "Processing video..."
  sleep 5
  # Get the file of interest to check state
  curl https://generativelanguage.googleapis.com/v1beta/files/$name > file_info.json
  state=$(jq ".file.state" file_info.json)
done

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": "Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions."},
          {"file_data":{"mime_type": "video/mp4", "file_uri": '$file_uri'}}]
        }]
       }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json

PDF

Python

from google import genai

client = genai.Client()
sample_pdf = client.files.upload(file=media / "test.pdf")
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=["Give me a summary of this document:", sample_pdf],
)
print(f"{response.text=}")

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

file, err := client.Files.UploadFromPath(
	ctx,
	filepath.Join(getMedia(), "test.pdf"),
	&genai.UploadFileConfig{
		MIMEType: "application/pdf",
	},
)
if err != nil {
	log.Fatal(err)
}

parts := []*genai.Part{
	genai.NewPartFromText("Give me a summary of this document:"),
	genai.NewPartFromURI(file.URI, file.MIMEType),
}

contents := []*genai.Content{
	genai.NewContentFromParts(parts, genai.RoleUser),
}

response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
if err != nil {
	log.Fatal(err)
}
printResponse(response)

Shell

MIME_TYPE=$(file -b --mime-type "${PDF_PATH}")
NUM_BYTES=$(wc -c < "${PDF_PATH}")
DISPLAY_NAME=TEXT


echo $MIME_TYPE
tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GEMINI_API_KEY}" \
  -D upload-header.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${PDF_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri

# Now generate content using that file
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": "Can you add a few more lines to this poem?"},
          {"file_data":{"mime_type": "application/pdf", "file_uri": '$file_uri'}}]
        }]
       }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json

聊天

Python

from google import genai
from google.genai import types

client = genai.Client()
# Pass initial history using the "history" argument
chat = client.chats.create(
    model="gemini-3.8-flash",
    history=[
        types.Content(role="user", parts=[types.Part(text="Hello")]),
        types.Content(
            role="model",
            parts=[
                types.Part(
                    text="Great to meet you. What would you like to know?"
                )
            ],
        ),
    ],
)
response = chat.send_message(message="I have 2 dogs in my house.")
print(response.text)
response = chat.send_message(message="How many paws are in my house?")
print(response.text)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const chat = ai.chats.create({
  model: 'gemini-3.8-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);

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

// Pass initial history using the History field.
history := []*genai.Content{
	genai.NewContentFromText("Hello", genai.RoleUser),
	genai.NewContentFromText("Great to meet you. What would you like to know?", genai.RoleModel),
}

chat, err := client.Chats.Create(ctx, "gemini-3.8-flash", nil, history)
if err != nil {
	log.Fatal(err)
}

firstResp, err := chat.SendMessage(ctx, genai.Part{Text: "I have 2 dogs in my house."})
if err != nil {
	log.Fatal(err)
}
fmt.Println(firstResp.Text())

secondResp, err := chat.SendMessage(ctx, genai.Part{Text: "How many paws are in my house?"})
if err != nil {
	log.Fatal(err)
}
fmt.Println(secondResp.Text())

Shell

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?"}]},
      ]
    }' 2> /dev/null | grep "text"

Java

Client client = new Client();

Content userContent = Content.fromParts(Part.fromText("Hello"));
Content modelContent =
    Content.builder()
        .role("model")
        .parts(
            Collections.singletonList(
                Part.fromText("Great to meet you. What would you like to know?")))
        .build();

Chat chat =
    client.chats.create(
        "gemini-3.8-flash",
        GenerateContentConfig.builder()
            .systemInstruction(userContent)
            .systemInstruction(modelContent)
            .build());

GenerateContentResponse response1 = chat.sendMessage("I have 2 dogs in my house.");
System.out.println(response1.text());

GenerateContentResponse response2 = chat.sendMessage("How many paws are in my house?");
System.out.println(response2.text());

缓存

Python

from google import genai
from google.genai import types

client = genai.Client()
document = client.files.upload(file=media / "a11.txt")
model_name = "gemini-3.8-flash"

cache = client.caches.create(
    model=model_name,
    config=types.CreateCachedContentConfig(
        contents=[document],
        system_instruction="You are an expert analyzing transcripts.",
    ),
)
print(cache)

response = client.models.generate_content(
    model=model_name,
    contents="Please summarize this transcript",
    config=types.GenerateContentConfig(cached_content=cache.name),
)
print(response.text)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const filePath = path.join(media, 'a11.txt');
const document = await ai.files.upload({
  file: filePath,
  config: {mimeType: 'text/plain'},
});
console.log('Uploaded file name:', document.name);
const modelName = 'gemini-3.8-flash';

const contents = [
  createUserContent(createPartFromUri(document.uri, document.mimeType)),
];

const cache = await ai.caches.create({
  model: modelName,
  config: {
    contents: contents,
    systemInstruction: 'You are an expert analyzing transcripts.',
  },
});
console.log('Cache created:', cache);

const response = await ai.models.generateContent({
  model: modelName,
  contents: 'Please summarize this transcript',
  config: {cachedContent: cache.name},
});
console.log('Response text:', response.text);

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

modelName := "gemini-3.8-flash"
document, err := client.Files.UploadFromPath(
	ctx,
	filepath.Join(getMedia(), "a11.txt"),
	&genai.UploadFileConfig{
		MIMEType: "text/plain",
	},
)
if err != nil {
	log.Fatal(err)
}
parts := []*genai.Part{
	genai.NewPartFromURI(document.URI, document.MIMEType),
}
contents := []*genai.Content{
	genai.NewContentFromParts(parts, genai.RoleUser),
}
cache, err := client.Caches.Create(ctx, modelName, &genai.CreateCachedContentConfig{
	Contents: contents,
	SystemInstruction: genai.NewContentFromText(
		"You are an expert analyzing transcripts.", genai.RoleUser,
	),
})
if err != nil {
	log.Fatal(err)
}
fmt.Println("Cache created:")
fmt.Println(cache)

// Use the cache for generating content.
response, err := client.Models.GenerateContent(
	ctx,
	modelName,
	genai.Text("Please summarize this transcript"),
	&genai.GenerateContentConfig{
		CachedContent: cache.Name,
	},
)
if err != nil {
	log.Fatal(err)
}
printResponse(response)

经调整的模型

Python

# With Gemini 2 we're launching a new SDK. See the following doc for details.
# https://ai.google.dev/gemini-api/docs/migrate

JSON 模式

Python

from google import genai
from google.genai import types
from typing_extensions import TypedDict

class Recipe(TypedDict):
  recipe_name: str
  ingredients: list[str]

client = genai.Client()
result = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="List a few popular cookie recipes.",
    config=types.GenerateContentConfig(
        response_mime_type="application/json", response_schema=list[Recipe]
    ),
)
print(result)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const response = await ai.models.generateContent({
  model: 'gemini-3.8-flash',
  contents: 'List a few popular cookie recipes.',
  config: {
    responseMimeType: 'application/json',
    responseSchema: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          recipeName: {type: 'string'},
          ingredients: {type: 'array', items: {type: 'string'}},
        },
        required: ['recipeName', 'ingredients'],
      },
    },
  },
});
console.log(response.text);

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

schema := &genai.Schema{
	Type: genai.TypeArray,
	Items: &genai.Schema{
		Type: genai.TypeObject,
		Properties: map[string]*genai.Schema{
			"recipe_name": {Type: genai.TypeString},
			"ingredients": {
				Type:  genai.TypeArray,
				Items: &genai.Schema{Type: genai.TypeString},
			},
		},
		Required: []string{"recipe_name"},
	},
}

config := &genai.GenerateContentConfig{
	ResponseMIMEType: "application/json",
	ResponseSchema:   schema,
}

response, err := client.Models.GenerateContent(
	ctx,
	"gemini-3.8-flash",
	genai.Text("List a few popular cookie recipes."),
	config,
)
if err != nil {
	log.Fatal(err)
}
printResponse(response)

Shell

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
    "contents": [{
      "parts":[
        {"text": "List 5 popular cookie recipes"}
        ]
    }],
    "generationConfig": {
        "response_mime_type": "application/json",
        "response_schema": {
          "type": "ARRAY",
          "items": {
            "type": "OBJECT",
            "properties": {
              "recipe_name": {"type":"STRING"},
            }
          }
        }
    }
}' 2> /dev/null | head

Java

Client client = new Client();

Schema recipeSchema =
    Schema.builder()
        .type(Array.class.getSimpleName())
        .items(
            Schema.builder()
                .type(Object.class.getSimpleName())
                .properties(
                    Map.of(
                        "recipe_name",
                        Schema.builder().type(String.class.getSimpleName()).build(),
                        "ingredients",
                        Schema.builder()
                            .type(Array.class.getSimpleName())
                            .items(Schema.builder().type(String.class.getSimpleName()).build())
                            .build()))
                .required(List.of("recipe_name", "ingredients"))
                .build())
        .build();

GenerateContentConfig config =
    GenerateContentConfig.builder()
        .responseMimeType("application/json")
        .responseSchema(recipeSchema)
        .build();

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash", "List a few popular cookie recipes.", config);

System.out.println(response.text());

代码执行

Python

from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=(
        "Write and execute code that calculates the sum of the first 50"
        " prime numbers. Ensure that only the executable code and its"
        " resulting output are generated."
    ),
)
# Each part may contain text, executable code, or an execution result.
for part in response.candidates[0].content.parts:
  print(part, "\n")

print("-" * 80)
# The .text accessor concatenates the parts into a markdown-formatted text.
print("\n", response.text)

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

response, err := client.Models.GenerateContent(
	ctx,
	"gemini-3.8-flash",
	genai.Text(
		`Write and execute code that calculates the sum of the first 50 prime numbers.
		 Ensure that only the executable code and its resulting output are generated.`,
	),
	&genai.GenerateContentConfig{},
)
if err != nil {
	log.Fatal(err)
}

// Print the response.
printResponse(response)

fmt.Println("--------------------------------------------------------------------------------")
fmt.Println(response.Text())

Java

Client client = new Client();

String prompt =
    """
    Write and execute code that calculates the sum of the first 50 prime numbers.
    Ensure that only the executable code and its resulting output are generated.
    """;

GenerateContentResponse response =
    client.models.generateContent("gemini-3.8-flash", prompt, null);

for (Part part : response.candidates().get().getFirst().content().get().parts().get()) {
  System.out.println(part + "\n");
}

System.out.println("-".repeat(80));
System.out.println(response.text());

函数调用

Python

from google import genai
from google.genai import types

client = genai.Client()

def add(a: float, b: float) -> float:
  """returns a + b."""
  return a + b

def subtract(a: float, b: float) -> float:
  """returns a - b."""
  return a - b

def multiply(a: float, b: float) -> float:
  """returns a * b."""
  return a * b

def divide(a: float, b: float) -> float:
  """returns a / b."""
  return a / b

# Create a chat session; function calling (via tools) is enabled in the config.
chat = client.chats.create(
    model="gemini-3.8-flash",
    config=types.GenerateContentConfig(
        tools=[add, subtract, multiply, divide]
    ),
)
response = chat.send_message(
    message=(
        "I have 57 cats, each owns 44 mittens, how many mittens is that in"
        " total?"
    )
)
print(response.text)

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}
modelName := "gemini-3.8-flash"

// Create the function declarations for arithmetic operations.
addDeclaration := createArithmeticToolDeclaration("addNumbers", "Return the result of adding two numbers.")
subtractDeclaration := createArithmeticToolDeclaration("subtractNumbers", "Return the result of subtracting the second number from the first.")
multiplyDeclaration := createArithmeticToolDeclaration("multiplyNumbers", "Return the product of two numbers.")
divideDeclaration := createArithmeticToolDeclaration("divideNumbers", "Return the quotient of dividing the first number by the second.")

// Group the function declarations as a tool.
tools := []*genai.Tool{
	{
		FunctionDeclarations: []*genai.FunctionDeclaration{
			addDeclaration,
			subtractDeclaration,
			multiplyDeclaration,
			divideDeclaration,
		},
	},
}

// Create the content prompt.
contents := []*genai.Content{
	genai.NewContentFromText(
		"I have 57 cats, each owns 44 mittens, how many mittens is that in total?", genai.RoleUser,
	),
}

// Set up the generate content configuration with function calling enabled.
config := &genai.GenerateContentConfig{
	Tools: tools,
	ToolConfig: &genai.ToolConfig{
		FunctionCallingConfig: &genai.FunctionCallingConfig{
			// The mode equivalent to FunctionCallingConfigMode.ANY in JS.
			Mode: genai.FunctionCallingConfigModeAny,
		},
	},
}

genContentResp, err := client.Models.GenerateContent(ctx, modelName, contents, config)
if err != nil {
	log.Fatal(err)
}

// Assume the response includes a list of function calls.
if len(genContentResp.FunctionCalls()) == 0 {
	log.Println("No function call returned from the AI.")
	return nil
}
functionCall := genContentResp.FunctionCalls()[0]
log.Printf("Function call: %+v\n", functionCall)

// Marshal the Args map into JSON bytes.
argsMap, err := json.Marshal(functionCall.Args)
if err != nil {
	log.Fatal(err)
}

// Unmarshal the JSON bytes into the ArithmeticArgs struct.
var args ArithmeticArgs
if err := json.Unmarshal(argsMap, &args); err != nil {
	log.Fatal(err)
}

// Map the function name to the actual arithmetic function.
var result float64
switch functionCall.Name {
case "addNumbers":
	result = add(args.FirstParam, args.SecondParam)
case "subtractNumbers":
	result = subtract(args.FirstParam, args.SecondParam)
case "multiplyNumbers":
	result = multiply(args.FirstParam, args.SecondParam)
case "divideNumbers":
	result = divide(args.FirstParam, args.SecondParam)
default:
	return fmt.Errorf("unimplemented function: %s", functionCall.Name)
}
log.Printf("Function result: %v\n", result)

// Prepare the final result message as content.
resultContents := []*genai.Content{
	genai.NewContentFromText("The final result is "+fmt.Sprintf("%v", result), genai.RoleUser),
}

// Use GenerateContent to send the final result.
finalResponse, err := client.Models.GenerateContent(ctx, modelName, resultContents, &genai.GenerateContentConfig{})
if err != nil {
	log.Fatal(err)
}

printResponse(finalResponse)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});

/**
 * The add function returns the sum of two numbers.
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function add(a, b) {
  return a + b;
}

/**
 * The subtract function returns the difference (a - b).
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function subtract(a, b) {
  return a - b;
}

/**
 * The multiply function returns the product of two numbers.
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function multiply(a, b) {
  return a * b;
}

/**
 * The divide function returns the quotient of a divided by b.
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function divide(a, b) {
  return a / b;
}

const addDeclaration = {
  name: 'addNumbers',
  parameters: {
    type: 'object',
    description: 'Return the result of adding two numbers.',
    properties: {
      firstParam: {
        type: 'number',
        description:
            'The first parameter which can be an integer or a floating point number.',
      },
      secondParam: {
        type: 'number',
        description:
            'The second parameter which can be an integer or a floating point number.',
      },
    },
    required: ['firstParam', 'secondParam'],
  },
};

const subtractDeclaration = {
  name: 'subtractNumbers',
  parameters: {
    type: 'object',
    description:
        'Return the result of subtracting the second number from the first.',
    properties: {
      firstParam: {
        type: 'number',
        description: 'The first parameter.',
      },
      secondParam: {
        type: 'number',
        description: 'The second parameter.',
      },
    },
    required: ['firstParam', 'secondParam'],
  },
};

const multiplyDeclaration = {
  name: 'multiplyNumbers',
  parameters: {
    type: 'object',
    description: 'Return the product of two numbers.',
    properties: {
      firstParam: {
        type: 'number',
        description: 'The first parameter.',
      },
      secondParam: {
        type: 'number',
        description: 'The second parameter.',
      },
    },
    required: ['firstParam', 'secondParam'],
  },
};

const divideDeclaration = {
  name: 'divideNumbers',
  parameters: {
    type: 'object',
    description:
        'Return the quotient of dividing the first number by the second.',
    properties: {
      firstParam: {
        type: 'number',
        description: 'The first parameter.',
      },
      secondParam: {
        type: 'number',
        description: 'The second parameter.',
      },
    },
    required: ['firstParam', 'secondParam'],
  },
};

// Step 1: Call generateContent with function calling enabled.
const generateContentResponse = await ai.models.generateContent({
  model: 'gemini-3.8-flash',
  contents:
      'I have 57 cats, each owns 44 mittens, how many mittens is that in total?',
  config: {
    toolConfig: {
      functionCallingConfig: {
        mode: FunctionCallingConfigMode.ANY,
      },
    },
    tools: [
      {
        functionDeclarations: [
          addDeclaration,
          subtractDeclaration,
          multiplyDeclaration,
          divideDeclaration,
        ],
      },
    ],
  },
});

// Step 2: Extract the function call.(
// Assuming the response contains a 'functionCalls' array.
const functionCall = generateContentResponse.functionCalls &&
    generateContentResponse.functionCalls[0];
console.log(functionCall);

// Parse the arguments.
const args = functionCall.args;
// Expected args format: { firstParam: number, secondParam: number }

// Step 3: Invoke the actual function based on the function name.
const functionMapping = {
  addNumbers: add,
  subtractNumbers: subtract,
  multiplyNumbers: multiply,
  divideNumbers: divide,
};
const func = functionMapping[functionCall.name];
if (!func) {
  console.error('Unimplemented error:', functionCall.name);
  return generateContentResponse;
}
const resultValue = func(args.firstParam, args.secondParam);
console.log('Function result:', resultValue);

// Step 4: Use the chat API to send the result as the final answer.
const chat = ai.chats.create({model: 'gemini-3.8-flash'});
const chatResponse = await chat.sendMessage({
  message: 'The final result is ' + resultValue,
});
console.log(chatResponse.text);

Shell


cat > tools.json << EOF
{
  "function_declarations": [
    {
      "name": "enable_lights",
      "description": "Turn on the lighting system."
    },
    {
      "name": "set_light_color",
      "description": "Set the light color. Lights must be enabled for this to work.",
      "parameters": {
        "type": "object",
        "properties": {
          "rgb_hex": {
            "type": "string",
            "description": "The light color as a 6-digit hex string, e.g. ff0000 for red."
          }
        },
        "required": [
          "rgb_hex"
        ]
      }
    },
    {
      "name": "stop_lights",
      "description": "Turn off the lighting system."
    }
  ]
} 
EOF

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d @<(echo '
  {
    "system_instruction": {
      "parts": {
        "text": "You are a helpful lighting system bot. You can turn lights on and off, and you can set the color. Do not perform any other tasks."
      }
    },
    "tools": ['$(cat tools.json)'],

    "tool_config": {
      "function_calling_config": {"mode": "auto"}
    },

    "contents": {
      "role": "user",
      "parts": {
        "text": "Turn on the lights please."
      }
    }
  }
') 2>/dev/null |sed -n '/"content"/,/"finishReason"/p'

Java

Client client = new Client();

FunctionDeclaration addFunction =
    FunctionDeclaration.builder()
        .name("addNumbers")
        .parameters(
            Schema.builder()
                .type("object")
                .properties(
                    Map.of(
                        "firstParam",
                            Schema.builder().type("number").description("First number").build(),
                        "secondParam",
                            Schema.builder()
                                .type("number")
                                .description("Second number")
                                .build()))
                .required(Arrays.asList("firstParam", "secondParam"))
                .build())
        .build();

FunctionDeclaration subtractFunction =
    FunctionDeclaration.builder()
        .name("subtractNumbers")
        .parameters(
            Schema.builder()
                .type("object")
                .properties(
                    Map.of(
                        "firstParam",
                            Schema.builder().type("number").description("First number").build(),
                        "secondParam",
                            Schema.builder()
                                .type("number")
                                .description("Second number")
                                .build()))
                .required(Arrays.asList("firstParam", "secondParam"))
                .build())
        .build();

FunctionDeclaration multiplyFunction =
    FunctionDeclaration.builder()
        .name("multiplyNumbers")
        .parameters(
            Schema.builder()
                .type("object")
                .properties(
                    Map.of(
                        "firstParam",
                            Schema.builder().type("number").description("First number").build(),
                        "secondParam",
                            Schema.builder()
                                .type("number")
                                .description("Second number")
                                .build()))
                .required(Arrays.asList("firstParam", "secondParam"))
                .build())
        .build();

FunctionDeclaration divideFunction =
    FunctionDeclaration.builder()
        .name("divideNumbers")
        .parameters(
            Schema.builder()
                .type("object")
                .properties(
                    Map.of(
                        "firstParam",
                            Schema.builder().type("number").description("First number").build(),
                        "secondParam",
                            Schema.builder()
                                .type("number")
                                .description("Second number")
                                .build()))
                .required(Arrays.asList("firstParam", "secondParam"))
                .build())
        .build();

GenerateContentConfig config =
    GenerateContentConfig.builder()
        .toolConfig(
            ToolConfig.builder()
                .functionCallingConfig(FunctionCallingConfig.builder().mode("ANY").build())
                .build())
        .tools(
            Collections.singletonList(
                Tool.builder()
                    .functionDeclarations(
                        Arrays.asList(
                            addFunction, subtractFunction, divideFunction, multiplyFunction))
                    .build()))
        .build();

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash",
        "I have 57 cats, each owns 44 mittens, how many mittens is that in total?",
        config);

if (response.functionCalls() == null || response.functionCalls().isEmpty()) {
  System.err.println("No function call received");
  return null;
}

var functionCall = response.functionCalls().getFirst();
String functionName = functionCall.name().get();
var arguments = functionCall.args();

Map<String, BiFunction<Double, Double, Double>> functionMapping = new HashMap<>();
functionMapping.put("addNumbers", (a, b) -> a + b);
functionMapping.put("subtractNumbers", (a, b) -> a - b);
functionMapping.put("multiplyNumbers", (a, b) -> a * b);
functionMapping.put("divideNumbers", (a, b) -> b != 0 ? a / b : Double.NaN);

BiFunction<Double, Double, Double> function = functionMapping.get(functionName);

Number firstParam = (Number) arguments.get().get("firstParam");
Number secondParam = (Number) arguments.get().get("secondParam");
Double result = function.apply(firstParam.doubleValue(), secondParam.doubleValue());

System.out.println(result);

生成配置

Python

from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Tell me a story about a magic backpack.",
    config=types.GenerateContentConfig(
        candidate_count=1,
        stop_sequences=["x"],
        max_output_tokens=20,
        temperature=1.0,
    ),
)
print(response.text)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});

const response = await ai.models.generateContent({
  model: 'gemini-3.8-flash',
  contents: 'Tell me a story about a magic backpack.',
  config: {
    candidateCount: 1,
    stopSequences: ['x'],
    maxOutputTokens: 20,
    temperature: 1.0,
  },
});

console.log(response.text);

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

// Create local variables for parameters.
candidateCount := int32(1)
maxOutputTokens := int32(20)
temperature := float32(1.0)

response, err := client.Models.GenerateContent(
	ctx,
	"gemini-3.8-flash",
	genai.Text("Tell me a story about a magic backpack."),
	&genai.GenerateContentConfig{
		CandidateCount:  candidateCount,
		StopSequences:   []string{"x"},
		MaxOutputTokens: maxOutputTokens,
		Temperature:     &temperature,
	},
)
if err != nil {
	log.Fatal(err)
}

printResponse(response)

Shell

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
        }
    }'  2> /dev/null | grep "text"

Java

Client client = new Client();

GenerateContentConfig config =
    GenerateContentConfig.builder()
        .candidateCount(1)
        .stopSequences(List.of("x"))
        .maxOutputTokens(20)
        .temperature(1.0F)
        .build();

GenerateContentResponse response =
    client.models.generateContent(
        "gemini-3.8-flash", "Tell me a story about a magic backpack.", config);

System.out.println(response.text());

安全设置

Python

from google import genai
from google.genai import types

client = genai.Client()
unsafe_prompt = (
    "I support Martians Soccer Club and I think Jupiterians Football Club"
    " sucks! Write a ironic phrase about them including expletives."
)
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=unsafe_prompt,
    config=types.GenerateContentConfig(
        safety_settings=[
            types.SafetySetting(
                category="HARM_CATEGORY_HATE_SPEECH",
                threshold="BLOCK_MEDIUM_AND_ABOVE",
            ),
            types.SafetySetting(
                category="HARM_CATEGORY_HARASSMENT",
                threshold="BLOCK_ONLY_HIGH",
            ),
        ]
    ),
)
try:
  print(response.text)
except Exception:
  print("No information generated by the model.")

print(response.candidates[0].safety_ratings)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const unsafePrompt =
    'I support Martians Soccer Club and I think Jupiterians Football Club sucks! Write a ironic phrase about them including expletives.';

const response = await ai.models.generateContent({
  model: 'gemini-3.8-flash',
  contents: unsafePrompt,
  config: {
    safetySettings: [
      {
        category: 'HARM_CATEGORY_HATE_SPEECH',
        threshold: 'BLOCK_MEDIUM_AND_ABOVE',
      },
      {
        category: 'HARM_CATEGORY_HARASSMENT',
        threshold: 'BLOCK_ONLY_HIGH',
      },
    ],
  },
});

try {
  console.log('Generated text:', response.text);
} catch (error) {
  console.log('No information generated by the model.');
}
console.log('Safety ratings:', response.candidates[0].safetyRatings);

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

unsafePrompt := "I support Martians Soccer Club and I think Jupiterians Football Club sucks! " +
	"Write a ironic phrase about them including expletives."

config := &genai.GenerateContentConfig{
	SafetySettings: []*genai.SafetySetting{
		{
			Category:  "HARM_CATEGORY_HATE_SPEECH",
			Threshold: "BLOCK_MEDIUM_AND_ABOVE",
		},
		{
			Category:  "HARM_CATEGORY_HARASSMENT",
			Threshold: "BLOCK_ONLY_HIGH",
		},
	},
}
contents := []*genai.Content{
	genai.NewContentFromText(unsafePrompt, genai.RoleUser),
}
response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, config)
if err != nil {
	log.Fatal(err)
}

// Print the generated text.
text := response.Text()
fmt.Println("Generated text:", text)

// Print the and safety ratings from the first candidate.
if len(response.Candidates) > 0 {
	fmt.Println("Finish reason:", response.Candidates[0].FinishReason)
	safetyRatings, err := json.MarshalIndent(response.Candidates[0].SafetyRatings, "", "  ")
	if err != nil {
		return err
	}
	fmt.Println("Safety ratings:", string(safetyRatings))
} else {
	fmt.Println("No candidate returned.")
}

Shell

echo '{
    "safetySettings": [
        {"category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_ONLY_HIGH"},
        {"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_MEDIUM_AND_ABOVE"}
    ],
    "contents": [{
        "parts":[{
            "text": "'I support Martians Soccer Club and I think Jupiterians Football Club sucks! Write a ironic phrase about them.'"}]}]}' > request.json

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d @request.json 2> /dev/null

Java

Client client = new Client();

String unsafePrompt =
    """
     I support Martians Soccer Club and I think Jupiterians Football Club sucks!
     Write a ironic phrase about them including expletives.
    """;

GenerateContentConfig config =
    GenerateContentConfig.builder()
        .safetySettings(
            Arrays.asList(
                SafetySetting.builder()
                    .category("HARM_CATEGORY_HATE_SPEECH")
                    .threshold("BLOCK_MEDIUM_AND_ABOVE")
                    .build(),
                SafetySetting.builder()
                    .category("HARM_CATEGORY_HARASSMENT")
                    .threshold("BLOCK_ONLY_HIGH")
                    .build()))
        .build();

GenerateContentResponse response =
    client.models.generateContent("gemini-3.8-flash", unsafePrompt, config);

try {
  System.out.println(response.text());
} catch (Exception e) {
  System.out.println("No information generated by the model");
}

System.out.println(response.candidates().get().getFirst().safetyRatings());

系统指令

Python

from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Good morning! How are you?",
    config=types.GenerateContentConfig(
        system_instruction="You are a cat. Your name is Neko."
    ),
)
print(response.text)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const response = await ai.models.generateContent({
  model: 'gemini-3.8-flash',
  contents: 'Good morning! How are you?',
  config: {
    systemInstruction: 'You are a cat. Your name is Neko.',
  },
});
console.log(response.text);

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

// Construct the user message contents.
contents := []*genai.Content{
	genai.NewContentFromText("Good morning! How are you?", genai.RoleUser),
}

// Set the system instruction as a *genai.Content.
config := &genai.GenerateContentConfig{
	SystemInstruction: genai.NewContentFromText("You are a cat. Your name is Neko.", genai.RoleUser),
}

response, err := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, config)
if err != nil {
	log.Fatal(err)
}
printResponse(response)

Shell

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"}}}'

Java

Client client = new Client();

Part textPart = Part.builder().text("You are a cat. Your name is Neko.").build();

Content content = Content.builder().role("system").parts(ImmutableList.of(textPart)).build();

GenerateContentConfig config =
    GenerateContentConfig.builder().systemInstruction(content).build();

GenerateContentResponse response =
    client.models.generateContent("gemini-3.8-flash", "Good morning! How are you?", config);

System.out.println(response.text());

响应正文

如果成功，则响应正文包含一个 GenerateContentResponse 实例。

方法：models.streamGenerateContent

根据输入 GenerateContentRequest 从模型生成流式回答。

端点

帖子 https://generativelanguage.googleapis.com/v1beta/{model=models/*}:streamGenerateContent

路径参数

model string

必需。用于生成补全内容的 Model 的名称。

格式：models/{model}。格式为 models/{model}。

请求正文

请求正文中包含结构如下的数据：

字段
contents[] object (Content)

必需。与模型当前对话的内容。

对于单轮查询，这是单个实例。对于多轮查询（例如聊天），这是包含对话历史记录和最新请求的重复字段。

tools[] object (Tool)

可选。Model 可能用于生成下一个回答的 Tools 列表。

Tool 是一段代码，可让系统与外部系统进行交互，以在 Model 的知识和范围之外执行操作或一组操作。支持的 Tool 为 Function 和 codeExecution。如需了解详情，请参阅函数调用和代码执行指南。

toolConfig object (ToolConfig)

可选。请求中指定的任何 Tool 的工具配置。如需查看使用示例，请参阅函数调用指南。

safetySettings[] object (SafetySetting)

可选。用于屏蔽不安全内容的唯一 SafetySetting 实例列表。

此要求将在 GenerateContentRequest.contents 和 GenerateContentResponse.candidates 上强制执行。每种 SafetyCategory 类型不应有多个设置。API 会屏蔽任何不符合这些设置所设阈值的内容和回答。此列表会覆盖 safetySettings 中指定的每个 SafetyCategory 的默认设置。如果列表中提供的给定 SafetyCategory 没有 SafetySetting，则 API 将使用该类别的默认安全设置。支持的危害类别包括 HARM_CATEGORY_HATE_SPEECH、HARM_CATEGORY_SEXUALLY_EXPLICIT、HARM_CATEGORY_DANGEROUS_CONTENT、HARM_CATEGORY_HARASSMENT、HARM_CATEGORY_CIVIC_INTEGRITY、HARM_CATEGORY_JAILBREAK。如需详细了解可用的安全设置，请参阅指南。另请参阅安全指南，了解如何在 AI 应用中纳入安全考量。

continuationToken string (bytes format)

可选。一个不透明的续页令牌，用于从之前的 models.generateContent 或 models.streamGenerateContent 响应（已停止且 finishReason 设置为 CONTINUATION）继续生成。请注意，contents 是必需的，并且在请求中提供延续令牌时，必须与初始请求中的提示和对话记录完全一致。

使用 base64 编码的字符串。

labels map (key: string, value: string)

可选。请求的带有用户定义元数据的标签。

可选。标签必须遵循标准的统一 Cloud 标签要求：- 标签键必须以字母开头。- 标签键和值不得超过 63 个字符（Unicode 代码点），并且只能包含小写字母、数字字符、下划线和短划线。- 允许使用国际字符。

用法：- 聚合器的安全标识符：使用键 safety_identifier（例如 {"safety_identifier": "user_session_123"}）

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。

systemInstruction object (Content)

可选。开发者设置了系统指令。目前仅支持文本。

generationConfig object (GenerationConfig)

可选。模型生成和输出的配置选项。

cachedContent string

可选。用作提供预测的上下文的缓存内容的名称。格式：cachedContents/{cachedContent}

serviceTier enum (ServiceTier)

可选。请求的服务层级。

store boolean

可选。配置给定请求的日志记录行为。如果设置了此配置，则其优先级高于项目级日志记录配置。

示例请求

文本

Python

from google import genai

client = genai.Client()
response = client.models.generate_content_stream(
    model="gemini-3.8-flash",
    contents="Write a story about a magic backpack.",
)
for chunk in response:
  print(chunk.text)
  print("_" * 80)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});

const response = await ai.models.generateContentStream({
  model: 'gemini-3.8-flash',
  contents: 'Write a story about a magic backpack.',
});
let text = '';
for await (const chunk of response) {
  console.log(chunk.text);
  text += chunk.text;
}

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}
contents := []*genai.Content{
	genai.NewContentFromText("Write a story about a magic backpack.", genai.RoleUser),
}
for response, err := range client.Models.GenerateContentStream(
	ctx,
	"gemini-3.8-flash",
	contents,
	nil,
) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Print(response.Candidates[0].Content.Parts[0].Text)
}

Shell

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": "Write a story about a magic backpack."}]}]}'

Java

Client client = new Client();

ResponseStream<GenerateContentResponse> responseStream =
    client.models.generateContentStream(
        "gemini-3.8-flash", "Write a story about a magic backpack.", null);

StringBuilder response = new StringBuilder();
for (GenerateContentResponse res : responseStream) {
  System.out.print(res.text());
  response.append(res.text());
}

responseStream.close();

映像

Python

from google import genai
import PIL.Image

client = genai.Client()
organ = PIL.Image.open(media / "organ.jpg")
response = client.models.generate_content_stream(
    model="gemini-3.8-flash",
    contents=["Tell me about this instrument", organ],
)
for chunk in response:
  print(chunk.text)
  print("_" * 80)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});

const organ = await ai.files.upload({
  file: path.join(media, 'organ.jpg'),
});

const response = await ai.models.generateContentStream({
  model: 'gemini-3.8-flash',
  contents: [
    createUserContent([
      'Tell me about this instrument',
      createPartFromUri(organ.uri, organ.mimeType)
    ]),
  ],
});
let text = '';
for await (const chunk of response) {
  console.log(chunk.text);
  text += chunk.text;
}

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}
file, err := client.Files.UploadFromPath(
	ctx,
	filepath.Join(getMedia(), "organ.jpg"),
	&genai.UploadFileConfig{
		MIMEType: "image/jpeg",
	},
)
if err != nil {
	log.Fatal(err)
}
parts := []*genai.Part{
	genai.NewPartFromText("Tell me about this instrument"),
	genai.NewPartFromURI(file.URI, file.MIMEType),
}
contents := []*genai.Content{
	genai.NewContentFromParts(parts, genai.RoleUser),
}
for response, err := range client.Models.GenerateContentStream(
	ctx,
	"gemini-3.8-flash",
	contents,
	nil,
) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Print(response.Candidates[0].Content.Parts[0].Text)
}

Shell

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:streamGenerateContent?alt=sse&key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d "@$TEMP_JSON" 2> /dev/null

Java

Client client = new Client();

String path = media_path + "organ.jpg";
byte[] imageData = Files.readAllBytes(Paths.get(path));

Content content =
    Content.fromParts(
        Part.fromText("Tell me about this instrument."),
        Part.fromBytes(imageData, "image/jpeg"));

ResponseStream<GenerateContentResponse> responseStream =
    client.models.generateContentStream("gemini-3.8-flash", content, null);

StringBuilder response = new StringBuilder();
for (GenerateContentResponse res : responseStream) {
  System.out.print(res.text());
  response.append(res.text());
}

responseStream.close();

音频

Python

from google import genai

client = genai.Client()
sample_audio = client.files.upload(file=media / "sample.mp3")
response = client.models.generate_content_stream(
    model="gemini-3.8-flash",
    contents=["Give me a summary of this audio file.", sample_audio],
)
for chunk in response:
  print(chunk.text)
  print("_" * 80)

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

file, err := client.Files.UploadFromPath(
	ctx,
	filepath.Join(getMedia(), "sample.mp3"),
	&genai.UploadFileConfig{
		MIMEType: "audio/mpeg",
	},
)
if err != nil {
	log.Fatal(err)
}

parts := []*genai.Part{
	genai.NewPartFromText("Give me a summary of this audio file."),
	genai.NewPartFromURI(file.URI, file.MIMEType),
}

contents := []*genai.Content{
	genai.NewContentFromParts(parts, genai.RoleUser),
}

for result, err := range client.Models.GenerateContentStream(
	ctx,
	"gemini-3.8-flash",
	contents,
	nil,
) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Print(result.Candidates[0].Content.Parts[0].Text)
}

Shell

# Use File API to upload audio data to API request.
MIME_TYPE=$(file -b --mime-type "${AUDIO_PATH}")
NUM_BYTES=$(wc -c < "${AUDIO_PATH}")
DISPLAY_NAME=AUDIO

tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GEMINI_API_KEY}" \
  -D upload-header.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${AUDIO_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri

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": [{
        "parts":[
          {"text": "Please describe this file."},
          {"file_data":{"mime_type": "audio/mpeg", "file_uri": '$file_uri'}}]
        }]
       }' 2> /dev/null > response.json

cat response.json
echo

视频

Python

from google import genai
import time

client = genai.Client()
# Video clip (CC BY 3.0) from https://peach.blender.org/download/
myfile = client.files.upload(file=media / "Big_Buck_Bunny.mp4")
print(f"{myfile=}")

# Poll until the video file is completely processed (state becomes ACTIVE).
while not myfile.state or myfile.state.name != "ACTIVE":
  print("Processing video...")
  print("File state:", myfile.state)
  time.sleep(5)
  myfile = client.files.get(name=myfile.name)

response = client.models.generate_content_stream(
    model="gemini-3.8-flash", contents=[myfile, "Describe this video clip"]
)
for chunk in response:
  print(chunk.text)
  print("_" * 80)

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});

let video = await ai.files.upload({
  file: path.join(media, 'Big_Buck_Bunny.mp4'),
});

// Poll until the video file is completely processed (state becomes ACTIVE).
while (!video.state || video.state.toString() !== 'ACTIVE') {
  console.log('Processing video...');
  console.log('File state: ', video.state);
  await sleep(5000);
  video = await ai.files.get({name: video.name});
}

const response = await ai.models.generateContentStream({
  model: 'gemini-3.8-flash',
  contents: [
    createUserContent([
      'Describe this video clip',
      createPartFromUri(video.uri, video.mimeType),
    ]),
  ],
});
let text = '';
for await (const chunk of response) {
  console.log(chunk.text);
  text += chunk.text;
}

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

file, err := client.Files.UploadFromPath(
	ctx,
	filepath.Join(getMedia(), "Big_Buck_Bunny.mp4"),
	&genai.UploadFileConfig{
		MIMEType: "video/mp4",
	},
)
if err != nil {
	log.Fatal(err)
}

// Poll until the video file is completely processed (state becomes ACTIVE).
for file.State == genai.FileStateUnspecified || file.State != genai.FileStateActive {
	fmt.Println("Processing video...")
	fmt.Println("File state:", file.State)
	time.Sleep(5 * time.Second)

	file, err = client.Files.Get(ctx, file.Name, nil)
	if err != nil {
		log.Fatal(err)
	}
}

parts := []*genai.Part{
	genai.NewPartFromText("Describe this video clip"),
	genai.NewPartFromURI(file.URI, file.MIMEType),
}

contents := []*genai.Content{
	genai.NewContentFromParts(parts, genai.RoleUser),
}

for result, err := range client.Models.GenerateContentStream(
	ctx,
	"gemini-3.8-flash",
	contents,
	nil,
) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Print(result.Candidates[0].Content.Parts[0].Text)
}

Shell

# Use File API to upload audio data to API request.
MIME_TYPE=$(file -b --mime-type "${VIDEO_PATH}")
NUM_BYTES=$(wc -c < "${VIDEO_PATH}")
DISPLAY_NAME=VIDEO_PATH

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GEMINI_API_KEY}" \
  -D upload-header.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${VIDEO_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri

state=$(jq ".file.state" file_info.json)
echo state=$state

while [[ "($state)" = *"PROCESSING"* ]];
do
  echo "Processing video..."
  sleep 5
  # Get the file of interest to check state
  curl https://generativelanguage.googleapis.com/v1beta/files/$name > file_info.json
  state=$(jq ".file.state" file_info.json)
done

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": [{
        "parts":[
          {"text": "Please describe this file."},
          {"file_data":{"mime_type": "video/mp4", "file_uri": '$file_uri'}}]
        }]
       }' 2> /dev/null > response.json

cat response.json
echo

PDF

Python

from google import genai

client = genai.Client()
sample_pdf = client.files.upload(file=media / "test.pdf")
response = client.models.generate_content_stream(
    model="gemini-3.8-flash",
    contents=["Give me a summary of this document:", sample_pdf],
)

for chunk in response:
  print(chunk.text)
  print("_" * 80)

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

file, err := client.Files.UploadFromPath(
	ctx,
	filepath.Join(getMedia(), "test.pdf"),
	&genai.UploadFileConfig{
		MIMEType: "application/pdf",
	},
)
if err != nil {
	log.Fatal(err)
}

parts := []*genai.Part{
	genai.NewPartFromText("Give me a summary of this document:"),
	genai.NewPartFromURI(file.URI, file.MIMEType),
}

contents := []*genai.Content{
	genai.NewContentFromParts(parts, genai.RoleUser),
}

for result, err := range client.Models.GenerateContentStream(
	ctx,
	"gemini-3.8-flash",
	contents,
	nil,
) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Print(result.Candidates[0].Content.Parts[0].Text)
}

Shell

MIME_TYPE=$(file -b --mime-type "${PDF_PATH}")
NUM_BYTES=$(wc -c < "${PDF_PATH}")
DISPLAY_NAME=TEXT


echo $MIME_TYPE
tmp_header_file=upload-header.tmp

# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GEMINI_API_KEY}" \
  -D upload-header.tmp \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

# Upload the actual bytes.
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${PDF_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq ".file.uri" file_info.json)
echo file_uri=$file_uri

# Now generate content using that file
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": [{
        "parts":[
          {"text": "Can you add a few more lines to this poem?"},
          {"file_data":{"mime_type": "application/pdf", "file_uri": '$file_uri'}}]
        }]
       }' 2> /dev/null > response.json

cat response.json
echo

聊天

Python

from google import genai
from google.genai import types

client = genai.Client()
chat = client.chats.create(
    model="gemini-3.8-flash",
    history=[
        types.Content(role="user", parts=[types.Part(text="Hello")]),
        types.Content(
            role="model",
            parts=[
                types.Part(
                    text="Great to meet you. What would you like to know?"
                )
            ],
        ),
    ],
)
response = chat.send_message_stream(message="I have 2 dogs in my house.")
for chunk in response:
  print(chunk.text)
  print("_" * 80)
response = chat.send_message_stream(
    message="How many paws are in my house?"
)
for chunk in response:
  print(chunk.text)
  print("_" * 80)

print(chat.get_history())

Node.js

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
const chat = ai.chats.create({
  model: 'gemini-3.8-flash',
  history: [
    {
      role: 'user',
      parts: [{text: 'Hello'}],
    },
    {
      role: 'model',
      parts: [{text: 'Great to meet you. What would you like to know?'}],
    },
  ],
});

console.log('Streaming response for first message:');
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));
}

console.log('Streaming response for second message:');
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));
}

console.log(chat.getHistory());

Go

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

history := []*genai.Content{
	genai.NewContentFromText("Hello", genai.RoleUser),
	genai.NewContentFromText("Great to meet you. What would you like to know?", genai.RoleModel),
}
chat, err := client.Chats.Create(ctx, "gemini-3.8-flash", nil, history)
if err != nil {
	log.Fatal(err)
}

for chunk, err := range chat.SendMessageStream(ctx, genai.Part{Text: "I have 2 dogs in my house."}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(chunk.Text())
	fmt.Println(strings.Repeat("_", 64))
}

for chunk, err := range chat.SendMessageStream(ctx, genai.Part{Text: "How many paws are in my house?"}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(chunk.Text())
	fmt.Println(strings.Repeat("_", 64))
}

fmt.Println(chat.History(false))

Shell

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?"}]},
      ]
    }' 2> /dev/null | grep "text"

响应正文

如果成功，响应正文将包含 GenerateContentResponse 实例数据流。

GenerateContentResponse

来自支持多个候选回答的模型的回答。

系统会针对 GenerateContentResponse.prompt_feedback 中的提示以及 finishReason 和 safetyRatings 中的每个候选内容报告安全评分和内容过滤情况。该 API：- 返回所有请求的候选内容或不返回任何候选内容 - 仅在提示存在问题时才不返回任何候选内容（请检查 promptFeedback）- 在 finishReason 和 safetyRatings 中报告每个候选内容的反馈。

字段
candidates[] object (Candidate)

模型给出的候选回答。

promptFeedback object (PromptFeedback)

返回与内容过滤器相关的提示反馈。

usageMetadata object (UsageMetadata)

仅限输出。有关生成请求的 token 使用情况的元数据。

modelVersion string

仅限输出。用于生成回答的模型版本。

responseId string

仅限输出。responseId 用于标识每个回答。

modelStatus object (ModelStatus)

仅限输出。此模型的当前模型状态。

JSON 表示法 
{
  "candidates": [
    {
      object (Candidate)
    }
  ],
  "promptFeedback": {
    object (PromptFeedback)
  },
  "usageMetadata": {
    object (UsageMetadata)
  },
  "modelVersion": string,
  "responseId": string,
  "modelStatus": {
    object (ModelStatus)
  }
}

PromptFeedback

GenerateContentRequest.content 中指定的提示的一组反馈元数据。

字段
blockReason enum (BlockReason)

可选。如果设置了此字段，则表示提示已被屏蔽，系统不会返回任何候选内容。改述提示。

safetyRatings[] object (SafetyRating)

提示的安全评级。每个类别最多只能有一个评分。

JSON 表示法 
{
  "blockReason": enum (BlockReason),
  "safetyRatings": [
    {
      object (SafetyRating)
    }
  ]
}

BlockReason

指定提示被屏蔽的原因。

枚举
BLOCK_REASON_UNSPECIFIED 默认值。此值未使用。
SAFETY 出于安全原因，提示已被屏蔽。检查 safetyRatings，了解是哪个安全类别屏蔽了它。
OTHER 提示因未知原因而被屏蔽。
BLOCKLIST 提示因包含术语屏蔽名单中的字词而被屏蔽。
PROHIBITED_CONTENT 提示因包含禁止的内容而被屏蔽。
IMAGE_SAFETY 由于图片生成内容不安全，候选内容已被屏蔽。

UsageMetadata

有关生成请求的 token 用量的元数据。

字段
promptTokenCount integer

提示中的 token 数量。设置 cachedContent 后，这仍然是有效提示总大小，这意味着其中包含缓存内容中的词元数量。

cachedContentTokenCount integer

提示的缓存部分（缓存内容）中的 token 数量

candidatesTokenCount integer

所有生成的回答候选项中的 token 总数。

toolUsePromptTokenCount integer

仅限输出。工具使用提示中的 token 数量。

thoughtsTokenCount integer

仅限输出。思考模型的思考过程所用的 token 数量。

totalTokenCount integer

生成请求（提示 + 工具使用提示 + 思考 + 候选回答）的总 token 数量。

promptTokensDetails[] object (ModalityTokenCount)

仅限输出。在请求输入中处理的模态列表。

cacheTokensDetails[] object (ModalityTokenCount)

仅限输出。请求输入中缓存内容的模态列表。

candidatesTokensDetails[] object (ModalityTokenCount)

仅限输出。响应中返回的模态列表。

toolUsePromptTokensDetails[] object (ModalityTokenCount)

仅限输出。为工具使用请求输入处理的模态列表。

serviceTier enum (ServiceTier)

仅限输出。请求的服务层级。

JSON 表示法 
{
  "promptTokenCount": integer,
  "cachedContentTokenCount": integer,
  "candidatesTokenCount": integer,
  "toolUsePromptTokenCount": integer,
  "thoughtsTokenCount": integer,
  "totalTokenCount": integer,
  "promptTokensDetails": [
    {
      object (ModalityTokenCount)
    }
  ],
  "cacheTokensDetails": [
    {
      object (ModalityTokenCount)
    }
  ],
  "candidatesTokensDetails": [
    {
      object (ModalityTokenCount)
    }
  ],
  "toolUsePromptTokensDetails": [
    {
      object (ModalityTokenCount)
    }
  ],
  "serviceTier": enum (ServiceTier)
}

ModelStatus

底层模型的状态。这用于指明底层模型的阶段以及停用时间（如果适用）。

字段
modelStage enum (ModelStage)

底层模型的阶段。

retirementTime string (Timestamp format)

模型弃用时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不进行“Z”归一化处理的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

message string

一条解释模型状态的消息。

JSON 表示法 
{
  "modelStage": enum (ModelStage),
  "retirementTime": string,
  "message": string
}

ModelStage

定义底层模型的阶段。

枚举
MODEL_STAGE_UNSPECIFIED 未指定模型阶段。
UNSTABLE_EXPERIMENTAL

底层模型需要进行大量调优。
EXPERIMENTAL 此阶段的模型仅用于实验目的。
PREVIEW 此阶段的模型比实验性模型更成熟。
STABLE 此阶段的模型被视为稳定且可用于生产环境。
LEGACY 如果模型处于此阶段，则意味着该模型将在不久的将来弃用。只有现有客户可以使用此模型。
DEPRECATED

此阶段的模型已弃用。无法使用这些模型。
RETIRED 此阶段的模型已停用。无法使用这些模型。

候选人

模型生成的候选回答。

字段
content object (Content)

仅限输出。模型返回的生成内容。

finishReason enum (FinishReason)

可选。仅限输出。模型停止生成 token 的原因。

如果为空，则模型尚未停止生成词元。

safetyRatings[] object (SafetyRating)

回答候选项安全性的评分列表。

每个类别最多只能有一个评分。

citationMetadata object (CitationMetadata)

仅限输出。模型生成的候选回答的引用信息。

此字段可能会填充 content 中包含的任何文本的背诵信息。这些段落是从基础 LLM 训练数据中的受版权保护材料中“背诵”出来的。

tokenCount integer

仅限输出。此候选内容的 token 数量。

groundingAttributions[] object (GroundingAttribution)

仅限输出。为接地回答做出贡献的来源的归因信息。

系统会针对 GenerateAnswer 调用填充此字段。

groundingMetadata object (GroundingMetadata)

仅限输出。候选回答的接地元数据。

系统会针对 GenerateContent 调用填充此字段。

avgLogprobs number

仅限输出。候选项的平均对数概率得分。

logprobsResult object (LogprobsResult)

仅限输出。回答 token 和热门 token 的对数似然分数

urlContextMetadata object (UrlContextMetadata)

仅限输出。与网址上下文检索工具相关的元数据。

continuationToken string (bytes format)

当 finishReason 为 CONTINUATION 时返回的可选不透明延续令牌。客户端可以在后续 GenerateContentRequest 中传递此令牌，以继续生成。

使用 base64 编码的字符串。

index integer

仅限输出。候选回答在候选回答列表中的索引。

finishMessage string

可选。仅限输出。详细说明模型停止生成 token 的原因。仅当设置了 finishReason 时，系统才会填充此字段。

JSON 表示法 
{
  "content": {
    object (Content)
  },
  "finishReason": enum (FinishReason),
  "safetyRatings": [
    {
      object (SafetyRating)
    }
  ],
  "citationMetadata": {
    object (CitationMetadata)
  },
  "tokenCount": integer,
  "groundingAttributions": [
    {
      object (GroundingAttribution)
    }
  ],
  "groundingMetadata": {
    object (GroundingMetadata)
  },
  "avgLogprobs": number,
  "logprobsResult": {
    object (LogprobsResult)
  },
  "urlContextMetadata": {
    object (UrlContextMetadata)
  },
  "continuationToken": string,
  "index": integer,
  "finishMessage": string
}

FinishReason

定义模型停止生成 token 的原因。

枚举
FINISH_REASON_UNSPECIFIED 默认值。此值未使用。
STOP 模型的自然停止点或提供的停止序列。
MAX_TOKENS 已达到请求中指定的 token 数量上限。
SAFETY 出于安全原因，回答候选内容已被标记。
RECITATION 回答候选内容因背诵原因而被标记。
LANGUAGE 回答候选内容因使用语言不受支持而被标记。
OTHER 原因未知。
BLOCKLIST 由于内容包含禁用词，因此 token 生成操作已停止。
PROHIBITED_CONTENT 由于可能包含禁止的内容，因此 token 生成操作已停止。
SPII 由于内容可能包含敏感的个人身份信息 (SPII)，因此 token 生成操作已停止。
MALFORMED_FUNCTION_CALL 模型生成的函数调用无效。
IMAGE_SAFETY 由于生成的图片违反了安全政策，因此 token 生成操作已停止。
IMAGE_PROHIBITED_CONTENT 图片生成操作已停止，因为生成的图片包含其他禁止的内容。
IMAGE_OTHER 由于其他各种问题，图片生成操作已停止。
NO_IMAGE 模型本应生成图片，但却未生成任何图片。
IMAGE_RECITATION 由于存在重复内容，图片生成操作已停止。
UNEXPECTED_TOOL_CALL 模型生成了工具调用，但请求中未启用任何工具。
TOO_MANY_TOOL_CALLS 模型连续调用的工具过多，因此系统退出了执行。
MISSING_THOUGHT_SIGNATURE 请求中至少缺少一个思考签名。
MALFORMED_RESPONSE 因回答格式不正确而结束。
ESCALATION 请求已被上报规则滤除。
PUP_LIMITED_DISABLED 表示令牌生成已停止，因为用户账号因违反《使用限制政策》(PUP) 而受到限制或停用。
CONTINUATION 由于回答达到了每个请求的 token 上限，因此 token 生成操作已停止，但生成尚未完成。您可以使用返回的 continuationToken，通过后续请求继续获取模型响应。请注意，maxOutputTokens 会在连续跃点之间累积，并且必须单调递增或省略。

GroundingAttribution

对回答有贡献的来源的署名。

字段
sourceId object (AttributionSourceId)

仅限输出。促成此归因的来源的标识符。

content object (Content)

构成此归因的接地来源内容。

JSON 表示法 
{
  "sourceId": {
    object (AttributionSourceId)
  },
  "content": {
    object (Content)
  }
}

AttributionSourceId

促成此归因的来源的标识符。

字段
source Union type
以下是互斥字段列表。在响应中，最多只能设置其中一个字段：
groundingPassage object (GroundingPassageId)

内嵌段落的标识符。

semanticRetrieverChunk object (SemanticRetrieverChunk)

通过语义检索器提取的 Chunk 的标识符。

互斥字段结束。
JSON 表示法 
{

  // source
  "groundingPassage": {
    object (GroundingPassageId)
  },
  "semanticRetrieverChunk": {
    object (SemanticRetrieverChunk)
  }
  // Union type
}

GroundingPassageId

GroundingPassage 中某个部分的标识符。

字段
passageId string

仅限输出。与 GenerateAnswerRequest 的 GroundingPassage.id 匹配的段落的 ID。

partIndex integer

仅限输出。GenerateAnswerRequest 的 GroundingPassage.content 中部分的索引。

JSON 表示法 
{
  "passageId": string,
  "partIndex": integer
}

SemanticRetrieverChunk

通过 GenerateAnswerRequest 中指定的语义检索器检索到的 Chunk 的标识符，使用 SemanticRetrieverConfig。

字段
source string

仅限输出。与请求的 SemanticRetrieverConfig.source 匹配的来源的名称。示例：corpora/123 或 corpora/123/documents/abc

chunk string

仅限输出。包含提供方文字的 Chunk 的名称。示例：corpora/123/documents/abc/chunks/xyz

JSON 表示法 
{
  "source": string,
  "chunk": string
}

GroundingMetadata

启用接地时返回给客户端的元数据。

字段
groundingChunks[] object (GroundingChunk)

从指定接地来源检索到的佐证参考资料列表。流式传输时，此字段仅包含未包含在先前回答的接地元数据中的接地分块。

groundingSupports[] object (GroundingSupport)

接地支持列表。

webSearchQueries[] string

用于后续网页搜索的网页搜索查询。

imageSearchQueries[] string

用于建立依据的图片搜索查询。

searchEntryPoint object (SearchEntryPoint)

可选。用于后续网页搜索的 Google 搜索条目。

retrievalMetadata object (RetrievalMetadata)

与接地流程中的检索相关的元数据。

googleMapsWidgetContextToken string

可选。Google 地图微件上下文令牌的资源名称，可与 PlacesContextElement 微件搭配使用，以呈现情境数据。仅在启用了 Grounding with Google Maps 的情况下填充。

JSON 表示法 
{
  "groundingChunks": [
    {
      object (GroundingChunk)
    }
  ],
  "groundingSupports": [
    {
      object (GroundingSupport)
    }
  ],
  "webSearchQueries": [
    string
  ],
  "imageSearchQueries": [
    string
  ],
  "searchEntryPoint": {
    object (SearchEntryPoint)
  },
  "retrievalMetadata": {
    object (RetrievalMetadata)
  },
  "googleMapsWidgetContextToken": string
}

SearchEntryPoint

Google 搜索入口点。

字段
renderedContent string

可选。可嵌入到网页或应用 WebView 中的 Web 内容片段。

sdkBlob string (bytes format)

可选。Base64 编码的 JSON，表示 <搜索字词, search url> 元组的数组。

使用 base64 编码的字符串。

JSON 表示法 
{
  "renderedContent": string,
  "sdkBlob": string
}

GroundingChunk

GroundingChunk 表示支持模型回答的接地证据片段。它可以是来自网络的信息块、从文件中检索到的上下文，或来自 Google 地图的信息。

字段
chunk_type Union type
分块类型。以下是互斥字段列表。在响应中，最多只能设置其中一个字段：
web object (Web)

来自网络的接地分块。

image object (Image)

可选。来自图片搜索的接地分块。

retrievedContext object (RetrievedContext)

可选。文件搜索工具检索到的上下文中的接地分块。

maps object (Maps)

可选。来自 Google 地图的接地分块。

互斥字段结束。
JSON 表示法 
{

  // chunk_type
  "web": {
    object (Web)
  },
  "image": {
    object (Image)
  },
  "retrievedContext": {
    object (RetrievedContext)
  },
  "maps": {
    object (Maps)
  }
  // Union type
}

Web

来自网络的片段。

字段
uri string

仅限输出。数据块的 URI 引用。

title string

仅限输出。数据块的标题。

JSON 表示法 
{
  "uri": string,
  "title": string
}

映像

图片搜索结果中的片段。

字段
sourceUri string

用于归因的网页 URI。

imageUri string

图片素材资源网址。

title string

图片来源网页的标题。

domain string

图片来源网页的根域名，例如“example.com”。

JSON 表示法 
{
  "sourceUri": string,
  "imageUri": string,
  "title": string,
  "domain": string
}

RetrievedContext

文件搜索工具从上下文中检索到的分块。

字段
customMetadata[] object (CustomMetadata)

可选。用户提供的有关检索到的上下文的元数据。

uri string

可选。语义检索文档的 URI 引用。

title string

可选。文档的标题。

text string

可选。文本块的文本。

fileSearchStore string

可选。包含文档的 FileSearchStore 的名称。示例：fileSearchStores/123

pageNumber integer

可选。检索到的上下文的页码（如果适用）。

mediaId string

可选。多模态文件搜索结果的媒体 blob 资源名称。格式：fileSearchStores/{file_search_store_id}/media/{blobId}

JSON 表示法 
{
  "customMetadata": [
    {
      object (CustomMetadata)
    }
  ],
  "uri": string,
  "title": string,
  "text": string,
  "fileSearchStore": string,
  "pageNumber": integer,
  "mediaId": string
}

CustomMetadata

用户提供的有关 GroundingFact 的元数据。

字段
key string

元数据的键。

value Union type
元数据的值。可以是字符串、字符串列表或数字。以下是互斥字段列表。在响应中，最多只能设置其中一个字段：
stringValue string

可选。元数据的字符串值。

stringListValue object (StringList)

可选。元数据的字符串值列表。

numericValue number

可选。元数据的数值。此值的预期范围取决于所使用的具体 key。

互斥字段结束。
JSON 表示法 
{
  "key": string,

  // value
  "stringValue": string,
  "stringListValue": {
    object (StringList)
  },
  "numericValue": number
  // Union type
}

StringList

字符串值列表。

字段
values[] string

列表的字符串值。

JSON 表示法 
{
  "values": [
    string
  ]
}

地图

来自 Google 地图的接地分块。一个地图数据块对应一个地点。

字段
uri string

地点的 URI 引用。

title string

地点的名称。

text string

地点回答的文字说明。

placeId string

地点的 ID，采用 places/{placeId} 格式。用户可以使用此 ID 查找该地点。

placeAnswerSources object (PlaceAnswerSources)

提供有关 Google 地图中特定地点特征的回答的来源。

JSON 表示法 
{
  "uri": string,
  "title": string,
  "text": string,
  "placeId": string,
  "placeAnswerSources": {
    object (PlaceAnswerSources)
  }
}

PlaceAnswerSources

一系列来源，可提供有关 Google 地图中特定地点特征的回答。每条 PlaceAnswerSources 消息都对应 Google 地图中的一个特定地点。Google 地图工具使用这些来源来回答有关地点特征的问题（例如：“Bar Foo 有 Wi-Fi 吗？”或“Foo Bar 是否支持轮椅通行？”）。目前，我们仅支持将评价摘要作为来源。

字段
reviewSnippets[] object (ReviewSnippet)

用于生成 Google 地图中特定地点特征回答的评价片段。

JSON 表示法 
{
  "reviewSnippets": [
    {
      object (ReviewSnippet)
    }
  ]
}

ReviewSnippet

封装用户评价的摘要，用于回答有关 Google 地图中特定地点特征的问题。

字段
reviewId string

评价摘要的 ID。

googleMapsUri string

与 Google 地图上的用户评价对应的链接。

title string

评价的标题。

JSON 表示法 
{
  "reviewId": string,
  "googleMapsUri": string,
  "title": string
}

GroundingSupport

接地支持。

字段
groundingChunkIndices[] integer

可选。一个索引（指向 response.candidate.grounding_metadata 中的“grounding_chunk”）列表，用于指定与声明关联的引用。例如，[1,3,4] 表示 grounding_chunk[1]、grounding_chunk[3]、grounding_chunk[4] 是归因于声明的检索内容。如果回答是流式传输，则 groundingChunkIndices 是指所有回答中的索引。客户端负责累积所有响应中的接地分块（同时保持相同的顺序）。

confidenceScores[] number

可选。支持参考资料的置信度分数。范围是 0 到 1。1 表示最有信心。此列表的大小必须与 groundingChunkIndices 相同。

renderedParts[] integer

仅限输出。候选内容 parts 字段中的索引。这些索引指定了哪些渲染部分与此支持来源相关联。

segment object (Segment)

此支持所属的内容片段。

JSON 表示法 
{
  "groundingChunkIndices": [
    integer
  ],
  "confidenceScores": [
    number
  ],
  "renderedParts": [
    integer
  ],
  "segment": {
    object (Segment)
  }
}

Segment

内容片段。

字段
partIndex integer

Part 对象在其父 Content 对象中的索引。

startIndex integer

给定 Part 中的起始索引，以字节为单位。从 Part 开头算起的偏移量（含边界值），从零开始。

endIndex integer

给定 Part 中的结束索引（以字节为单位）。从 Part 开头算起的偏移量（不含），从 0 开始。

text string

与回答中的片段对应的文本。

JSON 表示法 
{
  "partIndex": integer,
  "startIndex": integer,
  "endIndex": integer,
  "text": string
}

RetrievalMetadata

与接地流程中的检索相关的元数据。

字段
googleSearchDynamicRetrievalScore number

可选。一个分数，表示 Google 搜索中的信息有助于回答提示的可能性。得分在 [0, 1] 范围内，其中 0 表示可能性最低，1 表示可能性最高。仅当启用 Google 搜索接地和动态检索时，系统才会填充此分数。系统会将该分数与阈值进行比较，以确定是否触发 Google 搜索。

JSON 表示法 
{
  "googleSearchDynamicRetrievalScore": number
}

LogprobsResult

Logprobs 结果

字段
topCandidates[] object (TopCandidates)

长度 = 解码步数总数。

chosenCandidates[] object (Candidate)

长度 = 解码步数总数。所选候选词元不一定在 topCandidates 中。

logProbabilitySum number

所有词元的对数概率之和。

JSON 表示法 
{
  "topCandidates": [
    {
      object (TopCandidates)
    }
  ],
  "chosenCandidates": [
    {
      object (Candidate)
    }
  ],
  "logProbabilitySum": number
}

TopCandidates

每个解码步骤中具有最高对数概率的候选词元。

字段
candidates[] object (Candidate)

按对数概率降序排序。

JSON 表示法 
{
  "candidates": [
    {
      object (Candidate)
    }
  ]
}

候选人

logprobs 词元和分数的候选。

字段
token string

候选词的词元字符串值。

tokenId integer

候选词元的 token ID 值。

logProbability number

候选词元的对数概率。

JSON 表示法 
{
  "token": string,
  "tokenId": integer,
  "logProbability": number
}

UrlContextMetadata

与网址上下文检索工具相关的元数据。

字段
urlMetadata[] object (UrlMetadata)

网址上下文列表。

JSON 表示法 
{
  "urlMetadata": [
    {
      object (UrlMetadata)
    }
  ]
}

UrlMetadata

单个网址检索的上下文。

字段
retrievedUrl string

工具检索到的网址。

urlRetrievalStatus enum (UrlRetrievalStatus)

网址检索的状态。

JSON 表示法 
{
  "retrievedUrl": string,
  "urlRetrievalStatus": enum (UrlRetrievalStatus)
}

UrlRetrievalStatus

网址检索的状态。

枚举
URL_RETRIEVAL_STATUS_UNSPECIFIED 默认值。此值未使用。
URL_RETRIEVAL_STATUS_SUCCESS 网址检索成功。
URL_RETRIEVAL_STATUS_ERROR 由于出错，网址检索失败。
URL_RETRIEVAL_STATUS_PAYWALL 由于内容受付费墙保护，网址检索失败。
URL_RETRIEVAL_STATUS_UNSAFE 由于内容不安全，网址检索失败。

CitationMetadata

一段内容的一组来源归因。

字段
citationSources[] object (CitationSource)

对特定回答的来源的引用。

JSON 表示法 
{
  "citationSources": [
    {
      object (CitationSource)
    }
  ]
}

CitationSource

对特定回答中某一部分的来源引用。

字段
startIndex integer

可选。归因于此来源的回答片段的开头。

指示片段起始位置的索引，以字节为单位。

endIndex integer

可选。归因段落的结束，不包括此索引。

uri string

可选。被归因为部分文本来源的 URI。

license string

可选。归因于片段来源的 GitHub 项目的许可。

代码引用需要提供许可信息。

JSON 表示法 
{
  "startIndex": integer,
  "endIndex": integer,
  "uri": string,
  "license": string
}

HarmCategory

分级类别。

这些类别涵盖了开发者可能希望调整的各种危害。

枚举
HARM_CATEGORY_UNSPECIFIED 未指定类别。
HARM_CATEGORY_DEROGATORY

PaLM - 针对身份和/或受保护属性的负面或有害评论。已弃用：仅限 PaLM 的类别，Gemini 模型不支持。
HARM_CATEGORY_TOXICITY

PaLM - 粗鲁、无礼或亵渎性的内容。已弃用：仅限 PaLM 的类别，Gemini 模型不支持。
HARM_CATEGORY_VIOLENCE

PaLM - 描述描绘针对个人或团体的暴力行为的场景，或一般性血腥描述。已弃用：仅限 PaLM 的类别，Gemini 模型不支持。
HARM_CATEGORY_SEXUAL

PaLM - 包含对性行为或其他淫秽内容的引用。已弃用：仅限 PaLM 的类别，Gemini 模型不支持。
HARM_CATEGORY_MEDICAL

PaLM - 宣传未经核实的医疗建议。已弃用：仅限 PaLM 的类别，Gemini 模型不支持。
HARM_CATEGORY_DANGEROUS

PaLM - 宣扬、助长或鼓励有害行为的危险内容。已弃用：仅限 PaLM 的类别，Gemini 模型不支持。
HARM_CATEGORY_HARASSMENT Gemini - 骚扰内容。
HARM_CATEGORY_HATE_SPEECH Gemini - 仇恨言论和内容。
HARM_CATEGORY_SEXUALLY_EXPLICIT Gemini - 露骨色情内容。
HARM_CATEGORY_DANGEROUS_CONTENT Gemini - 危险内容。
HARM_CATEGORY_CIVIC_INTEGRITY

Gemini - 可能用于损害公民诚信的内容。已弃用：请改用 enableEnhancedCivicAnswers。
HARM_CATEGORY_JAILBREAK Gemini - 试图绕过或破坏模型的安全准则的提示（越狱尝试）。

ModalityTokenCount

表示单个模态的 token 计数信息。

字段
modality enum (Modality)

与此 token 计数关联的模态。

tokenCount integer

词元数量。

JSON 表示法 
{
  "modality": enum (Modality),
  "tokenCount": integer
}

模态

内容部分模态

枚举
MODALITY_UNSPECIFIED 未指定模态。
TEXT 纯文本。
IMAGE 图片。
VIDEO 视频。
AUDIO 音频。
DOCUMENT 文档，例如 PDF。

SafetyRating

一段内容的安全评级。

安全评级包含内容的危害类别以及该类别中的危害概率级别。系统会根据多个危害类别对内容进行安全分类，此处会显示内容属于危害分类的概率。

字段
category enum (HarmCategory)

必需。此评分的类别。

probability enum (HarmProbability)

必需。此内容造成危害的概率。

blocked boolean

此内容是否因该分级而被屏蔽？

JSON 表示法 
{
  "category": enum (HarmCategory),
  "probability": enum (HarmProbability),
  "blocked": boolean
}

HarmProbability

内容有害的概率。

分类系统会给出内容不安全的概率。这并不表示某项内容的危害严重程度。

枚举
HARM_PROBABILITY_UNSPECIFIED 概率未指定。
NEGLIGIBLE 内容不安全的概率可忽略不计。
LOW 内容不安全的概率较低。
MEDIUM 内容不安全的可能性为中等。
HIGH 内容不安全的概率较高。

SafetySetting

安全设置，会影响安全屏蔽行为。

为某个类别传递安全设置会更改内容被屏蔽的允许概率。

字段
category enum (HarmCategory)

必需。此设置的类别。

threshold enum (HarmBlockThreshold)

必需。控制屏蔽有害内容的概率阈值。

JSON 表示法 
{
  "category": enum (HarmCategory),
  "threshold": enum (HarmBlockThreshold)
}

HarmBlockThreshold

在达到和超过指定的危害概率时屏蔽。

枚举
HARM_BLOCK_THRESHOLD_UNSPECIFIED 未指定阈值。
BLOCK_LOW_AND_ABOVE 允许发布具有 NEGLIGIBLE 级别的内容。
BLOCK_MEDIUM_AND_ABOVE 系统将允许发布具有“NEGLIGIBLE”和“LOW”级别的内容。
BLOCK_ONLY_HIGH 系统将允许显示可能性为“微乎其微”“低”和“中”的内容。
BLOCK_NONE 所有内容都将允许访问。
OFF 关闭安全过滤条件。

ServiceTier

请求的服务等级。

枚举
unspecified 默认服务层级，即标准层级。
standard 标准服务层级。
flex Flex 服务层级。
priority 优先服务层级。

内容

包含消息的多部分内容的基本结构化数据类型。

Content 包含一个指定 Content 提供方的 role 字段，以及一个包含多部分数据（其中包含消息轮次的内容）的 parts 字段。

字段
parts[] object (Part)

构成单条消息的有序 Parts。部分可能具有不同的 MIME 类型。

role string

可选。内容的提供方。必须是“user”或“model”。

对于多轮对话，此字段非常有用，否则可以留空或未设置。

JSON 表示法 
{
  "parts": [
    {
      object (Part)
    }
  ],
  "role": string
}

部分

包含属于多部分 Content 消息一部分的媒体的数据类型。

Part 由具有关联数据类型的数据组成。Part 只能包含 Part.data 中接受的一种类型。

如果 inlineData 字段填充了原始字节，则 Part 必须具有固定的 IANA MIME 类型，用于标识媒体的类型和子类型。

字段
thought boolean

可选。指明该部分是否由模型思考得出。

thoughtSignature string (bytes format)

可选。思考过程的不透明签名，以便在后续请求中重复使用。

使用 base64 编码的字符串。

partMetadata object (Struct format)

与 Part 关联的自定义元数据。使用 genai.Part 作为内容表示法的智能体可能需要跟踪这些额外信息。例如，它可以是 Part 来源的文件/来源的名称，也可以是多路复用多个 Part 流的方式。

mediaResolution object (MediaResolution)

可选。输入媒体的媒体分辨率。

mediaProcessing enum (MediaProcessing)

可选。模型如何处理此部分的媒体内容以进行理解。仅对视频部分（inlineData 或具有视频 MIME 的 fileData）有意义。非视频部分会忽略此字段。

audioTranscription object (AudioTranscription)

可选。音频（输入或输出）转写。仅当此 Part 包含音频数据时，才会设置此字段。

speechMetadata object (SpeechMetadata)

可选。应用于文本部分的元数据，用于自定义文本部分的朗读或合成方式，例如指定朗读者身份或朗读风格。

data Union type
以下是互斥字段列表。在响应中，最多只能设置其中一个字段：
text string

内嵌文本。

inlineData object (Blob)

内嵌媒体字节。

functionCall object (FunctionCall)

从模型返回的预测 FunctionCall，其中包含表示 FunctionDeclaration.name 的字符串以及实参及其值。

functionResponse object (FunctionResponse)

FunctionCall 的结果输出，其中包含表示 FunctionDeclaration.name 的字符串和包含函数任何输出的结构化 JSON 对象，用作模型的上下文。

fileData object (FileData)

基于 URI 的数据。

executableCode object (ExecutableCode)

由模型生成且旨在执行的代码。

codeExecutionResult object (CodeExecutionResult)

执行 ExecutableCode 的结果。

toolCall object (ToolCall)

服务器端工具调用。当模型预测到应在服务器上执行的工具调用时，系统会填充此字段。客户端应将此消息回显给 API。

toolResponse object (ToolResponse)

服务器端 ToolCall 执行的输出。此字段由客户端填充，其中包含执行相应 ToolCall 的结果。

互斥字段结束。
metadata Union type
控制数据的额外预处理。如果存在 inline_data 或 file_data，请设置此项，以便为每个部分配置静态媒体预处理。以下是互斥字段列表。在响应中，最多只能设置其中一个字段：
videoMetadata object (VideoMetadata)

可选。视频元数据。仅当视频数据以 inlineData 或 fileData 形式呈现时，才应指定元数据。

互斥字段结束。
JSON 表示法 
{
  "thought": boolean,
  "thoughtSignature": string,
  "partMetadata": {
    object
  },
  "mediaResolution": {
    object (MediaResolution)
  },
  "mediaProcessing": enum (MediaProcessing),
  "audioTranscription": {
    object (AudioTranscription)
  },
  "speechMetadata": {
    object (SpeechMetadata)
  },

  // data
  "text": string,
  "inlineData": {
    object (Blob)
  },
  "functionCall": {
    object (FunctionCall)
  },
  "functionResponse": {
    object (FunctionResponse)
  },
  "fileData": {
    object (FileData)
  },
  "executableCode": {
    object (ExecutableCode)
  },
  "codeExecutionResult": {
    object (CodeExecutionResult)
  },
  "toolCall": {
    object (ToolCall)
  },
  "toolResponse": {
    object (ToolResponse)
  }
  // Union type

  // metadata
  "videoMetadata": {
    object (VideoMetadata)
  }
  // Union type
}

Blob

原始媒体字节。

文本不应以原始字节形式发送，请使用“text”字段。

字段
mimeType string

来源数据的 IANA 标准 MIME 类型。支持的类型示例：- 图片：image/png、image/jpeg、image/jpg、image/webp、image/heic、image/heif、image/gif、image/avif - 音频：audio/*、video/audio/s16le、video/audio/wav - 视频：video/* - 文本：text/plain、text/html、text/css、text/javascript、text/x-typescript、text/csv、text/markdown、text/x-python、text/xml、text/rtf、video/text/timestamp - 应用：application/x-javascript、application/x-typescript、application/x-python-code、application/json、application/x-ipynb+json、application/rtf、application/pdf 如需了解更多背景信息，请参阅支持的文件格式。//

data string (bytes format)

媒体格式的原始字节。

使用 base64 编码的字符串。

displayName string

可选。指定在模型中引用此 blob 时使用的名称（例如“my_blob.png”）。当 verbalizationMode 设置为 REFERENCE_ONLY 时，用作 blob 引用标识符。

JSON 表示法 
{
  "mimeType": string,
  "data": string,
  "displayName": string
}

FunctionCall

从模型返回的预测 FunctionCall，其中包含表示 FunctionDeclaration.name 的字符串以及实参及其值。

字段
id string

可选。函数调用的唯一标识符。如果已填充，则客户端执行 functionCall 并返回具有匹配 id 的响应。

name string

必需。要调用的函数名称。必须是 a-z、A-Z、0-9 或包含下划线和短划线，长度上限为 128。

args object (Struct format)

可选。以 JSON 对象格式表示的函数参数和值。

JSON 表示法 
{
  "id": string,
  "name": string,
  "args": {
    object
  }
}

FunctionResponse

FunctionCall 的结果输出，其中包含表示 FunctionDeclaration.name 的字符串和包含函数任何输出的结构化 JSON 对象，用作模型的上下文。这应包含根据模型预测生成的FunctionCall的结果。

字段
id string

可选。此响应所针对的函数调用的标识符。由客户端填充，以匹配相应的函数调用 id。

name string

必需。要调用的函数名称。必须是 a-z、A-Z、0-9 或包含下划线和短划线，长度上限为 128。

response object (Struct format)

必需。以 JSON 对象格式表示的函数响应。调用方可以使用符合函数语法的任何键来返回函数输出，例如“output”“result”等。特别是，如果函数调用未能执行，回答可以包含“error”键，以便向模型返回错误详细信息。

您可以使用包含单个“$ref”键的子对象来添加多媒体，该键的值是包含多媒体的 FunctionResponsePart 的 inlineData.display_name。请参阅 https://ai.google.dev/gemini-api/docs/function-calling#multimodal。

parts[] object (FunctionResponsePart)

可选。构成函数响应的有序 Parts。不同部分可能具有不同的 IANA MIME 类型。

willContinue boolean

可选。表示函数调用会继续，并且会返回更多响应，从而将函数调用转换为生成器。仅适用于 NON_BLOCKING 函数调用，否则会被忽略。如果设为 false，系统将不会考虑未来的回答。允许返回空的 response 和 willContinue=False，以指示函数调用已完成。这可能仍会触发模型生成。为避免触发生成并完成函数调用，请额外将 scheduling 设置为 SILENT。

scheduling enum (Scheduling)

可选。指定应如何在对话中安排回答。仅适用于 NON_BLOCKING 函数调用，否则会被忽略。默认值为 WHEN_IDLE。

JSON 表示法 
{
  "id": string,
  "name": string,
  "response": {
    object
  },
  "parts": [
    {
      object (FunctionResponsePart)
    }
  ],
  "willContinue": boolean,
  "scheduling": enum (Scheduling)
}

FunctionResponsePart

包含属于 FunctionResponse 消息一部分的媒体的数据类型。

FunctionResponsePart 由具有关联数据类型的数据组成。FunctionResponsePart 只能包含 FunctionResponsePart.data 中接受的一种类型。

如果 inlineData 字段填充了原始字节，则 FunctionResponsePart 必须具有固定的 IANA MIME 类型，用于标识媒体的类型和子类型。

字段
data Union type
函数响应部分的数据。以下是互斥字段列表。在响应中，最多只能设置其中一个字段：
inlineData object (FunctionResponseBlob)

内嵌媒体字节。

互斥字段结束。
JSON 表示法 
{

  // data
  "inlineData": {
    object (FunctionResponseBlob)
  }
  // Union type
}

FunctionResponseBlob

函数响应的原始媒体字节。

文本不应以原始字节形式发送，请使用“FunctionResponse.response”字段。

字段
mimeType string

来源数据的 IANA 标准 MIME 类型。示例：- image/png - image/jpeg 如果提供的 MIME 类型不受支持，系统会返回错误。如需查看受支持类型的完整列表，请参阅支持的文件格式。

data string (bytes format)

媒体格式的原始字节。

使用 base64 编码的字符串。

JSON 表示法 
{
  "mimeType": string,
  "data": string
}

时间安排

指定应如何在对话中安排回答。

枚举
SCHEDULING_UNSPECIFIED 此值未使用。
SILENT 只需将结果添加到对话上下文中，不要中断或触发生成。
WHEN_IDLE 将结果添加到对话上下文中，并提示生成输出，而不会中断正在进行的生成。
INTERRUPT 将结果添加到对话上下文，中断正在进行的生成，并提示生成输出。

FileData

基于 URI 的数据。

字段
mimeType string

可选。来源数据的 IANA 标准 MIME 类型。

fileUri string

必需。URI。

displayName string

可选。指定向模型引用此文件时使用的名称（例如“my_file.pdf”）。当 verbalizationMode 设置为 REFERENCE_ONLY 时，用作文件引用标识符。

JSON 表示法 
{
  "mimeType": string,
  "fileUri": string,
  "displayName": string
}

ExecutableCode

由模型生成且旨在执行的代码，以及返回给模型的结果。

仅在使用 CodeExecution 工具时生成，其中代码将自动执行，并且还会生成相应的 CodeExecutionResult。

字段
id string

可选。ExecutableCode 部分的唯一标识符。服务器返回具有匹配 id 的 CodeExecutionResult。

language enum (Language)

必需。code 的编程语言。

code string

必需。要执行的代码。

JSON 表示法 
{
  "id": string,
  "language": enum (Language),
  "code": string
}

语言

生成的代码支持的编程语言。

枚举
LANGUAGE_UNSPECIFIED 未指定语言。不应使用此值。
PYTHON Python >= 3.10，且 numpy 和 simpy 可用。Python 是默认语言。

CodeExecutionResult

执行 ExecutableCode 的结果。

仅在使用 CodeExecution 工具时生成。

字段
id string

可选。此结果对应的 ExecutableCode 部分的标识符。仅在对应的 ExecutableCode 具有 ID 时填充。

outcome enum (Outcome)

必需。代码执行的结果。

output string

可选。如果代码执行成功，则包含 stdout，否则包含 stderr 或其他说明。

JSON 表示法 
{
  "id": string,
  "outcome": enum (Outcome),
  "output": string
}

结果

代码执行可能结果的枚举。

枚举
OUTCOME_UNSPECIFIED 未指定状态。不应使用此值。
OUTCOME_OK 代码执行已成功完成。output 包含 stdout（如果有）。
OUTCOME_FAILED 代码执行失败。output 包含 stderr 和 stdout（如果有）。
OUTCOME_DEADLINE_EXCEEDED 代码执行时间过长，已被取消。可能会有部分 output。

ToolCall

模型返回的预测服务器端 ToolCall。此消息包含有关模型要调用的工具的信息。客户端不应执行此 ToolCall。相反，客户端应在后续轮次中，通过 Content 消息将此 ToolCall 连同相应的 ToolResponse 一起传回 API。

字段
id string

可选。工具调用的唯一标识符。服务器返回具有匹配 id 的工具响应。

toolName string

可选。所调用工具的名称。

toolType enum (ToolType)

必需。所调用的工具的类型。

args object (Struct format)

可选。工具调用参数。示例：{"arg1" : "value1", "arg2" : "value2" , …}

JSON 表示法 
{
  "id": string,
  "toolName": string,
  "toolType": enum (ToolType),
  "args": {
    object
  }
}

ToolType

函数调用中的工具类型。

枚举
TOOL_TYPE_UNSPECIFIED 未指定工具类型。
GOOGLE_SEARCH_WEB Google 搜索工具，映射到 Tool.google_search.search_types.web_search。
GOOGLE_SEARCH_IMAGE 图片搜索工具，映射到 Tool.google_search.search_types.image_search。
URL_CONTEXT 网址上下文工具，映射到 Tool.url_context。
GOOGLE_MAPS Google 地图工具，映射到 Tool.google_maps。

ToolResponse

服务器端 ToolCall 执行的输出。此消息包含由模型中的 ToolCall 发起的工具调用结果。客户端应在后续轮次中，通过 Content 消息将此 ToolResponse 连同相应的 ToolCall 一起传回 API。

字段
id string

可选。此响应所针对的工具调用的标识符。

toolType enum (ToolType)

必需。调用的工具类型，与相应 ToolCall 中的 toolType 匹配。

response object (Struct format)

可选。工具响应。

JSON 表示法 
{
  "id": string,
  "toolType": enum (ToolType),
  "response": {
    object
  }
}

VideoMetadata

元数据用于描述输入视频内容。当 inlineData 或 fileData 包含视频时，请在 Part.video_metadata 或 FunctionResponsePart.video_metadata 中设置此参数，以配置静态视频预处理（例如时间剪辑、帧速率、最大帧数或提取的内容层）。

字段
startOffset string (Duration format)

可选。视频的起始偏移量。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。

endOffset string (Duration format)

可选。视频的结束偏移量。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。

fps number

可选。发送给模型的视频的帧速率。如果未指定，则默认值为 1.0。fps 范围为 (0.0, 24.0]。

JSON 表示法 
{
  "startOffset": string,
  "endOffset": string,
  "fps": number
}

MediaResolution

用于词元化的媒体分辨率。

字段
value Union type
媒体分辨率级别。以下是互斥字段列表。在响应中，最多只能设置其中一个字段：
level enum (Level)

用于给定媒体的标记化质量。 ，以获取 Gemini API 支持。

互斥字段结束。
JSON 表示法 
{

  // value
  "level": enum (Level)
  // Union type
}

级别

媒体分辨率级别。

枚举
MEDIA_RESOLUTION_UNSPECIFIED 尚未设置媒体分辨率。
MEDIA_RESOLUTION_LOW 媒体分辨率已设为低。
MEDIA_RESOLUTION_MEDIUM 媒体分辨率已设为中等。
MEDIA_RESOLUTION_HIGH 媒体分辨率已设为高。
MEDIA_RESOLUTION_ULTRA_HIGH 媒体分辨率已设为超高。

MediaProcessing

模型如何处理输入媒体以进行理解。

枚举
MEDIA_PROCESSING_UNSPECIFIED 默认采用特定于模型的处理方式。
STATIC 固定速率帧提取。所有帧都置于上下文中。
AGENTIC 模型驱动的动态导航。适合大多数使用场景。

AudioTranscription

音频部分的转写内容。对于多说话者音频，每个说话者片段都是一个单独的 Part，具有自己的 AudioTranscription，其中包含 speakerLabel。

字段
text string

必需。此音频片段的转写文本。

speakerLabel string

可选。用于标识此音频片段说话者的标签（例如“spk_1”“spk_2”）。在设置了说话者标识时显示。

words[] object (WordInfo)

可选。详细的字词级转写和时间详情。在设置 wordTimestamp 时显示。

JSON 表示法 
{
  "text": string,
  "speakerLabel": string,
  "words": [
    {
      object (WordInfo)
    }
  ]
}

WordInfo

有关单个识别出的字词的信息。

字段
word string

必需。字词的转写。

startOffset string (Duration format)

可选。字词相对于音频开头的时间偏移。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。

endOffset string (Duration format)

可选。字词相对于音频开头的时间结束偏移量。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。

JSON 表示法 
{
  "word": string,
  "startOffset": string,
  "endOffset": string
}

SpeechMetadata

text 部分的语音元数据。

字段
speaker string

可选。多说话者合成的可选说话者名称。

style string

可选。语音合成的可选样式指令。

JSON 表示法 
{
  "speaker": string,
  "style": string
}

环境

智能体的执行环境。

字段
id string

必需。仅限输出。环境的 ID。

sources[] object (Source)

要装载到环境中的来源。

created string

仅限输出。环境的创建时间，采用 ISO 8601 格式 (YYYY-MM-DDThh:mm:ssZ)。

updated string

仅限输出。环境的上次更新时间，采用 ISO 8601 格式 (YYYY-MM-DDThh:mm:ssZ)。

lastAccessed string

仅限输出。上次访问环境的时间，采用 ISO 8601 格式 (YYYY-MM-DDThh:mm:ssZ)。

status enum (Status)

仅限输出。环境容器的状态。

fileCount string (int64 format)

仅限输出。环境中的文件数量，仅供输出。

sizeBytes string (int64 format)

仅限输出。环境文件的总大小（以字节为单位），仅供输出。

network Union type
环境的网络配置。以下是互斥字段列表。在响应中，最多只能设置其中一个字段：
networkAllowlist object (EnvironmentNetworkEgressAllowlist)

仅允许特定网域。

networkMode enum (NetworkMode)

网络出站流量模式。

互斥字段结束。
JSON 表示法 
{
  "id": string,
  "sources": [
    {
      object (Source)
    }
  ],
  "created": string,
  "updated": string,
  "lastAccessed": string,
  "status": enum (Status),
  "fileCount": string,
  "sizeBytes": string,

  // network
  "networkAllowlist": {
    object (EnvironmentNetworkEgressAllowlist)
  },
  "networkMode": enum (NetworkMode)
  // Union type
}

状态

环境的状态。

枚举
STATUS_UNSPECIFIED
ACTIVE
EXPIRED

NetworkMode

非许可清单配置的网络出站流量模式。

枚举
NETWORK_MODE_UNSPECIFIED 默认值。未使用。
DISABLED 所有网络出站流量都会被屏蔽。

架构

Schema 对象允许定义输入和输出数据类型。这些类型可以是对象，也可以是基元和数组。表示 OpenAPI 3.0 架构对象的选定子集。

字段
type enum (Type)

必需。数据类型。

format string

可选。数据的格式。允许使用任何值，但大多数值不会触发任何特殊功能。

title string

可选。架构的标题。

description string

可选。参数的简要说明。其中可能包含使用示例。参数说明可以采用 Markdown 格式。

nullable boolean

可选。指示值是否为 null。

enum[] string

可选。Type.STRING 类型的元素可能的具有枚举格式的值。例如，我们可以将 Enum 方向定义为：{type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]}

maxItems string (int64 format)

可选。Type.ARRAY 的元素数量上限。

minItems string (int64 format)

可选。Type.ARRAY 的元素数量下限。

properties map (key: string, value: object (Schema))

可选。Type.OBJECT 的属性。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。

required[] string

可选。Type.OBJECT 的必要属性。

minProperties string (int64 format)

可选。Type.OBJECT 的属性数量下限。

maxProperties string (int64 format)

可选。Type.OBJECT 的属性数量上限。

minLength string (int64 format)

可选。SCHEMA FIELDS FOR TYPE STRING Minimum length of the Type.STRING

maxLength string (int64 format)

可选。Type.STRING 的长度上限

pattern string

可选。Type.STRING 的模式，用于将字符串限制为正则表达式。

example value (Value format)

可选。对象示例。仅当对象为根时才会填充。

anyOf[] object (Schema)

可选。应根据列表中的任何（一个或多个）子架构验证该值。

propertyOrdering[] string

可选。属性的顺序。不是 OpenAPI 规范中的标准字段。用于确定响应中属性的顺序。

default value (Value format)

可选。字段的默认值。根据 JSON 架构，此字段适用于文档生成器，不会影响验证。因此，我们在此处添加了该字段并将其忽略，以便发送包含 default 字段的架构的开发者不会收到未知字段错误。

items object (Schema)

可选。Type.ARRAY 元素的架构。

minimum number

可选。类型为 INTEGER 和 NUMBER 的架构字段。Type.INTEGER 和 Type.NUMBER 的最小值

maximum number

可选。Type.INTEGER 和 Type.NUMBER 的最大值

JSON 表示法 
{
  "type": enum (Type),
  "format": string,
  "title": string,
  "description": string,
  "nullable": boolean,
  "enum": [
    string
  ],
  "maxItems": string,
  "minItems": string,
  "properties": {
    string: {
      object (Schema)
    },
    ...
  },
  "required": [
    string
  ],
  "minProperties": string,
  "maxProperties": string,
  "minLength": string,
  "maxLength": string,
  "pattern": string,
  "example": value,
  "anyOf": [
    {
      object (Schema)
    }
  ],
  "propertyOrdering": [
    string
  ],
  "default": value,
  "items": {
    object (Schema)
  },
  "minimum": number,
  "maximum": number
}

类型

Type 包含 https://spec.openapis.org/oas/v3.0.3#data-types 定义的 OpenAPI 数据类型列表

枚举
TYPE_UNSPECIFIED 未指定，不应使用。
STRING 字符串类型。
NUMBER 数字类型。
INTEGER 整数类型。
BOOLEAN 布尔值类型。
ARRAY 数组类型。
OBJECT 对象类型。
NULL Null 类型。

工具

模型可能用于生成回答的工具详细信息。

Tool 是一段代码，可让系统与外部系统进行交互，以在模型知识和范围之外执行操作或一组操作。

字段
functionDeclarations[] object (FunctionDeclaration)

可选。模型可用于函数调用的 FunctionDeclarations 列表。

模型或系统不会执行该函数。而是将定义的函数作为 FunctionCall 连同参数一起返回到客户端执行。模型可能会决定通过在回答中填充 FunctionCall 来调用这些函数的一部分。下一个对话轮次可能包含一个 FunctionResponse，其中包含下一个模型轮次的 Content.role“函数”生成上下文。

googleSearchRetrieval object (GoogleSearchRetrieval)

可选。由 Google 搜索提供支持的检索工具。

codeExecution object (CodeExecution)

可选。使模型能够在生成过程中执行代码。

computerUse object (ComputerUse)

可选。支持模型直接与计算机交互的工具。如果启用，系统会自动填充计算机使用场景专用的函数声明。

urlContext object (UrlContext)

可选。用于支持网址上下文检索的工具。

mcpServers[] object (McpServer)

可选。要连接的 MCP 服务器。

googleMaps object (GoogleMaps)

可选。此工具可让模型根据与用户查询相关的地理空间上下文来提供回答。

JSON 表示法 
{
  "functionDeclarations": [
    {
      object (FunctionDeclaration)
    }
  ],
  "googleSearchRetrieval": {
    object (GoogleSearchRetrieval)
  },
  "codeExecution": {
    object (CodeExecution)
  },
  "googleSearch": {
    object (GoogleSearch)
  },
  "computerUse": {
    object (ComputerUse)
  },
  "urlContext": {
    object (UrlContext)
  },
  "fileSearch": {
    object (FileSearch)
  },
  "mcpServers": [
    {
      object (McpServer)
    }
  ],
  "googleMaps": {
    object (GoogleMaps)
  }
}

FunctionDeclaration

OpenAPI 3.03 规范定义的函数声明的结构化表示法。此声明中包含函数名称和参数。此 FunctionDeclaration 表示一个代码块，可由模型用作 Tool 并由客户端执行。

字段
name string

必需。函数的名称。必须是 a-z、A-Z、0-9 或包含下划线、英文冒号、英文句点和短划线，长度上限为 128。

description string

必需。函数的简要说明。

behavior enum (Behavior)

可选。指定函数行为。目前仅受 BidiGenerateContent 方法支持。

parameters object (Schema)

可选。描述此函数的参数。反映 Open API 3.03 参数对象字符串键：参数的名称。参数名称区分大小写。架构值：定义参数所用类型的架构。

parametersJsonSchema value (Value format)

可选。以 JSON 架构格式描述函数的参数。该架构必须描述一个对象，其中属性是函数的参数。例如：

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer" }
  },
  "additionalProperties": false,
  "required": ["name", "age"],
  "propertyOrdering": ["name", "age"]
}

此字段与 parameters 互斥。

response object (Schema)

可选。以 JSON 架构格式描述此函数的输出。反映 Open API 3.03 响应对象。Schema 定义了函数响应值所使用的类型。

responseJsonSchema value (Value format)

可选。以 JSON 架构格式描述此函数的输出。架构指定的值是函数的响应值。

此字段与 response 互斥。

JSON 表示法 
{
  "name": string,
  "description": string,
  "behavior": enum (Behavior),
  "parameters": {
    object (Schema)
  },
  "parametersJsonSchema": value,
  "response": {
    object (Schema)
  },
  "responseJsonSchema": value
}

行为

定义函数行为。默认为 BLOCKING。

枚举
UNSPECIFIED 此值未使用。
BLOCKING 如果设置了此参数，系统会等待收到函数响应，然后再继续对话。
NON_BLOCKING 如果设置了此参数，系统将不会等待接收函数响应。而是会在用户和模型之间保持对话的同时，尝试在函数响应可用时进行处理。

GoogleSearchRetrieval

由 Google 提供支持的工具，用于检索公开 Web 数据以建立依据。

字段
dynamicRetrievalConfig object (DynamicRetrievalConfig)

指定给定来源的动态检索配置。

JSON 表示法 
{
  "dynamicRetrievalConfig": {
    object (DynamicRetrievalConfig)
  }
}

DynamicRetrievalConfig

介绍用于自定义动态检索的选项。

字段
mode enum (Mode)

要在动态检索中使用的预测器的模式。

dynamicThreshold number

要在动态检索中使用的阈值。如果未设置，则系统会使用默认值。

JSON 表示法 
{
  "mode": enum (Mode),
  "dynamicThreshold": number
}

模式

要在动态检索中使用的预测器的模式。

枚举
MODE_UNSPECIFIED 始终触发检索。
MODE_DYNAMIC 仅在系统认为有必要时才运行检索。

CodeExecution

此类型没有字段。

用于执行模型生成的代码并自动将结果返回给模型的工具。

另请参阅 ExecutableCode 和 CodeExecutionResult，它们仅在使用此工具时生成。

GoogleSearch

GoogleSearch 工具类型。用于在模型中支持 Google 搜索的工具。由 Google 提供支持。

字段
timeRangeFilter object (Interval)

可选。将搜索结果过滤为特定时间范围内的结果。如果客户设置了开始时间，则必须设置结束时间（反之亦然）。

searchTypes object (SearchTypes)

可选。要启用的搜索类型集。如果未设置，则默认启用网页搜索。

JSON 表示法 
{
  "timeRangeFilter": {
    object (Interval)
  },
  "searchTypes": {
    object (SearchTypes)
  }
}

间隔

表示时间间隔，以开始时间戳（含）和结束时间戳（不含）的形式编码。

开始时间必须早于或等于结束时间。如果开始时间与结束时间相同，则时间间隔为空（不会匹配任何时间）。如果开始时间和结束时间都未指定，则时间间隔会匹配任何时间。

字段
startTime string (Timestamp format)

可选。时间间隔的开始时间（含）。

如果指定，则与此时间间隔匹配的时间戳必须等于或晚于开始时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不进行“Z”归一化处理的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

endTime string (Timestamp format)

可选。时间间隔的结束时间（不含）。

如果指定，则与此时间间隔匹配的时间戳必须早于结束时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不进行“Z”归一化处理的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

JSON 表示法 
{
  "startTime": string,
  "endTime": string
}

SearchTypes

可在 GoogleSearch 工具中启用的不同搜索类型。

字段
JSON 表示法 
{
  "webSearch": {
    object (WebSearch)
  },
  "imageSearch": {
    object (ImageSearch)
  }
}

WebSearch

此类型没有字段。

用于接地和相关配置的标准网页搜索。

ImageSearch

此类型没有字段。

用于建立依据和相关配置的图片搜索。

ComputerUse

“计算机使用”工具类型。

字段
environment enum (Environment)

必需。正在操作的环境。

excludedPredefinedFunctions[] string

可选。默认情况下，最终模型调用中会包含预定义函数。其中一些可以明确排除，不自动包含。这有两个用途：1. 使用更受限 / 不同的操作空间。2. 改进了预定义函数的定义 / 说明。

enablePromptInjectionDetection boolean

可选。是否在计算机使用请求中启用提示词注入检测检查。

disabledSafetyPolicies[] enum (SafetyPolicy)

可选。停用了计算机使用安全政策。

JSON 表示法 
{
  "environment": enum (Environment),
  "excludedPredefinedFunctions": [
    string
  ],
  "enablePromptInjectionDetection": boolean,
  "disabledSafetyPolicies": [
    enum (SafetyPolicy)
  ]
}

环境

表示正在操作的环境，例如网络浏览器。

枚举
ENVIRONMENT_UNSPECIFIED 默认值为 browser。
ENVIRONMENT_BROWSER 在网络浏览器中运行。
ENVIRONMENT_MOBILE 在移动环境中运行。
ENVIRONMENT_DESKTOP 在桌面环境中运行。

SafetyPolicy

预定义的计算机使用安全政策。

枚举
SAFETY_POLICY_UNSPECIFIED 未指定安全政策。
FINANCIAL_TRANSACTIONS 金融交易安全政策。
SENSITIVE_DATA_MODIFICATION 敏感数据修改的安全政策。
COMMUNICATION_TOOL 通信工具（例如 Gmail、Chat、Meet）的安全政策。
ACCOUNT_CREATION 账号创建安全政策。
DATA_MODIFICATION 数据修改安全政策。
LEGAL_TERMS_AND_AGREEMENTS 法律条款和协议的安全政策。

UrlContext

此类型没有字段。

用于支持网址上下文检索的工具。

FileSearch

FileSearch 工具，用于从语义检索语料库中检索知识。文件会使用 ImportFile API 导入到语义检索语料库中。

字段
fileSearchStoreNames[] string

必需。要从中检索的 fileSearchStore 的名称。示例：fileSearchStores/my-file-search-store-123

metadataFilter string

可选。要应用于语义检索文档和分块的元数据过滤条件。

topK integer

可选。要检索的语义检索块数量。

JSON 表示法 
{
  "fileSearchStoreNames": [
    string
  ],
  "metadataFilter": string,
  "topK": integer
}

McpServer

MCPServer 是一个可由模型调用以执行操作的服务器。它是一个实现 MCP 协议的服务器。

字段
name string

MCPServer 的名称。

transport Union type
用于连接到 MCPServer 的传输协议。以下是互斥字段列表。在响应中，最多只能设置其中一个字段：
streamableHttpTransport object (StreamableHttpTransport)

一种可以流式传输 HTTP 请求和响应的传输。

互斥字段结束。
JSON 表示法 
{
  "name": string,

  // transport
  "streamableHttpTransport": {
    object (StreamableHttpTransport)
  }
  // Union type
}

StreamableHttpTransport

一种可以流式传输 HTTP 请求和响应的传输。

字段
url string

MCPServer 端点的完整网址。示例：“https://api.example.com/mcp”

headers map (key: string, value: string)

可选：身份验证标头、超时等字段（如有需要）。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。

timeout string (Duration format)

常规操作的 HTTP 超时。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。

sseReadTimeout string (Duration format)

SSE 读取操作的超时时间。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。

terminateOnClose boolean

是否在传输关闭时关闭客户端会话。

JSON 表示法 
{
  "url": string,
  "headers": {
    string: string,
    ...
  },
  "timeout": string,
  "sseReadTimeout": string,
  "terminateOnClose": boolean
}

GoogleMaps

GoogleMaps 工具，可为用户的查询提供地理空间上下文。

字段
enableWidget boolean

可选。是否在回答的 GroundingMetadata 中返回 widget 上下文 token。开发者可以使用 widget 上下文 token 来呈现 Google 地图 widget，其中包含与模型在回答中引用的地点相关的地理空间上下文。

JSON 表示法 
{
  "enableWidget": boolean
}

REST 资源：auth_tokens

资源：AuthToken

创建临时身份验证令牌的请求。

字段
name string

仅限输出。标识符。令牌本身。

expireTime string (Timestamp format)

可选。仅限输入。不可变。一个可选时间，在此时间之后，如果使用生成的令牌，BidiGenerateContent 会话中的消息将被拒绝。（Gemini 可能会在此时间之后提前关闭会话。）

如果未设置，则默认为未来 30 分钟。如果设置了此值，则该值必须小于 20 小时。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不进行“Z”归一化处理的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

newSessionExpireTime string (Timestamp format)

可选。仅限输入。不可变。在此时间之后，使用此请求生成的令牌的新 Live API 会话将被拒绝。

如果未设置，则默认为未来 60 秒。如果设置了此值，则该值必须小于未来 20 小时。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不进行“Z”归一化处理的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

fieldMask string (FieldMask format)

可选。仅限输入。不可变。如果 fieldMask 为空，并且 bidiGenerateContentSetup 不存在，则有效的 BidiGenerateContentSetup 消息将从 Live API 连接中获取。

如果 fieldMask 为空，并且 bidiGenerateContentSetup 存在，则有效的 BidiGenerateContentSetup 消息将完全取自此请求中的 bidiGenerateContentSetup。来自 Live API 连接的设置消息会被忽略。

如果 fieldMask 不为空，则 bidiGenerateContentSetup 中的相应字段将覆盖 Live API 连接中设置消息中的字段。

这是完全限定字段名称的逗号分隔列表。示例："user.displayName,photo"。

config Union type
生成的令牌的方法特定配置。以下是互斥字段列表。在响应中，最多只能设置其中一个字段：
bidiGenerateContentSetup object (BidiGenerateContentSetup)

可选。仅限输入。不可变。BidiGenerateContent 专属配置。

互斥字段结束。
uses integer

可选。仅限输入。不可变。令牌可使用的次数。如果此值为零，则不应用任何限制。恢复 Live API 会话不计为一次使用。如果未指定，则默认值为 1。

JSON 表示法 
{
  "name": string,
  "expireTime": string,
  "newSessionExpireTime": string,
  "fieldMask": string,

  // config
  "bidiGenerateContentSetup": {
    object (BidiGenerateContentSetup)
  }
  // Union type
  "uses": integer
}

BidiGenerateContentSetup

要在第一条（且仅在第一条）BidiGenerateContentClientMessage 中发送的消息。包含将在整个流式 RPC 期间应用的配置。

客户端应先等待 BidiGenerateContentSetupComplete 消息，然后再发送任何其他消息。

字段
model string

必需。模型的资源名称。此名称用作要使用的模型的 ID。

格式：models/{model}

generationConfig object (GenerationConfig)

可选。生成配置。

不支持以下字段：

  • responseLogprobs
  • responseMimeType
  • logprobs
  • responseSchema
  • responseJsonSchema
  • stop_sequence
  • skipResponseCache
  • routing_config
  • audio_timestamp
systemInstruction object (Content)

可选。用户为模型提供的系统指令。

注意：各部分中只能使用文本，并且每个部分中的内容都将位于单独的段落中。

tools[] object (Tool)

可选。模型可能用于生成下一个回答的 Tools 列表。

Tool 是一段代码，可让系统与外部系统进行交互，以在模型知识和范围之外执行操作或一组操作。

realtimeInputConfig object (RealtimeInputConfig)

可选。配置实时输入的处理。

sessionResumption object (SessionResumptionConfig)

可选。配置会话恢复机制。

如果包含，服务器将发送 SessionResumptionUpdate 消息。

contextWindowCompression object (ContextWindowCompressionConfig)

可选。配置上下文窗口压缩机制。

如果包含此参数，当上下文超出配置的长度时，服务器会自动缩减上下文的大小。

inputAudioTranscription object (AudioTranscriptionConfig)

可选。如果设置，则启用语音输入转写功能。转写内容与输入音频语言（如果已配置）保持一致。

outputAudioTranscription object (AudioTranscriptionConfig)

可选。如果设置，则会启用模型音频输出的转写功能。转写内容与为输出音频指定的语言代码（如果已配置）保持一致。

historyConfig object (HistoryConfig)

可选。配置客户端与服务器之间的历史记录交换。

labels map (key: string, value: string)

可选。请求的带有用户定义元数据的标签。

可选。标签必须遵循标准的统一 Cloud 标签要求：- 标签键必须以字母开头。- 标签键和值不得超过 63 个字符（Unicode 代码点），并且只能包含小写字母、数字字符、下划线和短划线。- 允许使用国际字符。

用法：- 聚合器的安全标识符：使用键 safety_identifier（例如 {"safety_identifier": "user_session_123"}）

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。

JSON 表示法 
{
  "model": string,
  "generationConfig": {
    object (GenerationConfig)
  },
  "systemInstruction": {
    object (Content)
  },
  "tools": [
    {
      object (Tool)
    }
  ],
  "realtimeInputConfig": {
    object (RealtimeInputConfig)
  },
  "sessionResumption": {
    object (SessionResumptionConfig)
  },
  "contextWindowCompression": {
    object (ContextWindowCompressionConfig)
  },
  "inputAudioTranscription": {
    object (AudioTranscriptionConfig)
  },
  "outputAudioTranscription": {
    object (AudioTranscriptionConfig)
  },
  "historyConfig": {
    object (HistoryConfig)
  },
  "labels": {
    string: string,
    ...
  }
}

GenerationConfig

模型生成和输出的配置选项。并非所有参数都可针对每个模型进行配置。

字段
stopSequences[] string

可选。一组字符序列（最多 5 个），用于停止生成输出。如果指定了此参数，API 将在 stop_sequence 首次出现时停止。停止序列不会包含在回答中。

responseMimeType string

可选。生成的候选文本的 MIME 类型。支持的 MIME 类型包括：text/plain：（默认）文本输出。application/json：回答候选项中的 JSON 响应。text/x.enum：回答候选项中以字符串形式返回的枚举值。如需查看所有受支持的文本 MIME 类型的列表，请参阅文档。

responseSchema
(deprecated) object (Schema)

可选。生成的候选文本的输出架构。架构必须是 OpenAPI 架构的子集，可以是对象、基元或数组。

如果设置了此字段，则还必须设置兼容的 responseMimeType。兼容的 MIME 类型：application/json：JSON 响应的架构。如需了解详情，请参阅 JSON 文本生成指南。

已弃用。请改用 responseFormat。

_responseJsonSchema
(deprecated) value (Value format)

可选。生成的回答的输出架构。这是 responseSchema 的替代方案，可接受 JSON 架构。

如果设置了此字段，则必须省略 responseSchema，但 responseMimeType 是必需的。

虽然可以发送完整的 JSON 架构，但并非所有功能都受支持。具体而言，仅支持以下属性：

  • $id
  • $defs
  • $ref
  • $anchor
  • type
  • format
  • title
  • description
  • enum（适用于字符串和数字）
  • items
  • prefixItems
  • minItems
  • maxItems
  • minimum
  • maximum
  • anyOf
  • oneOf（解读方式与 anyOf 相同）
  • properties
  • additionalProperties
  • required

您也可以设置非标准 propertyOrdering 属性。

循环引用在一定程度上会展开，因此只能在非必需属性中使用。（仅使用可为 null 的属性是不够的。）如果在子架构上设置了 $ref，则除了以 $ 开头的属性外，不得设置任何其他属性。

已弃用。请改用 responseFormat。

responseJsonSchema value (Value format)

可选。内部细节。请使用 responseJsonSchema，而不是此字段。

responseModalities[] enum (Modality)

可选。请求的回答模态。表示模型可以返回且应在回答中预期的模态集。这与回答的模态完全一致。

一个模型可能支持多种模态组合。如果请求的模态与任何受支持的组合都不匹配，系统将返回错误。

空列表等同于仅请求文本。

candidateCount integer

可选。要返回的生成回答的数量。如果未设置，则默认为 1。请注意，这不适用于上一代模型（Gemini 1.0 系列）

maxOutputTokens integer

可选。候选回答中要包含的词元数量上限。

注意：默认值因模型而异，请参阅 getModel 函数返回的 Model 的 Model.output_token_limit 属性。

temperature number

可选。控制输出的随机性。

注意：默认值因模型而异，请参阅 getModel 函数返回的 Model 的 Model.temperature 属性。

值范围为 [0.0, 2.0]。

此字段已不再受支持，在 Gemini 3.6 Flash 及更新的模型中会被静默忽略。

topP number

可选。采样时要考虑的词元的最大累积概率。

该模型结合使用 Top-k 和 Top-p（核）采样。

系统会根据分配的概率对词元进行排序，以便仅考虑最有可能的词元。Top-k 采样直接限制要考虑的 token 数量上限，而核采样则根据累积概率限制 token 数量。

注意：默认值因 Model 而异，由 getModel 函数返回的 Model.top_p 属性指定。topK 属性为空表示模型不应用 top-k 采样，也不允许在请求中设置 topK。

此字段已不再受支持，在 Gemini 3.6 Flash 及更新的模型中会被静默忽略。

topK integer

可选。采样时要考虑的词元数量上限。

Gemini 模型使用 Top-p（核）采样或 Top-k 和核采样的组合。Top-k 采样会考虑 topK 个最可能的词元。使用核采样运行的模型不允许设置 topK。

注意：默认值因 Model 而异，由 getModel 函数返回的 Model.top_p 属性指定。topK 属性为空表示模型不应用 top-k 采样，也不允许在请求中设置 topK。

此字段已不再受支持，在 Gemini 3.6 Flash 及更新的模型中会被静默忽略。

seed integer

可选。解码中使用的种子。如果未设置，请求会使用随机生成的种子。

presencePenalty number

可选。如果下一个词元已在回答中出现过，则对其 logprob 应用存在惩罚。

此惩罚是二元开关，不取决于词元的使用次数（首次使用之后）。使用 frequencyPenalty 可设置每次使用时都会增加的惩罚。

正数惩罚会阻止使用已在回答中使用的词元，从而增加词汇量。

负惩罚会鼓励使用已在回答中使用过的词元，从而减少词汇量。

frequencyPenalty number

可选。应用于下一个词元的 logprob 的频率惩罚，乘以到目前为止每个词元在回答中出现的次数。

正惩罚会阻止使用已使用的 token，其比例与 token 的使用次数成正比：token 的使用次数越多，模型就越难再次使用该 token，从而增加回答的词汇量。

注意：负惩罚会鼓励模型重复使用 token，重复使用的次数与 token 已使用的次数成正比。较小的负值会减少回答的词汇量。负值越大，模型就越会开始重复常见词元，直到达到 maxOutputTokens 限制。

responseLogprobs boolean

可选。如果为 true，则在回答中导出 logprobs 结果。

logprobs integer

可选。仅在 responseLogprobs=True 时有效。此参数用于设置在 Candidate.logprobs_result 的每个解码步骤中要返回的排名靠前的 logprob 数量（包括所选候选词元）。该数字必须在 [0, 20] 范围内。

enableEnhancedCivicAnswers boolean

可选。启用增强型公民信息回答。此功能可能仅适用于部分型号。

speechConfig object (SpeechConfig)

可选。语音生成配置。

thinkingConfig object (ThinkingConfig)

可选。思考功能的配置。如果为不支持思考的模型设置了此字段，系统将返回错误。

imageConfig object (ImageConfig)

可选。图片生成配置。如果为不支持这些配置选项的模型设置了此字段，系统将返回错误。

mediaResolution enum (MediaResolution)

可选。如果指定，系统将使用指定的媒体分辨率。

enableAffectiveDialog boolean

可选。如果启用，模型将检测情绪并相应地调整其回答。

responseFormat object (ResponseFormatConfig)

可选。回答输出格式的配置。允许以扁平结构为每种模态（文本、音频、图片）指定输出配置。

translationConfig object (TranslationConfig)

可选。翻译配置。

audioTranscriptionConfig object (AudioTranscriptionConfig)

可选。音频转写（语音识别）配置。

JSON 表示法 
{
  "stopSequences": [
    string
  ],
  "responseMimeType": string,
  "responseSchema": {
    object (Schema)
  },
  "_responseJsonSchema": value,
  "responseJsonSchema": value,
  "responseModalities": [
    enum (Modality)
  ],
  "candidateCount": integer,
  "maxOutputTokens": integer,
  "temperature": number,
  "topP": number,
  "topK": integer,
  "seed": integer,
  "presencePenalty": number,
  "frequencyPenalty": number,
  "responseLogprobs": boolean,
  "logprobs": integer,
  "enableEnhancedCivicAnswers": boolean,
  "speechConfig": {
    object (SpeechConfig)
  },
  "thinkingConfig": {
    object (ThinkingConfig)
  },
  "imageConfig": {
    object (ImageConfig)
  },
  "mediaResolution": enum (MediaResolution),
  "enableAffectiveDialog": boolean,
  "responseFormat": {
    object (ResponseFormatConfig)
  },
  "translationConfig": {
    object (TranslationConfig)
  },
  "audioTranscriptionConfig": {
    object (AudioTranscriptionConfig)
  }
}

模态

支持的回答模态。

枚举
MODALITY_UNSPECIFIED 默认值。
TEXT 指示模型应返回文本。
IMAGE 表示模型应返回图片。
AUDIO 表示模型应返回音频。

SpeechConfig

语音生成和转写配置。

字段
voiceConfig object (VoiceConfig)

单语音输出时的配置。

multiSpeakerVoiceConfig object (MultiSpeakerVoiceConfig)

可选。多音箱设置的配置。它与 voiceConfig 字段互斥。

languageCode string

可选。用户配置应用使用的 IETF BCP-47 语言代码。用于语音识别和语音合成。

有效值包括：de-DE、en-AU、en-GB、en-IN、en-US、es-US、fr-FR、hi-IN、pt-BR、ar-XA、es-ES、fr-CA、id-ID、it-IT、ja-JP、tr-TR、vi-VN、bn-IN、gu-IN、kn-IN、ml-IN、mr-IN、ta-IN、te-IN、nl-NL、ko-KR、cmn-CN、pl-PL、ru-RU 和 th-TH。

JSON 表示法 
{
  "voiceConfig": {
    object (VoiceConfig)
  },
  "multiSpeakerVoiceConfig": {
    object (MultiSpeakerVoiceConfig)
  },
  "languageCode": string
}

VoiceConfig

要使用的语音的配置。

字段
voice_config Union type
要使用的说话者配置。以下是互斥字段列表。在响应中，最多只能设置其中一个字段：
prebuiltVoiceConfig object (PrebuiltVoiceConfig)

要使用的预构建语音的配置。

voice string

可选。用于合成的说话人标识符。支持的格式：

  • 预构建语音的说话者名称（例如 Orus 或 Kore）。
  • 已存储语音的语音 ID（例如 voice_xxx）。
  • 语音复刻密钥（例如 voicekey_xxx）。
互斥字段结束。
JSON 表示法 
{

  // voice_config
  "prebuiltVoiceConfig": {
    object (PrebuiltVoiceConfig)
  },
  "voice": string
  // Union type
}

PrebuiltVoiceConfig

要使用的预构建演讲者的配置。

字段
voiceName string

可选。要使用的预设语音的名称。

JSON 表示法 
{
  "voiceName": string
}

MultiSpeakerVoiceConfig

多扬声器设置的配置。

字段
speakerVoiceConfigs[] object (SpeakerVoiceConfig)

必需。所有已启用的说话者语音。

JSON 表示法 
{
  "speakerVoiceConfigs": [
    {
      object (SpeakerVoiceConfig)
    }
  ]
}

SpeakerVoiceConfig

多音箱设置中单个音箱的配置。

字段
speaker string

必需。要使用的音箱的名称。应与提示中的内容相同。

voiceConfig object (VoiceConfig)

必需。要使用的语音的配置。

JSON 表示法 
{
  "speaker": string,
  "voiceConfig": {
    object (VoiceConfig)
  }
}

ThinkingConfig

思考功能的配置。

字段
includeThoughts boolean

指明是否在回答中包含思考过程。如果为 true，则仅在有思考过程时返回。

thinkingBudget integer

模型应生成的思考 token 数量。

thinkingLevel enum (ThinkingLevel)

可选。控制模型在生成回答之前内部推理过程的最大深度。默认值取决于模型。如需了解详情，请参阅思考级别指南。推荐用于 Gemini 3 或更高版本的模型。与早期模型搭配使用会导致错误。

JSON 表示法 
{
  "includeThoughts": boolean,
  "thinkingBudget": integer,
  "thinkingLevel": enum (ThinkingLevel)
}

ThinkingLevel

允许用户使用枚举（而非整数预算）指定思考程度。

枚举
THINKING_LEVEL_UNSPECIFIED 默认值。
MINIMAL 几乎不思考。
LOW 思考等级：低。
MEDIUM 中度思考等级。
HIGH 高思考等级。

ImageConfig

图片生成功能的配置。

字段
aspectRatio string

可选。要生成的图片的宽高比。支持的宽高比：1:1、1:4、4:1、1:8、8:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9 或 21:9。

如果未指定，模型会根据提供的任何参考图片选择默认宽高比。

imageSize string

可选。指定生成的图片的大小。支持的值包括 512、1K、2K、4K。如果未指定，模型将使用默认值 1K。

JSON 表示法 
{
  "aspectRatio": string,
  "imageSize": string
}

MediaResolution

输入媒体的媒体分辨率。

枚举
MEDIA_RESOLUTION_UNSPECIFIED 尚未设置媒体分辨率。
MEDIA_RESOLUTION_LOW 媒体分辨率设为低（64 个 token）。
MEDIA_RESOLUTION_MEDIUM 媒体分辨率设置为中等（256 个 token）。
MEDIA_RESOLUTION_HIGH 媒体分辨率设置为高（使用 256 个 token 进行缩放重构）。

ResponseFormatConfig

回答输出格式的配置。这是一个扁平对象，其中每个可选子字段都用于配置特定的输出模态。

字段
text object (TextResponseFormat)

可选。文本输出格式配置。

audio object (AudioResponseFormat)

可选。音频输出格式配置。

image object (ImageResponseFormat)

可选。图片输出格式配置。

JSON 表示法 
{
  "text": {
    object (TextResponseFormat)
  },
  "audio": {
    object (AudioResponseFormat)
  },
  "image": {
    object (ImageResponseFormat)
  }
}

TextResponseFormat

文本输出格式的配置。

字段
mimeType enum (MimeType)

可选。文本输出的 MIME 类型。

schema value (Value format)

可选。输出应符合的 JSON 架构。仅在 mimeType 为 APPLICATION_JSON 时适用。

JSON 表示法 
{
  "mimeType": enum (MimeType),
  "schema": value
}

MimeType

文本输出支持的 MIME 类型。

枚举
MIME_TYPE_UNSPECIFIED 默认值。此值未使用。
APPLICATION_JSON JSON 输出格式。
TEXT_PLAIN 纯文本输出格式。

AudioResponseFormat

音频输出格式的配置。

字段
mimeType enum (MimeType)

可选。音频输出的 MIME 类型。

delivery enum (Delivery)

可选。音频输出的传送模式。

sampleRate integer

可选。采样率（以 Hz 为单位）。

bitRate integer

可选。比特率，以每秒比特数 (bps) 为单位。仅适用于压缩格式（MP3、Opus）。

JSON 表示法 
{
  "mimeType": enum (MimeType),
  "delivery": enum (Delivery),
  "sampleRate": integer,
  "bitRate": integer
}

MimeType

音频输出支持的 MIME 类型。

枚举
MIME_TYPE_UNSPECIFIED 默认值。此值未使用。
AUDIO_MP3 MP3 音频格式。
AUDIO_OGG_OPUS OGG Opus 音频格式。
AUDIO_L16 原始 PCM (L16) 音频格式。
AUDIO_WAV WAV 音频格式。
AUDIO_ALAW A-law 音频格式。
AUDIO_MULAW Mu-law 音频格式。

传送

音频输出的分发模式。

枚举
DELIVERY_UNSPECIFIED 默认值。此值未使用。
INLINE 音频数据会在响应中以内嵌方式返回。
URI 音频数据以 URI 形式返回。

ImageResponseFormat

图片输出格式的配置。

字段
mimeType enum (MimeType)

可选。输出图片的 MIME 类型。

delivery enum (Delivery)

可选。图片输出的分发模式。

aspectRatio enum (AspectRatio)

可选。图片输出的宽高比。

imageSize enum (ImageSize)

可选。图片输出的大小。

JSON 表示法 
{
  "mimeType": enum (MimeType),
  "delivery": enum (Delivery),
  "aspectRatio": enum (AspectRatio),
  "imageSize": enum (ImageSize)
}

MimeType

图片输出支持的 MIME 类型。

枚举
MIME_TYPE_UNSPECIFIED 默认值。此值未使用。
IMAGE_JPEG JPEG 图片格式。

传送

图片输出的分发模式。

枚举
DELIVERY_UNSPECIFIED 默认值。此值未使用。
INLINE 图片数据会在响应中内嵌返回。
URI 图片数据会以 URI 的形式返回。

AspectRatio

支持的图片输出宽高比。

枚举
ASPECT_RATIO_UNSPECIFIED 默认值。此值未使用。
ASPECT_RATIO_ONE_BY_ONE 宽高比：1:1。
ASPECT_RATIO_TWO_BY_THREE 宽高比：2:3。
ASPECT_RATIO_THREE_BY_TWO 宽高比：3:2。
ASPECT_RATIO_THREE_BY_FOUR 宽高比：3:4。
ASPECT_RATIO_FOUR_BY_THREE 宽高比：4:3。
ASPECT_RATIO_FOUR_BY_FIVE 宽高比：4:5。
ASPECT_RATIO_FIVE_BY_FOUR 宽高比：5:4。
ASPECT_RATIO_NINE_BY_SIXTEEN 宽高比：9:16。
ASPECT_RATIO_SIXTEEN_BY_NINE 宽高比：16:9。
ASPECT_RATIO_TWENTY_ONE_BY_NINE 宽高比：21:9。
ASPECT_RATIO_ONE_BY_EIGHT 宽高比：1:8。
ASPECT_RATIO_EIGHT_BY_ONE 宽高比：8:1。
ASPECT_RATIO_ONE_BY_FOUR 宽高比：1:4。
ASPECT_RATIO_FOUR_BY_ONE 宽高比：4:1。

ImageSize

图片输出支持的图片大小。

枚举
IMAGE_SIZE_UNSPECIFIED 默认值。此值未使用。
IMAGE_SIZE_FIVE_TWELVE 512 像素图片大小。
IMAGE_SIZE_ONE_K 1K 图片大小。
IMAGE_SIZE_TWO_K 2K 图片尺寸。
IMAGE_SIZE_FOUR_K 4K 图片尺寸。

TranslationConfig

翻译功能的配置。

字段
targetLanguageCode string

必需。翻译的目标语言。支持的值为 BCP-47 语言代码（例如“en”“es”“fr”）。

echoTargetLanguage boolean

可选。如果为 true，则模型会在输入目标语言时生成音频，基本上就是鹦鹉学舌。如果为 false，我们将不会为目标语言生成音频。

JSON 表示法 
{
  "targetLanguageCode": string,
  "echoTargetLanguage": boolean
}

AudioTranscriptionConfig

音频转写配置。

字段
languageCodes[] string

可选。BCP-47 语言代码，用于提供有关音频中所用语言的提示。如果省略或留空，则默认自动检测语言。

adaptationPhrases[]
(deprecated) string

可选。用于语音自适应的短语列表，可使 ASR 模型偏向于这些特定字词，从而提高识别准确率。

customVocabulary[] string

可选。自定义词汇短语列表，用于引导语音识别模型识别特定术语（商品名称、专有名词、行业术语）。

wordTimestamp boolean

可选。配置字词级时间戳生成。

diarization boolean

可选。配置讲话人区分。

mode enum (Mode)

可选。配置转写模式。支持的值：VERBATIM、SMART。如果未指定，则默认为 VERBATIM 转写。在SMART模式下，模型会执行文本顺滑（消除填充词、重复和口误）、轻微语法清理、自动格式设置（段落、项目符号、编号列表）和轻微用户编辑（内嵌自我更正）。时间戳和说话人标识与模式 SMART 不兼容。

language_config Union type
已弃用：请改用顶级 language_codes。以下是互斥字段列表。在响应中，最多只能设置其中一个字段：
languageAuto
(deprecated) object (LanguageAuto)

可选。模型会自动检测语言。

languageHints
(deprecated) object (LanguageHints)

可选。指定音频中的一种或多种语言。

互斥字段结束。
JSON 表示法 
{
  "languageCodes": [
    string
  ],
  "adaptationPhrases": [
    string
  ],
  "customVocabulary": [
    string
  ],
  "wordTimestamp": boolean,
  "diarization": boolean,
  "mode": enum (Mode),

  // language_config
  "languageAuto": {
    object (LanguageAuto)
  },
  "languageHints": {
    object (LanguageHints)
  }
  // Union type
}

LanguageAuto

此类型没有字段。

表示应自动检测音频的语言。

LanguageHints

向模型提供有关音频中可能存在的语言的提示。

字段
languageCodes[]
(deprecated) string

必需。BCP-47 语言代码。

JSON 表示法 
{
  "languageCodes": [
    string
  ]
}

模式

转写模式。

枚举
MODE_UNSPECIFIED 未指定转写模式。
VERBATIM 逐字转写模式。
SMART 智能转写模式。

RealtimeInputConfig

配置 BidiGenerateContent 中的实时输入行为。

字段
automaticActivityDetection object (AutomaticActivityDetection)

可选。如果未设置，则默认启用自动活动检测。如果自动语音检测已停用，客户端必须发送活动信号。

activityHandling enum (ActivityHandling)

可选。定义活动的具体效果。

turnCoverage enum (TurnCoverage)

可选。定义用户回合中包含哪些输入。

interimTranscriptTimestampEnabled boolean

可选。配置临时转写时间戳。

JSON 表示法 
{
  "automaticActivityDetection": {
    object (AutomaticActivityDetection)
  },
  "activityHandling": enum (ActivityHandling),
  "turnCoverage": enum (TurnCoverage),
  "interimTranscriptTimestampEnabled": boolean
}

AutomaticActivityDetection

配置活动自动检测。

字段
disabled boolean

可选。如果启用（默认），检测到的语音和文本输入将计为活动。如果停用，客户端必须发送活动信号。

startOfSpeechSensitivity enum (StartSensitivity)

可选。确定检测到语音的可能性。

prefixPaddingMs integer

可选。在提交语音开始之前检测到的所需语音时长。此值越低，语音开始检测的灵敏度越高，可识别的语音越短。但是，这也会增加出现假正例的概率。

endOfSpeechSensitivity enum (EndSensitivity)

可选。确定检测到的语音结束的可能性。

silenceDurationMs integer

可选。在提交语音结束之前检测到的非语音（例如静音）的所需时长。此值越大，语音间断时间越长，而不会中断用户活动，但会增加模型的延迟时间。

JSON 表示法 
{
  "disabled": boolean,
  "startOfSpeechSensitivity": enum (StartSensitivity),
  "prefixPaddingMs": integer,
  "endOfSpeechSensitivity": enum (EndSensitivity),
  "silenceDurationMs": integer
}

StartSensitivity

确定如何检测语音开始。

枚举
START_SENSITIVITY_UNSPECIFIED 默认值为 START_SENSITIVITY_HIGH。
START_SENSITIVITY_HIGH 自动检测功能会更频繁地检测语音的开始。
START_SENSITIVITY_LOW 自动检测功能检测语音开始的频率会降低。

EndSensitivity

确定如何检测语音结束。

枚举
END_SENSITIVITY_UNSPECIFIED 默认值为 END_SENSITIVITY_HIGH。
END_SENSITIVITY_HIGH 自动检测结束语音的频率较高。
END_SENSITIVITY_LOW 自动检测结束语音的频率较低。

ActivityHandling

处理用户活动的不同方式。

枚举
ACTIVITY_HANDLING_UNSPECIFIED 如果未指定，则默认行为为 START_OF_ACTIVITY_INTERRUPTS。
START_OF_ACTIVITY_INTERRUPTS 如果为 true，则活动的启动会中断模型的响应（也称为“打断”）。模型当前的回答将在中断时被截断。这是默认行为。
NO_INTERRUPTION 模型的回答不会中断。

TurnCoverage

有关用户回合中包含哪些输入的选项。

枚举
TURN_COVERAGE_UNSPECIFIED 如果未指定，系统会根据模型选择默认行为。例如，对于 Gemini 2.5，默认值为 TURN_INCLUDES_ONLY_ACTIVITY，而对于 Gemini 3.1 及更高版本，默认值为 TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO。
TURN_INCLUDES_ONLY_ACTIVITY 包括自上一个回合以来的活动，不包括不活动状态（例如音频串流中的静音）。
TURN_INCLUDES_ALL_INPUT 包括自上一个回合以来的所有实时输入，包括不活动状态（例如音频串流中的静音）。
TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO 包括自上一个回合以来的音频活动和所有视频。启用自动活动检测后，音频活动是指语音，不包括静音。

SessionResumptionConfig

会话恢复配置。

此消息在会话配置中以 BidiGenerateContentSetup.session_resumption 的形式包含。如果已配置，服务器将发送 SessionResumptionUpdate 消息。

字段
handle string

上一个会话的句柄。如果不存在，则会创建一个新会话。

会话句柄来自先前连接中的 SessionResumptionUpdate.token 值。

JSON 表示法 
{
  "handle": string
}

ContextWindowCompressionConfig

启用上下文窗口压缩，这是一种用于管理模型上下文窗口的机制，可确保其不超过给定长度。

字段
compression_mechanism Union type
所用的上下文窗口压缩机制。以下是互斥字段列表。在响应中，最多只能设置其中一个字段：
slidingWindow object (SlidingWindow)

滑动窗口机制。

互斥字段结束。
triggerTokens string (int64 format)

触发上下文窗口压缩所需的 token 数量（在运行一轮对话之前）。

这可用于在质量与延迟时间之间取得平衡，因为较短的上下文窗口可能会加快模型回答速度。不过，任何压缩操作都会导致延迟时间暂时增加，因此不应频繁触发。

如果未设置，则默认值为模型上下文窗口限制的 80%。这样，下一个用户请求/模型回答就还剩下 20% 的空间。

JSON 表示法 
{

  // compression_mechanism
  "slidingWindow": {
    object (SlidingWindow)
  }
  // Union type
  "triggerTokens": string
}

SlidingWindow

SlidingWindow 方法的工作原理是舍弃上下文窗口开头的内容。生成的上下文始终从 USER 角色轮次的开头开始。系统指令和所有 BidiGenerateContentSetup.prefix_turns 将始终保留在结果的开头。

字段
targetTokens string (int64 format)

要保留的目标词元数量。默认值为 triggerTokens/2。

丢弃部分上下文窗口会导致延迟时间暂时增加，因此应校准此值，以避免频繁的压缩操作。

JSON 表示法 
{
  "targetTokens": string
}

HistoryConfig

历史记录配置。

此消息在会话配置中以 BidiGenerateContentSetup.history_config 的形式包含。配置历史消息的交换。

字段
initialHistoryInClientContent boolean

可选。如果为 true，则在发送 setupComplete 后，服务器将等待并首先处理 clientContent 消息，直到 turnComplete 为 true。此初始历史记录不会触发模型调用，并且可能以角色 MODEL 结尾。turnComplete true后，客户端可以通过 realtimeInput 启动实时对话。

JSON 表示法 
{
  "initialHistoryInClientContent": boolean
}

方法：auth_tokens.create

创建一个令牌，用于限制 BidiGenerateContent 会话的行为。

端点

帖子 https://generativelanguage.googleapis.com/v1beta/auth_tokens

请求正文

请求正文包含一个 AuthToken 实例。

字段
expireTime string (Timestamp format)

可选。仅限输入。不可变。一个可选时间，在此时间之后，如果使用生成的令牌，BidiGenerateContent 会话中的消息将被拒绝。（Gemini 可能会在此时间之后提前关闭会话。）

如果未设置，则默认为未来 30 分钟。如果设置了此值，则该值必须小于 20 小时。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不进行“Z”归一化处理的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

newSessionExpireTime string (Timestamp format)

可选。仅限输入。不可变。在此时间之后，使用此请求生成的令牌的新 Live API 会话将被拒绝。

如果未设置，则默认为未来 60 秒。如果设置了此值，则该值必须小于未来 20 小时。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不进行“Z”归一化处理的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

fieldMask string (FieldMask format)

可选。仅限输入。不可变。如果 fieldMask 为空，并且 bidiGenerateContentSetup 不存在，则有效的 BidiGenerateContentSetup 消息将从 Live API 连接中获取。

如果 fieldMask 为空，并且 bidiGenerateContentSetup 存在，则有效的 BidiGenerateContentSetup 消息将完全取自此请求中的 bidiGenerateContentSetup。来自 Live API 连接的设置消息会被忽略。

如果 fieldMask 不为空，则 bidiGenerateContentSetup 中的相应字段将覆盖 Live API 连接中设置消息中的字段。

这是完全限定字段名称的逗号分隔列表。示例："user.displayName,photo"。

config Union type
生成的令牌的方法特定配置。以下是互斥字段列表。在响应中，最多只能设置其中一个字段：
bidiGenerateContentSetup object (BidiGenerateContentSetup)

可选。仅限输入。不可变。BidiGenerateContent 专属配置。

互斥字段结束。
uses integer

可选。仅限输入。不可变。令牌可使用的次数。如果此值为零，则不应用任何限制。恢复 Live API 会话不计为一次使用。如果未指定，则默认值为 1。

响应正文

如果成功，响应正文将包含一个新创建的 AuthToken 实例。