Google Gemini 对话格式(Generate Content)¶
📝 简介¶
Google Gemini API 支持使用图片、音频、代码、工具等生成内容。给定输入 GenerateContentRequest 生成模型响应。支持文本生成、视觉理解、音频处理、长上下文、代码执行、JSON 模式、函数调用等多种功能。
💡 请求示例¶
基础文本对话 ✅¶
curl "https://api.zetatechs.com/v1beta/models/gemini-2.0-flash:generateContent?key=$NEWAPI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[{"text": "Write a story about a magic backpack."}]
        }]
       }' 2> /dev/null
图像分析对话 ✅¶
# 使用临时文件保存base64编码的图片数据
TEMP_B64=$(mktemp)
trap 'rm -f "$TEMP_B64"' EXIT
base64 $B64FLAGS $IMG_PATH > "$TEMP_B64"
# 使用临时文件保存JSON载荷
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://api.zetatechs.com/v1beta/models/gemini-2.0-flash:generateContent?key=$NEWAPI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d "@$TEMP_JSON" 2> /dev/null
函数调用 ✅¶
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://api.zetatechs.com/v1beta/models/gemini-2.0-flash:generateContent?key=$NEWAPI_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'
JSON 模式响应 ✅¶
curl "https://api.zetatechs.com/v1beta/models/gemini-2.0-flash:generateContent?key=$NEWAPI_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
音频处理 🟡¶
文件上传限制
仅支持通过 inline_data 以 base64 方式上传音频,不支持 file_data.file_uri 或 File API。
# 使用File API上传音频数据到API请求
# 使用 base64 inline_data 上传音频数据到 API 请求
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi
AUDIO_B64=$(base64 $B64FLAGS "$AUDIO_PATH")
curl "https://api.zetatechs.com/v1beta/models/gemini-2.0-flash:generateContent?key=$NEWAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [
        {"text": "Please describe this audio file."},
        {"inline_data": {"mime_type": "audio/mpeg", "data": "'$AUDIO_B64'"}}
      ]
    }]
  }' 2> /dev/null | jq ".candidates[].content.parts[].text"
视频处理 🟡¶
文件上传限制
仅支持通过 inline_data 以 base64 方式上传视频,不支持 file_data.file_uri 或 File API。
# 使用File API上传视频数据到API请求
# 使用 base64 inline_data 上传视频数据到 API 请求
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi
VIDEO_B64=$(base64 $B64FLAGS "$VIDEO_PATH")
curl "https://api.zetatechs.com/v1beta/models/gemini-2.0-flash:generateContent?key=$NEWAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [
        {"text": "Transcribe the audio from this video and provide visual descriptions."},
        {"inline_data": {"mime_type": "video/mp4", "data": "'$VIDEO_B64'"}}
      ]
    }]
  }' 2> /dev/null | jq ".candidates[].content.parts[].text"
PDF处理 🟡¶
文件上传限制
仅支持通过 inline_data 以 base64 方式上传 PDF,不支持 file_data.file_uri 或 File API。
MIME_TYPE=$(file -b --mime-type "${PDF_PATH}")
# 使用 base64 inline_data 上传 PDF 文件到 API 请求
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi
PDF_B64=$(base64 $B64FLAGS "$PDF_PATH")
echo $MIME_TYPE
curl "https://api.zetatechs.com/v1beta/models/gemini-2.0-flash:generateContent?key=$NEWAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [
        {"text": "Can you add a few more lines to this poem?"},
        {"inline_data": {"mime_type": "application/pdf", "data": "'$PDF_B64'"}}
      ]
    }]
  }' 2> /dev/null | jq ".candidates[].content.parts[].text"
聊天对话 ✅¶
curl https://api.zetatechs.com/v1beta/models/gemini-2.0-flash:generateContent?key=$NEWAPI_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"
流式响应 ✅¶
curl "https://api.zetatechs.com/v1beta/models/gemini-2.0-flash:streamGenerateContent?alt=sse&key=$NEWAPI_API_KEY" \
    -H 'Content-Type: application/json' \
    --no-buffer \
    -d '{
      "contents": [{
        "parts": [{"text": "写一个关于魔法背包的故事"}]
      }]
    }'
