Gemini 协议
POST https://api.easyx.ai/v1beta/models/gemini-2.5-flash:generateContent
x-goog-api-key: easyx_ws_xxx
Content-Type: application/json请求示例
文本生成
curl https://api.easyx.ai/v1beta/models/gemini-2.5-flash:generateContent \
-H "x-goog-api-key: easyx_ws_xxx" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"role": "user",
"parts": [
{
"text": "写一个关于魔法背包的故事。"
}
]
}
]
}'系统指令与多轮对话
curl https://api.easyx.ai/v1beta/models/gemini-2.5-flash:generateContent \
-H "x-goog-api-key: easyx_ws_xxx" \
-H "Content-Type: application/json" \
-d '{
"systemInstruction": {
"parts": [
{
"text": "请用中文回答。"
}
]
},
"contents": [
{
"role": "user",
"parts": [
{
"text": "我叫小明。"
}
]
},
{
"role": "model",
"parts": [
{
"text": "你好,小明。"
}
]
},
{
"role": "user",
"parts": [
{
"text": "我叫什么名字?"
}
]
}
]
}'图片理解
curl https://api.easyx.ai/v1beta/models/gemini-2.5-flash:generateContent \
-H "x-goog-api-key: easyx_ws_xxx" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"role": "user",
"parts": [
{
"text": "这张图片里有什么?"
},
{
"inlineData": {
"mimeType": "image/png",
"data": "BASE64_IMAGE"
}
}
]
}
]
}'结构化 JSON 输出
curl https://api.easyx.ai/v1beta/models/gemini-2.5-flash:generateContent \
-H "x-goog-api-key: easyx_ws_xxx" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"parts": [
{
"text": "提取姓名:我叫小明。"
}
]
}
],
"generationConfig": {
"responseMimeType": "application/json",
"responseSchema": {
"type": "OBJECT",
"properties": {
"name": {
"type": "STRING"
}
},
"required": [
"name"
]
}
}
}'函数调用
curl https://api.easyx.ai/v1beta/models/gemini-2.5-flash:generateContent \
-H "x-goog-api-key: easyx_ws_xxx" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"parts": [
{
"text": "北京的天气怎么样?"
}
]
}
],
"tools": [
{
"functionDeclarations": [
{
"name": "get_weather",
"description": "查询指定城市的天气",
"parameters": {
"type": "OBJECT",
"properties": {
"location": {
"type": "STRING"
}
},
"required": [
"location"
]
}
}
]
}
]
}'文生图
curl https://api.easyx.ai/v1beta/models/gemini-2.5-flash-image:generateContent \
-H "x-goog-api-key: easyx_ws_xxx" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"parts": [
{
"text": "画一只戴红帽子的柴犬。"
}
]
}
],
"generationConfig": {
"responseModalities": [
"TEXT",
"IMAGE"
]
}
}'参考图生图
curl https://api.easyx.ai/v1beta/models/gemini-2.5-flash-image:generateContent \
-H "x-goog-api-key: easyx_ws_xxx" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"parts": [
{
"inlineData": {
"mimeType": "image/png",
"data": "BASE64_IMAGE"
}
},
{
"text": "给图中的动物加一顶红帽子。"
}
]
}
],
"generationConfig": {
"responseModalities": [
"TEXT",
"IMAGE"
]
}
}'BASE64_IMAGE 填入图片文件的 base64 内容,不包含 data URL 前缀。图片理解与生图需要选择支持对应输入、输出模态的模型。
函数调用结果
函数调用出现在 candidates[].content.parts[].functionCall。应用执行函数后,保留模型返回的 parts(包括存在时的 thoughtSignature),再将对应的 functionResponse 与历史内容一起发回。
{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"functionCall": {
"name": "get_weather",
"args": {
"location": "北京"
}
}
}
]
}
}
]
}curl https://api.easyx.ai/v1beta/models/gemini-2.5-flash-image:generateContent \
-H "x-goog-api-key: easyx_ws_xxx" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"role": "user",
"parts": [
{
"text": "北京的天气怎么样?"
}
]
},
{
"role": "model",
"parts": [
{
"functionCall": {
"name": "get_weather",
"args": {
"location": "北京"
}
}
}
]
},
{
"role": "user",
"parts": [
{
"functionResponse": {
"name": "get_weather",
"response": {
"temperature": 22,
"condition": "晴"
}
}
}
]
}
],
"tools": [
{
"functionDeclarations": [
{
"name": "get_weather",
"parameters": {
"type": "OBJECT",
"properties": {
"location": {
"type": "STRING"
}
},
"required": [
"location"
]
}
}
]
}
]
}'流式生成
curl -N https://api.easyx.ai/v1beta/models/gemini-2.5-flash-image:streamGenerateContent \
-H "x-goog-api-key: easyx_ws_xxx" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"parts": [
{
"text": "讲一个简短的故事。"
}
]
}
]
}'data: {"candidates":[{"content":{"role":"model","parts":[{"text":"从前"}]}}]}
data: {"candidates":[{"content":{"role":"model","parts":[{"text":"有一只小兔子。"}]},"finishReason":"STOP"}],"usageMetadata":{"promptTokenCount":10,"candidatesTokenCount":8,"totalTokenCount":18}}每个事件包含一个 GenerateContentResponse。按顺序读取 parts 中的 text,并检查 finishReason;Gemini 流不使用 OpenAI 的 [DONE] 标记。
请求参数
contents
- 类型:数组
- 必需:是
与模型当前对话的内容。对于单轮查询,这是单个实例。对于聊天等多轮查询,这是包含对话历史记录和最新请求的重复字段。
Content 对象属性:
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
parts | 数组 | 是 | 有序的内容部分,构成单个消息 |
role | 字符串 | 否 | 对话中内容的生产者。user 或 model |
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 | 整数 | 否 | 候选回答中包含的 token 数量上限 |
temperature | 数字 | 否 | 控制输出的随机性,范围[0.0, 2.0] |
topP | 数字 | 否 | 在抽样时要考虑的 token 的累计概率上限 |
topK | 整数 | 否 | 抽样时要考虑的 token 数量上限 |
seed | 整数 | 否 | 解码中使用的种子 |
presencePenalty | 数字 | 否 | 存在性惩罚 |
frequencyPenalty | 数字 | 否 | 频率惩罚 |
responseLogprobs | 布尔值 | 否 | 是否在响应中导出logprobs结果 |
logprobs | 整数 | 否 | 返回的顶部logprob的数量 |
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: 代码执行超时
generationConfig.imageConfig
| 参数 | 类型 | 说明 |
|---|---|---|
aspectRatio | string | 宽高比,如 1:1、16:9、9:16,支持情况由模型决定。 |
imageSize | string | 分辨率档位,如 1K、2K、4K,可用档位随生图模型而不同。 |
响应
{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"text": "你好!"
}
]
},
"finishReason": "STOP",
"index": 0
}
],
"usageMetadata": {
"promptTokenCount": 10,
"candidatesTokenCount": 3,
"totalTokenCount": 13
},
"modelVersion": "gemini-2.5-flash-image"
}文本在 candidates[].content.parts[].text 中;图片在 inlineData.data 中,以 inlineData.mimeType 标识格式,保存前需要解码 base64。响应可以包含多个 part,也可能包含思考或函数调用。candidates 缺失或为空时,检查 promptFeedback。
图片响应
{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"inlineData": {
"mimeType": "image/png",
"data": "BASE64_IMAGE"
}
}
]
},
"finishReason": "STOP"
}
]
}import base64
import mimetypes
from pathlib import Path
# response is the parsed JSON response
for candidate in response.get("candidates", []):
for index, part in enumerate(candidate.get("content", {}).get("parts", [])):
image = part.get("inlineData")
if image:
extension = mimetypes.guess_extension(image["mimeType"]) or ".bin"
Path(f"image-{index}{extension}").write_bytes(
base64.b64decode(image["data"])
)GenerateContentResponse
支持多个候选回答的模型的回答。系统会针对提示以及每个候选项报告安全分级和内容过滤。
candidates
- 类型:数组
- 说明:模型的候选回答列表
Candidate 对象属性:
| 属性 | 类型 | 描述 |
|---|---|---|
content | 对象 | 模型返回的生成内容 |
finishReason | 枚举 | 模型停止生成 token 的原因 |
safetyRatings | 数组 | 候选回答安全性的评分列表 |
citationMetadata | 对象 | 模型生成的候选项的引用信息 |
tokenCount | 整数 | 此候选项的 token 数 |
groundingAttributions | 数组 | 为生成有依据的回答所参考的来源提供方信息 |
groundingMetadata | 对象 | 候选对象的参考元数据 |
avgLogprobs | 数字 | 候选项的平均对数概率得分 |
logprobsResult | 对象 | 回答 token 和前置 token 的对数似然度得分 |
urlRetrievalMetadata | 对象 | 与网址情境检索工具相关的元数据 |
urlContextMetadata | 对象 | 与网址情境检索工具相关的元数据 |
index | 整数 | 响应候选列表中候选项的索引 |
FinishReason 枚举值:
STOP: 模型的自然停止点或提供的停止序列MAX_TOKENS: 已达到请求中指定的 token 数量上限SAFETY: 出于安全考虑,系统已标记回答候选内容RECITATION: 由于背诵原因,回答候选内容被标记LANGUAGE: 回答候选内容因使用不受支持的语言而被标记OTHER: 原因未知BLOCKLIST: 由于内容包含禁止使用的字词,因此 token 生成操作已停止PROHIBITED_CONTENT: 由于可能包含禁止的内容,因此 token 生成操作已停止SPII: 由于内容可能包含敏感的个人身份信息,因此 token 生成操作已停止MALFORMED_FUNCTION_CALL: 模型生成的函数调用无效IMAGE_SAFETY: 由于生成的图片违反了安全规定,因此 token 生成已停止
promptFeedback
- 类型:对象
- 说明:与内容过滤器相关的提示反馈
PromptFeedback 对象属性:
| 属性 | 类型 | 描述 |
|---|---|---|
blockReason | 枚举 | 屏蔽该提示的原因 |
safetyRatings | 数组 | 问题安全性的评分 |
BlockReason 枚举值:
BLOCK_REASON_UNSPECIFIED: 默认值,此值未使用SAFETY: 出于安全原因,系统屏蔽了提示OTHER: 提示因未知原因被屏蔽了BLOCKLIST: 系统屏蔽了此提示,因为其中包含术语屏蔽名单中包含的术语PROHIBITED_CONTENT: 系统屏蔽了此提示,因为其中包含禁止的内容IMAGE_SAFETY: 候选图片因生成不安全的内容而被屏蔽
usageMetadata
- 类型:对象
- 说明:有关生成请求 token 用量的元数据
UsageMetadata 对象属性:
| 属性 | 类型 | 描述 |
|---|---|---|
promptTokenCount | 整数 | 提示中的 token 数 |
cachedContentTokenCount | 整数 | 提示的缓存部分中的 token 数 |
candidatesTokenCount | 整数 | 所有生成的候选回答中的 token 总数 |
totalTokenCount | 整数 | 生成请求的总 token 数 |
toolUsePromptTokenCount | 整数 | 工具使用提示中的 token 数量 |
thoughtsTokenCount | 整数 | 思考模型的想法 token 数 |
promptTokensDetails | 数组 | 在请求输入中处理的模态列表 |
candidatesTokensDetails | 数组 | 响应中返回的模态列表 |
cacheTokensDetails | 数组 | 请求输入中缓存内容的模态列表 |
toolUsePromptTokensDetails | 数组 | 为工具使用请求输入处理的模态列表 |
modelVersion
- 类型:字符串
- 说明:用于生成回答的模型版本
responseId
- 类型:字符串
- 说明:用于标识每个响应的ID
Python SDK
pip install google-genaifrom google import genai
from google.genai import types
client = genai.Client(
api_key="easyx_ws_xxx",
http_options=types.HttpOptions(
base_url="https://api.easyx.ai",
api_version="v1beta",
),
)
response = client.models.generate_content(model="gemini-2.5-flash", contents="Hello")
print(response.text)
for chunk in client.models.generate_content_stream(
model="gemini-2.5-flash", contents="Hello"
):
if chunk.text:
print(chunk.text, end="", flush=True)Node.js SDK
npm install @google/genaiimport { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({
apiKey: "easyx_ws_xxx",
httpOptions: {
baseUrl: "https://api.easyx.ai",
apiVersion: "v1beta",
},
});
const response = await client.models.generateContent({
model: "gemini-2.5-flash",
contents: "Hello",
});
console.log(response.text);