跳转至

Google Gemini 对话格式（Generate Content）

官方文档

Google Gemini Generating content API

📝 简介

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

音频处理 ✅

# 使用File API上传音频数据到API请求
MIME_TYPE=$(file -b --mime-type "${AUDIO_PATH}")
NUM_BYTES=$(wc -c < "${AUDIO_PATH}")
DISPLAY_NAME=AUDIO

tmp_header_file=upload-header.tmp

# 初始可恢复请求定义元数据
# 上传URL在响应头中，将其转储到文件
curl "${BASE_URL}/upload/v1beta/files?key=${NEWAPI_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}"

# 上传实际字节
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://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 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

视频处理 ✅

# 使用File API上传视频数据到API请求
MIME_TYPE=$(file -b --mime-type "${VIDEO_PATH}")
NUM_BYTES=$(wc -c < "${VIDEO_PATH}")
DISPLAY_NAME=VIDEO

# 初始可恢复请求定义元数据
# 上传URL在响应头中，将其转储到文件
curl "${BASE_URL}/upload/v1beta/files?key=${NEWAPI_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}"

# 上传实际字节
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
  # 获取感兴趣的文件以检查状态
  curl https://api.zetatechs.com/v1beta/files/$name > file_info.json
  state=$(jq ".file.state" file_info.json)
done

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, 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处理 ✅

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

# 初始可恢复请求定义元数据
# 上传URL在响应头中，将其转储到文件
curl "${BASE_URL}/upload/v1beta/files?key=${NEWAPI_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}"

# 上传实际字节
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

# 现在使用该文件生成内容
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?"},
          {"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

聊天对话 ✅

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

📮 请求

端点

生成内容

POST https://api.zetatechs.com/v1beta/{model=models/*}:generateContent

流式生成内容

POST https://api.zetatechs.com/v1beta/{model=models/*}:streamGenerateContent

鉴权方法

在请求URL参数中包含API密钥：

?key=$NEWAPI_API_KEY

其中 $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 请求超时 减少输入大小或重试请求

错误响应示例

{
  "error": {
    "code": 400,
    "message": "Invalid argument: contents",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "contents",
            "description": "contents is required"
          }
        ]
      }
    ]
  }
}