代码执行 ✅¶
curl "https://api.zetatechs.com/v1beta/models/gemini-2.0-flash:generateContent?key=$NEWAPI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts": [{"text": "计算斐波那契数列的第10项"}]
      }],
      "tools": [{
        "codeExecution": {}
      }]
    }'
生成配置 ✅¶
curl https://api.zetatechs.com/v1beta/models/gemini-2.0-flash:generateContent?key=$NEWAPI_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"
安全设置 ✅¶
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://api.zetatechs.com/v1beta/models/gemini-2.0-flash:generateContent?key=$NEWAPI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d @request.json 2> /dev/null
系统指令 ✅¶
curl "https://api.zetatechs.com/v1beta/models/gemini-2.0-flash:generateContent?key=$NEWAPI_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"}}}'
📮 请求¶
端点¶
生成内容¶
流式生成内容¶
鉴权方法¶
在请求URL参数中包含API密钥:
其中 $NEWAPI_API_KEY 是您的 Google AI API 密钥。
路径参数¶
model¶
 - 类型:字符串
 - 必需:是
 
用于生成补全项的模型名称。
格式:models/{model},例如 models/gemini-2.0-flash
请求体参数¶
contents¶
 - 类型:数组
 - 必需:是
 
与模型当前对话的内容。对于单轮查询,这是单个实例。对于聊天等多轮查询,这是包含对话历史记录和最新请求的重复字段。
Content 对象属性:
| 属性 | 类型 | 必需 | 描述 | 
|---|---|---|---|
parts |  数组 | 是 | 有序的内容部分,构成单个消息 | 
role |  字符串 | 否 | 对话中内容的生产者。user、model、function 或 tool |  
Part 对象属性:
| 属性 | 类型 | 必需 | 描述 | 
|---|---|---|---|
text |  字符串 | 否 | 纯文本内容 | 
inlineData |  对象 | 否 | 内联媒体字节数据 | 
fileData |  对象 | 否 | 上传文件的URI引用 | 
functionCall |  对象 | 否 | 函数调用请求 | 
functionResponse |  对象 | 否 | 函数调用响应 | 
executableCode |  对象 | 否 | 可执行代码 | 
codeExecutionResult |  对象 | 否 | 代码执行结果 | 
InlineData 对象属性:
| 属性 | 类型 | 必需 | 描述 | 
|---|---|---|---|
mimeType |  字符串 | 是 | 媒体的MIME类型 | 
data |  字符串 | 是 | base64编码的媒体数据 | 
FileData 对象属性:
| 属性 | 类型 | 必需 | 描述 | 
|---|---|---|---|
mimeType |  字符串 | 是 | 文件的MIME类型 | 
fileUri |  字符串 | 是 | 文件的URI | 
tools¶
 - 类型:数组
 - 必需:否
 
模型可能用于生成下一个响应的工具列表。支持的工具包括函数和代码执行。
Tool 对象属性:
| 属性 | 类型 | 必需 | 描述 | 
|---|---|---|---|
functionDeclarations |  数组 | 否 | 可选的函数声明列表 | 
codeExecution |  对象 | 否 | 启用模型执行代码 | 
FunctionDeclaration 对象属性:
| 属性 | 类型 | 必需 | 描述 | 
|---|---|---|---|
name |  字符串 | 是 | 函数名称 | 
description |  字符串 | 否 | 函数功能描述 | 
parameters |  对象 | 否 | 函数参数,JSON Schema格式 | 
FunctionCall 对象属性:
| 属性 | 类型 | 必需 | 描述 | 
|---|---|---|---|
name |  字符串 | 是 | 要调用的函数名称 | 
args |  对象 | 否 | 函数参数的键值对 | 
FunctionResponse 对象属性:
| 属性 | 类型 | 必需 | 描述 | 
|---|---|---|---|
name |  字符串 | 是 | 调用的函数名称 | 
response |  对象 | 是 | 函数调用的响应数据 | 
ExecutableCode 对象属性:
| 属性 | 类型 | 必需 | 描述 | 
|---|---|---|---|
language |  枚举 | 是 | 代码的编程语言 | 
code |  字符串 | 是 | 要执行的代码 | 
CodeExecutionResult 对象属性:
| 属性 | 类型 | 必需 | 描述 | 
|---|---|---|---|
outcome |  枚举 | 是 | 代码执行的结果状态 | 
output |  字符串 | 否 | 代码执行的输出内容 | 
CodeExecution 对象属性:
| 属性 | 类型 | 必需 | 描述 | 
|---|---|---|---|
| {} | 空对象 | - | 启用代码执行功能的空配置对象 | 
toolConfig¶
 - 类型:对象
 - 必需:否
 
