1. 模型指南
undyingapi
  • 面板功能
  • 渠道指南
  • 模型指南
    • Gemini API 使用文档
  • 聊天(Chat)
    • 谷歌Gemini 接口
      • 原生格式
        • 图片生成
        • 图片生成 gemini-2.5-flash-image
        • 图片生成 gemini-2.5-flash-image 控制宽高比
        • 图片生成 gemini-3-pro-image-preview 控制宽高比 +清晰度
  • 应用设置教程
    • 获取令牌
    • Cherry Studio
    • 在线画图
    • Chat Box
  1. 模型指南

Gemini API 使用文档

1.Gemini 简介#

Geimin官方文档:https://ai.google.dev/api/generate-content?hl=zh-cn
Google Gemini API 是一个 多模态生成接口,支持开发者基于多种输入类型(包括文本、图像、音频、代码以及外部工具调用)来创建和处理内容。
通过 GenerateContentRequest 请求,模型能够生成多类型响应,具备以下主要功能特性:
文本生成:支持自然语言写作、摘要、翻译、问答与对话生成。
视觉理解:支持图像识别、描述生成、图文推理等任务。
音频处理:可进行语音识别、语义理解及音频内容生成。
长上下文理解:支持处理更长文本与多模态输入,保持语义一致性。
代码生成与执行:具备编写、解释与运行代码的能力。
结构化输出:支持以 JSON Schema 等格式输出结构化结果。
函数调用与工具集成:可与外部 API、数据库或自定义工具进行交互调用。
凭借上述能力,Gemini API 构建了一个集 感知、推理与交互 于一体的多模态智能生成平台,适用于从文本创作到复杂任务编排的多种应用场景。

下面是一些常用的 Gemini API 请求示例。

2.请求示例#

基础文本对话#

图像分析对话#

# 使用临时文件保存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://vip.undyingapi.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://vip.undyingapi.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 模式响应

视频处理#

**文件上传限制:**仅支持通过 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://vip.undyingapi.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://vip.undyingapi.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"

聊天对话#

流式响应#

代码执行#

生成配置#

安全设置#

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://vip.undyingapi.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

系统指令#

3.Gemini CLI 配置#

配置准备工作#

Node.js: 已安装 Node.js version 18 或更高版本。
API 令牌: 您在 vip.undyingapi.com 申请用于 Gemini 的 API 令牌。
**配置BASE_URL:**地址为 https://vip.undyingapi.com

安装 Gemini CLI#

无论您使用 macOS, Linux 还是 Windows,安装 Gemini CLI 的步骤都是一致的:
npm install -g @google/gemini-cli
这个命令会全局安装 @google/gemini-cli 包,使其可以在任何终端中使用。

配置环境变量#

macOS 用户#
在 macOS 上,默认的 Shell 是 zsh。推荐将环境变量写入 ~/.zshrc 文件。如果您使用的是 bash,则可以写入 ~/.bashrc 或 ~/.profile。
添加环境变量
打开终端,执行以下命令将环境变量添加到 ~/.zshrc 文件末尾:
echo 'export GOOGLE_GEMINI_BASE_URL=https://vip.undyingapi.com' >> ~/.zshrc
echo 'export GEMINI_API_KEY="你在undyingapi.com申请的令牌"' >> ~/.zshrc
刷新环境变量:
执行以下命令使更改立即生效:
source ~/.zshrc
验证配置:**
您可以运行以下命令来检查环境变量是否已成功设置:
echo $GOOGLE_GEMINI_BASE_URL
echo $GEMINI_API_KEY
Linux 用户#
在大多数 Linux 发行版中,bash 是常见的 Shell。推荐将环境变量写入 ~/.bashrc 文件。
添加环境变量:
打开终端,执行以下命令将环境变量添加到 ~/.bashrc 文件末尾:
echo 'export GOOGLE_GEMINI_BASE_URL=https://vip.undyingapi.com' >> ~/.bashrc
echo 'export GEMINI_API_KEY="vip.undyingapi.com申请的令牌"' >> ~/.bashrc
刷新环境变量:
执行以下命令使更改立即生效:
source ~/.bashrc
验证配置:**
您可以运行以下命令来检查环境变量是否已成功设置:
echo $GOOGLE_GEMINI_BASE_URL
echo $GEMINI_API_KEY
若您使用其他 Shell (如 fish, zsh),请将变量写入对应的启动配置文件,并使用该 Shell 的加载命令。
Windows 用户#
Windows 系统设置环境变量有多种方法,推荐使用永久设置。
命令行永久设置 (推荐):
打开 命令提示符 (CMD) 或 PowerShell,运行以下命令。这将为当前用户永久设置环境变量,新的终端会话会加载这些变量。
:: CMD 命令
setx GOOGLE_GEMINI_BASE_URL "https://vip.undyingapi.com"
setx GEMINI_API_KEY "vip.undyingapi.com申请的令牌"
或者在 PowerShell 中:
:: PowerShell 命令 (注意 setx 在 PowerShell 中也能用)
[System.Environment]::SetEnvironmentVariable('GOOGLE_GEMINI_BASE_URL', 'https://vip.undyingapi.com', 'User')
[System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'vip.undyingapi.com申请的令牌', 'User')
设置后,请重启终端或 打开新的终端窗口 使环境变量生效。

