EasyXAI 文档
API 接入

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

参数类型说明
aspectRatiostring宽高比,如 1:1、16:9、9:16,支持情况由模型决定。
imageSizestring分辨率档位,如 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-genai
from 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/genai
import { 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);

Gemini GenerateContent reference

Google Gen AI SDK