请求中指定的任何工具的工具配置。
ToolConfig 对象属性:
| 属性 | 类型 | 必需 | 描述 | 
|---|---|---|---|
functionCallingConfig |  对象 | 否 | 函数调用配置 | 
FunctionCallingConfig 对象属性:
| 属性 | 类型 | 必需 | 描述 | 
|---|---|---|---|
mode |  枚举 | 否 | 指定函数调用的模式 | 
allowedFunctionNames |  数组 | 否 | 允许调用的函数名列表 | 
FunctionCallingMode 枚举值:
MODE_UNSPECIFIED: 默认模式,模型决定是否调用函数AUTO: 模型自动决定何时调用函数ANY: 模型必须调用函数NONE: 模型不能调用函数
safetySettings¶
 - 类型:数组
 - 必需:否
 
用于屏蔽不安全内容的 SafetySetting 实例列表。
SafetySetting 对象属性:
| 属性 | 类型 | 必需 | 描述 | 
|---|---|---|---|
category |  枚举 | 是 | 安全类别 | 
threshold |  枚举 | 是 | 屏蔽阈值 | 
HarmCategory 枚举值:
HARM_CATEGORY_HARASSMENT: 骚扰内容HARM_CATEGORY_HATE_SPEECH: 仇恨言论和内容HARM_CATEGORY_SEXUALLY_EXPLICIT: 露骨色情内容HARM_CATEGORY_DANGEROUS_CONTENT: 危险内容HARM_CATEGORY_CIVIC_INTEGRITY: 可能用于破坏公民诚信的内容
HarmBlockThreshold 枚举值:
BLOCK_LOW_AND_ABOVE: 允许发布评分为 NEGLIGIBLE 的内容BLOCK_MEDIUM_AND_ABOVE: 允许发布评分为 NEGLIGIBLE 和 LOW 的内容BLOCK_ONLY_HIGH: 允许发布风险等级为 NEGLIGIBLE、LOW 和 MEDIUM 的内容BLOCK_NONE: 允许所有内容OFF: 关闭安全过滤器
HarmBlockThreshold 完整枚举值:
HARM_BLOCK_THRESHOLD_UNSPECIFIED: 未指定阈值BLOCK_LOW_AND_ABOVE: 屏蔽低概率及以上的有害内容,只允许 NEGLIGIBLE 级别的内容BLOCK_MEDIUM_AND_ABOVE: 屏蔽中等概率及以上的有害内容,允许 NEGLIGIBLE 和 LOW 级别的内容BLOCK_ONLY_HIGH: 只屏蔽高概率的有害内容,允许 NEGLIGIBLE、LOW 和 MEDIUM 级别的内容BLOCK_NONE: 不屏蔽任何内容,允许所有级别的内容OFF: 完全关闭安全过滤器
systemInstruction¶
 - 类型:对象(Content)
 - 必需:否
 
开发者设置的系统指令。目前仅支持文本。
generationConfig¶
 - 类型:对象
 - 必需:否
 