图形界面手动设置:
这种方法通过 Windows 的用户界面来设置:
打开 开始菜单,搜索并选择 “编辑系统环境变量”。
点击右下角的 “环境变量(N)...” 按钮。
在 “用户变量” 部分下(通常是上半部分),点击 “新建...”。
分别添加以下两个用户变量:
变量名: GOOGLE_GEMINI_BASE_URL
变量值: https://vip.undyingapi.com
变量名: GEMINI_API_KEY
变量值: vip.undyingapi.com申请的令牌
点击 “确定” 保存所有更改。
同样,设置后请重启终端或 打开新的终端窗口。
临时设置 (仅当前终端会话有效):
PowerShell:
$env:GOOGLE_GEMINI_BASE_URL = "https://vip.undyingapi.com"
$env:GEMINI_API_KEY = "vip.undyingapi.com申请的令牌"
CMD:
set GOOGLE_GEMINI_BASE_URL=https://vip.undyingapi.com
set GEMINI_API_KEY=vip.undyingapi.com申请的令牌
注意: 这种方法设置的环境变量在当前终端关闭后会失效,不推荐长期使用。
Git Bash / WSL 用户:
如果您在 Windows 上使用 Git Bash 或 WSL (Windows Subsystem for Linux),您可以按照上述 Linux 用户 的方式配置,将变量写入 ~/.bashrc 后 source ~/.bashrc。

启动 Gemini CLI#

环境变量设置完成后,您就可以启动 Gemini CLI 了:
gemini
进入交互界面后,选择「Use Gemini API Key」选项即可开启与 Gemini 模型的聊天。

常见问题与故障排除#

环境变量未生效:
确保您已按照操作系统的指示刷新或重新加载了环境变量(例如 source ~/.zshrc 或重启终端)。
仔细检查环境变量的拼写和值是否正确。
在终端中运行 echo GOOGLEG​EMINIB​ASEU​RL和echoGEMINI_API_KEY 来验证它们是否被正确设置。
gemini 命令未找到:
确认您已成功安装 Node.js (version 18+) 和 @google/gemini-cli (npm install -g @google/gemini-cli)。
检查 Node.js 的全局包路径是否已添加到系统的 PATH 环境变量中。
连接失败或认证错误:
确认您的 GEMINI_API_KEY 是从 undyingapi.com 申请的有效令牌。
确认 GOOGLE_GEMINI_BASE_URL 设置为 https://vip.undyingapi.com。
检查您的网络连接是否正常。

4.请求#

端点#

生成内容#
POST https://vip.undyingapi.com/v1beta/{model=models/*}:generateContent
流式生成内容#
POST https://vip.undyingapi.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: 模型不能调用函数
SafetySetting#
类型:数组
必需:否
用于屏蔽不安全内容的 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}

5.响应#

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

6.高级功能#

安全评级#

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: 由于出错,网址检索失败

7.错误处理#

常见错误码#

错误码描述
400请求格式错误或参数无效
401API密钥无效或缺失
403权限不足或配额限制
429请求频率过高
500服务器内部错误

详细错误码说明#

错误码状态描述解决方案
400INVALID_ARGUMENT请求参数无效或格式错误检查请求参数格式和必需字段
400FAILED_PRECONDITION请求的前置条件不满足确保满足API调用的前置条件
401UNAUTHENTICATEDAPI密钥无效、缺失或已过期检查API密钥的有效性和格式
403PERMISSION_DENIED权限不足或配额已用完检查API密钥权限或升级配额
404NOT_FOUND指定的模型或资源不存在验证模型名称和资源路径
413PAYLOAD_TOO_LARGE请求体太大减少输入内容大小或分批处理
429RESOURCE_EXHAUSTED请求频率超限或配额不足降低请求频率或等待配额重置
500INTERNAL服务器内部错误重试请求,如持续出现联系支持
503UNAVAILABLE服务暂时不可用等待一段时间后重试
504DEADLINE_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"
          }
        ]
      }
    ]
  }
}
修改于 2025-10-30 02:14:36
上一页
渠道指南
下一页
图片生成
Built with