模型生成和输出的配置选项。
GenerationConfig 对象属性:
| 属性 | 类型 | 必需 | 描述 | 
|---|---|---|---|
stopSequences |  数组 | 否 | 用于停止生成输出的字符序列集(最多5个) | 
responseMimeType |  字符串 | 否 | 生成的候选文本的MIME类型 | 
responseSchema |  对象 | 否 | 生成的候选文本的输出架构 | 
responseModalities |  数组 | 否 | 请求的响应模式 | 
candidateCount |  整数 | 否 | 要返回的生成的回答数量 | 
maxOutputTokens |  整数 | 否 | 候选回答中包含的令牌数量上限 | 
temperature |  数字 | 否 | 控制输出的随机性,范围[0.0, 2.0] | 
topP |  数字 | 否 | 在抽样时要考虑的令牌的累计概率上限 | 
topK |  整数 | 否 | 抽样时要考虑的令牌数量上限 | 
seed |  整数 | 否 | 解码中使用的种子 | 
presencePenalty |  数字 | 否 | 存在性惩罚 | 
frequencyPenalty |  数字 | 否 | 频率惩罚 | 
responseLogprobs |  布尔值 | 否 | 是否在响应中导出logprobs结果 | 
logprobs |  整数 | 否 | 返回的顶部logprob的数量 | 
enableEnhancedCivicAnswers |  布尔值 | 否 | 启用增强型城市服务回答 | 
speechConfig |  对象 | 否 | 语音生成配置 | 
thinkingConfig |  对象 | 否 | 思考功能的配置 | 
mediaResolution |  枚举 | 否 | 指定的媒体分辨率 | 
支持的 MIME 类型:
text/plain: (默认)文本输出application/json: JSON响应text/x.enum: ENUM作为字符串响应
Modality 枚举值:
TEXT: 指示模型应返回文本IMAGE: 表示模型应返回图片AUDIO: 指示模型应返回音频
Schema 对象属性:
| 属性 | 类型 | 必需 | 描述 | 
|---|---|---|---|
type |  枚举 | 是 | 数据类型 | 
description |  字符串 | 否 | 字段描述 | 
enum |  数组 | 否 | 枚举值列表(当type为string时) | 
example |  任意类型 | 否 | 示例值 | 
nullable |  布尔值 | 否 | 是否可为null | 
format |  字符串 | 否 | 字符串格式(如date、date-time等) | 
items |  对象 | 否 | 数组项的Schema(当type为array时) | 
properties |  对象 | 否 | 对象属性的Schema映射(当type为object时) | 
required |  数组 | 否 | 必需属性的名称列表 | 
minimum |  数字 | 否 | 数字的最小值 | 
maximum |  数字 | 否 | 数字的最大值 | 
minItems |  整数 | 否 | 数组的最小长度 | 
maxItems |  整数 | 否 | 数组的最大长度 | 
minLength |  整数 | 否 | 字符串的最小长度 | 
maxLength |  整数 | 否 | 字符串的最大长度 | 
Type 枚举值:
TYPE_UNSPECIFIED: 未指定类型STRING: 字符串类型NUMBER: 数字类型INTEGER: 整数类型BOOLEAN: 布尔类型ARRAY: 数组类型OBJECT: 对象类型
支持的编程语言(ExecutableCode):
LANGUAGE_UNSPECIFIED: 未指定语言PYTHON: Python编程语言
代码执行结果枚举(Outcome):
OUTCOME_UNSPECIFIED: 未指定结果OUTCOME_OK: 代码执行成功OUTCOME_FAILED: 代码执行失败OUTCOME_DEADLINE_EXCEEDED: 代码执行超时
cachedContent¶
 - 类型:字符串
 - 必需:否
 
缓存的内容的名称,用于用作提供预测的上下文。格式:cachedContents/{cachedContent}
📥 响应¶
GenerateContentResponse¶
支持多个候选回答的模型的回答。系统会针对提示以及每个候选项报告安全分级和内容过滤。
candidates¶
 - 类型:数组
 - 说明:模型的候选回答列表
 
Candidate 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
content |  对象 | 模型返回的生成内容 | 
finishReason |  枚举 | 模型停止生成词元的原因 | 
safetyRatings |  数组 | 候选回答安全性的评分列表 | 
citationMetadata |  对象 | 模型生成的候选项的引用信息 | 
tokenCount |  整数 | 此候选项的令牌数 | 
groundingAttributions |  数组 | 为生成有依据的回答所参考的来源提供方信息 | 
groundingMetadata |  对象 | 候选对象的参考元数据 | 
avgLogprobs |  数字 | 候选项的平均对数概率得分 | 
logprobsResult |  对象 | 回答令牌和前置令牌的对数似然度得分 | 
urlRetrievalMetadata |  对象 | 与网址情境检索工具相关的元数据 | 
urlContextMetadata |  对象 | 与网址情境检索工具相关的元数据 | 
index |  整数 | 响应候选列表中候选项的索引 | 
FinishReason 枚举值:
STOP: 模型的自然停止点或提供的停止序列MAX_TOKENS: 已达到请求中指定的词元数量上限SAFETY: 出于安全考虑,系统已标记回答候选内容RECITATION: 由于背诵原因,回答候选内容被标记LANGUAGE: 回答候选内容因使用不受支持的语言而被标记OTHER: 原因未知BLOCKLIST: 由于内容包含禁止使用的字词,因此token生成操作已停止PROHIBITED_CONTENT: 由于可能包含禁止的内容,因此token生成操作已停止SPII: 由于内容可能包含敏感的个人身份信息,因此token生成操作已停止MALFORMED_FUNCTION_CALL: 模型生成的函数调用无效IMAGE_SAFETY: 由于生成的图片违反了安全规定,因此词元生成已停止
promptFeedback¶
 - 类型:对象
 - 说明:与内容过滤器相关的提示反馈
 
PromptFeedback 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
blockReason |  枚举 | 屏蔽该提示的原因 | 
safetyRatings |  数组 | 问题安全性的评分 | 
BlockReason 枚举值:
BLOCK_REASON_UNSPECIFIED: 默认值,此值未使用SAFETY: 出于安全原因,系统屏蔽了提示OTHER: 提示因未知原因被屏蔽了BLOCKLIST: 系统屏蔽了此提示,因为其中包含术语屏蔽名单中包含的术语PROHIBITED_CONTENT: 系统屏蔽了此提示,因为其中包含禁止的内容IMAGE_SAFETY: 候选图片因生成不安全的内容而被屏蔽
usageMetadata¶
 - 类型:对象
 - 说明:有关生成请求令牌用量的元数据
 
UsageMetadata 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
promptTokenCount |  整数 | 提示中的词元数 | 
cachedContentTokenCount |  整数 | 提示的缓存部分中的词元数 | 
candidatesTokenCount |  整数 | 所有生成的候选回答中的词元总数 | 
totalTokenCount |  整数 | 生成请求的总令牌数 | 
toolUsePromptTokenCount |  整数 | 工具使用提示中的词元数量 | 
thoughtsTokenCount |  整数 | 思考模型的想法token数 | 
promptTokensDetails |  数组 | 在请求输入中处理的模态列表 | 
candidatesTokensDetails |  数组 | 响应中返回的模态列表 | 
cacheTokensDetails |  数组 | 请求输入中缓存内容的模态列表 | 
toolUsePromptTokensDetails |  数组 | 为工具使用请求输入处理的模态列表 | 
modelVersion¶
 - 类型:字符串
 - 说明:用于生成回答的模型版本
 
responseId¶
 - 类型:字符串
 - 说明:用于标识每个响应的ID
 
完整响应示例¶
{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "你好!我是 Gemini,一个由 Google 开发的人工智能助手。我可以帮助您解答问题、提供信息、协助写作、代码编程等多种任务。请告诉我有什么可以为您效劳的!"
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE",
          "blocked": false
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH", 
          "probability": "NEGLIGIBLE",
          "blocked": false
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE",
          "blocked": false
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE",
          "blocked": false
        }
      ],
      "tokenCount": 47
    }
  ],
  "promptFeedback": {
    "safetyRatings": [
      {
        "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HATE_SPEECH",
        "probability": "NEGLIGIBLE"
      }
    ]
  },
  "usageMetadata": {
    "promptTokenCount": 4,
    "candidatesTokenCount": 47,
    "totalTokenCount": 51,
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 4
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "TEXT", 
        "tokenCount": 47
      }
    ]
  },
  "modelVersion": "gemini-2.0-flash",
  "responseId": "response-12345"
}
🔧 高级功能¶
安全评级¶
SafetyRating 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
category |  枚举 | 此评分的类别 | 
probability |  枚举 | 此内容的有害概率 | 
blocked |  布尔值 | 此内容是否因此分级而被屏蔽 | 
HarmProbability 枚举值:
NEGLIGIBLE: 内容不安全的概率可忽略不计LOW: 内容不安全的概率较低MEDIUM: 内容不安全的概率为中等HIGH: 内容不安全的概率较高
引用元数据¶
CitationMetadata 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
citationSources |  数组 | 特定回复的来源引用 | 
CitationSource 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
startIndex |  整数 | 归因于此来源的响应片段的开始索引 | 
endIndex |  整数 | 归因细分的结束索引(不含) | 
uri |  字符串 | 被归因为文本部分来源的URI | 
license |  字符串 | 被归因为片段来源的GitHub项目的许可 | 
代码执行¶
当启用代码执行工具时,模型可以生成和执行代码来解决问题。
代码执行示例响应:
{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "我来计算斐波那契数列的第10项:"
          },
          {
            "executableCode": {
              "language": "PYTHON",
              "code": "def fibonacci(n):\n    if n <= 1:\n        return n\n    else:\n        return fibonacci(n-1) + fibonacci(n-2)\n\nresult = fibonacci(10)\nprint(f'第10项斐波那契数是: {result}')"
            }
          },
          {
            "codeExecutionResult": {
              "outcome": "OK",
              "output": "第10项斐波那契数是: 55"
            }
          },
          {
            "text": "所以斐波那契数列的第10项是55。"
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP"
    }
  ]
}
接地功能 (Grounding)¶
GroundingMetadata 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
groundingChunks |  数组 | 从指定的接地源检索到的支持参考文献列表 | 
groundingSupports |  数组 | 接地支持列表 | 
webSearchQueries |  数组 | 用于后续网页搜索的网页搜索查询 | 
searchEntryPoint |  对象 | 后续网页搜索的Google搜索条目 | 
retrievalMetadata |  对象 | 与基准流程中检索相关的元数据 | 
GroundingAttribution 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
sourceId |  对象 | 对此归因做出贡献的来源的标识符 | 
content |  对象 | 构成此归因的来源内容 | 
AttributionSourceId 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
groundingPassage |  对象 | 内嵌段落的标识符 | 
semanticRetrieverChunk |  对象 | 通过Semantic Retriever提取的Chunk的标识符 | 
GroundingPassageId 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
passageId |  字符串 | 与GenerateAnswerRequest的GroundingPassage.id匹配的段落的ID | 
partIndex |  整数 | GenerateAnswerRequest的GroundingPassage.content中的部分的索引 | 
SemanticRetrieverChunk 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
source |  字符串 | 与请求的SemanticRetrieverConfig.source匹配的来源名称 | 
chunk |  字符串 | 包含归因文本的Chunk的名称 | 
SearchEntryPoint 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
renderedContent |  字符串 | 可嵌入网页或应用WebView中的Web内容代码段 | 
sdkBlob |  字符串 | 使用base64编码的JSON,表示搜索词和搜索URL元组的数组 | 
Segment 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
partIndex |  整数 | Part对象在其父级Content对象中的索引 | 
startIndex |  整数 | 给定part中的起始索引,以字节为单位 | 
endIndex |  整数 | 给定分块中的结束索引,以字节为单位 | 
text |  字符串 | 与响应中的片段对应的文本 | 
RetrievalMetadata 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
googleSearchDynamicRetrievalScore |  数字 | Google搜索中的信息有助于回答问题的概率得分,范围[0,1] | 
GroundingChunk 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
web |  对象 | 来自网络的接地分块 | 
Web 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
uri |  字符串 | 分块的URI引用 | 
title |  字符串 | 数据块的标题 | 
GroundingSupport 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
groundingChunkIndices |  数组 | 索引列表,用于指定与版权主张相关的引文 | 
confidenceScores |  数组 | 支持参考文档的置信度分数,范围为0到1 | 
segment |  对象 | 此支持请求所属的内容片段 | 
多模态处理¶
Gemini API 支持处理多种模态的输入和输出:
支持的输入模态:
TEXT: 纯文本IMAGE: 图片(JPEG、PNG、WebP、HEIC、HEIF)AUDIO: 音频(WAV、MP3、AIFF、AAC、OGG、FLAC)VIDEO: 视频(MP4、MPEG、MOV、AVI、FLV、MPG、WEBM、WMV、3GPP)DOCUMENT: 文档(PDF)
ModalityTokenCount 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
modality |  枚举 | 与此令牌数关联的模态 | 
tokenCount |  整数 | 令牌数量 | 
MediaResolution 枚举值:
MEDIA_RESOLUTION_LOW: 低分辨率(64个令牌)MEDIA_RESOLUTION_MEDIUM: 中等分辨率(256个令牌)MEDIA_RESOLUTION_HIGH: 高分辨率(256个令牌进行缩放重新取景)
思考功能¶
ThinkingConfig 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
includeThoughts |  布尔值 | 是否要在回答中包含思考内容 | 
thinkingBudget |  整数 | 模型应生成的想法token的数量 | 
语音生成¶
SpeechConfig 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
voiceConfig |  对象 | 单声音输出的配置 | 
multiSpeakerVoiceConfig |  对象 | 多音箱设置的配置 | 
languageCode |  字符串 | 用于语音合成的语言代码 | 
VoiceConfig 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
prebuiltVoiceConfig |  对象 | 要使用的预构建语音的配置 | 
PrebuiltVoiceConfig 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
voiceName |  字符串 | 要使用的预设语音的名称 | 
MultiSpeakerVoiceConfig 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
speakerVoiceConfigs |  数组 | 所有已启用的音箱语音 | 
SpeakerVoiceConfig 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
speaker |  字符串 | 要使用的音箱的名称 | 
voiceConfig |  对象 | 要使用的语音的配置 | 
支持的语言代码:
zh-CN: 中文(简体)en-US: 英语(美国)ja-JP: 日语ko-KR: 韩语fr-FR: 法语de-DE: 德语es-ES: 西班牙语pt-BR: 葡萄牙语(巴西)hi-IN: 印地语ar-XA: 阿拉伯语it-IT: 意大利语tr-TR: 土耳其语vi-VN: 越南语th-TH: 泰语ru-RU: 俄语pl-PL: 波兰语nl-NL: 荷兰语
Logprobs 结果¶
LogprobsResult 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
topCandidates |  数组 | 长度等于解码步骤总数 | 
chosenCandidates |  数组 | 长度等于解码步骤总数,所选候选项不一定在topCandidates中 | 
TopCandidates 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
candidates |  数组 | 按对数概率降序排序的候选项 | 
Candidate (Logprobs) 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
token |  字符串 | 候选项的令牌字符串值 | 
tokenId |  整数 | 候选项的令牌ID值 | 
logProbability |  数字 | 候选项的对数概率 | 
URL检索功能¶
UrlRetrievalMetadata 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
urlRetrievalContexts |  数组 | 网址检索情境列表 | 
UrlRetrievalContext 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
retrievedUrl |  字符串 | 工具检索到的网址 | 
UrlContextMetadata 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
urlMetadata |  数组 | 网址上下文列表 | 
UrlMetadata 对象属性:
| 属性 | 类型 | 描述 | 
|---|---|---|
retrievedUrl |  字符串 | 工具检索到的网址 | 
urlRetrievalStatus |  枚举 | 网址检索的状态 | 
UrlRetrievalStatus 枚举值:
URL_RETRIEVAL_STATUS_SUCCESS: 网址检索成功URL_RETRIEVAL_STATUS_ERROR: 由于出错,网址检索失败
完整安全类别¶
HarmCategory 完整枚举值:
HARM_CATEGORY_UNSPECIFIED: 类别未指定HARM_CATEGORY_DEROGATORY: PaLM - 针对身份和/或受保护属性的负面或有害评论HARM_CATEGORY_TOXICITY: PaLM - 粗鲁、无礼或亵渎性的内容HARM_CATEGORY_VIOLENCE: PaLM - 描述描绘针对个人或团体的暴力行为的场景HARM_CATEGORY_SEXUAL: PaLM - 包含对性行为或其他淫秽内容的引用HARM_CATEGORY_MEDICAL: PaLM - 宣传未经核实的医疗建议HARM_CATEGORY_DANGEROUS: PaLM - 危险内容会宣扬、助长或鼓励有害行为HARM_CATEGORY_HARASSMENT: Gemini - 骚扰内容HARM_CATEGORY_HATE_SPEECH: Gemini - 仇恨言论和内容HARM_CATEGORY_SEXUALLY_EXPLICIT: Gemini - 露骨色情内容HARM_CATEGORY_DANGEROUS_CONTENT: Gemini - 危险内容HARM_CATEGORY_CIVIC_INTEGRITY: Gemini - 可能用于破坏公民诚信的内容
HarmProbability 完整枚举值:
HARM_PROBABILITY_UNSPECIFIED: 概率未指定NEGLIGIBLE: 内容不安全的概率可忽略不计LOW: 内容不安全的概率较低MEDIUM: 内容不安全的概率为中等HIGH: 内容不安全的概率较高
Modality 完整枚举值:
MODALITY_UNSPECIFIED: 未指定模态TEXT: 纯文本IMAGE: 图片VIDEO: 视频AUDIO: 音频DOCUMENT: 文档,例如PDF
MediaResolution 完整枚举值:
MEDIA_RESOLUTION_UNSPECIFIED: 未设置媒体分辨率MEDIA_RESOLUTION_LOW: 媒体分辨率设为低(64个令牌)MEDIA_RESOLUTION_MEDIUM: 媒体分辨率设为中等(256个令牌)MEDIA_RESOLUTION_HIGH: 媒体分辨率设为高(使用256个令牌进行缩放重新取景)
UrlRetrievalStatus 完整枚举值:
URL_RETRIEVAL_STATUS_UNSPECIFIED: 默认值,此值未使用URL_RETRIEVAL_STATUS_SUCCESS: 网址检索成功URL_RETRIEVAL_STATUS_ERROR: 由于出错,网址检索失败
🔍 错误处理¶
常见错误码¶
| 错误码 | 描述 | 
|---|---|
400 |  请求格式错误或参数无效 | 
401 |  API密钥无效或缺失 | 
403 |  权限不足或配额限制 | 
429 |  请求频率过高 | 
500 |  服务器内部错误 | 
详细错误码说明¶
| 错误码 | 状态 | 描述 | 解决方案 | 
|---|---|---|---|
400 |  INVALID_ARGUMENT |  请求参数无效或格式错误 | 检查请求参数格式和必需字段 | 
400 |  FAILED_PRECONDITION |  请求的前置条件不满足 | 确保满足API调用的前置条件 | 
401 |  UNAUTHENTICATED |  API密钥无效、缺失或已过期 | 检查API密钥的有效性和格式 | 
403 |  PERMISSION_DENIED |  权限不足或配额已用完 | 检查API密钥权限或升级配额 | 
404 |  NOT_FOUND |  指定的模型或资源不存在 | 验证模型名称和资源路径 | 
413 |  PAYLOAD_TOO_LARGE |  请求体太大 | 减少输入内容大小或分批处理 | 
429 |  RESOURCE_EXHAUSTED |  请求频率超限或配额不足 | 降低请求频率或等待配额重置 | 
500 |  INTERNAL |  服务器内部错误 | 重试请求,如持续出现联系支持 | 
503 |  UNAVAILABLE |  服务暂时不可用 | 等待一段时间后重试 | 
504 |  DEADLINE_EXCEEDED |  请求超时 | 减少输入大小或重试请求 |