Gemini 原生格式调用
我们支持 Google Gemini 原生协议,您可以使用官方 SDK(google-genai / @google/genai)直接接入,只需将 base_url 指向我们的平台地址,其余代码无需改动。
接入配置
| 配置项 | 值 |
|---|---|
| Base URL | https://api.zestai.pro |
| API Key | 您在控制台创建的 sk- 开头的令牌 |
v1beta/... 等路径,请勿手动在 Base URL 中加入 v1beta。安装 SDK
pip install google-genai
npm install @google/genai
快速示例
from google import genai
client = genai.Client(
api_key="sk-your-api-key", # 替换为您的令牌
http_options={"base_url": "https://api.zestai.pro"},
)
response = client.models.generate_content(
model="gemini-2.5-pro", # 替换为您想使用的模型
contents="你好,请介绍一下你自己。",
)
print(response.text)
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({
apiKey: "sk-your-api-key", // 替换为您的令牌
httpOptions: {
baseUrl: "https://api.zestai.pro",
},
});
const response = await ai.models.generateContent({
model: "gemini-2.5-pro", // 替换为您想使用的模型
contents: "你好,请介绍一下你自己。",
});
console.log(response.text);
POST https://api.zestai.pro/v1beta/models/gemini-2.5-pro:generateContent
Headers
| Key | Value |
|---|---|
Content-Type | application/json |
x-goog-api-key | sk-your-api-key |
Body
{
"contents": [
{
"parts": [{ "text": "你好,请介绍一下你自己。" }]
}
]
}
带系统提示词
from google import genai
from google.genai import types
client = genai.Client(
api_key="sk-your-api-key",
http_options={"base_url": "https://api.zestai.pro"},
)
response = client.models.generate_content(
model="gemini-2.5-pro",
contents="写一首关于秋天的诗。",
config=types.GenerateContentConfig(
system_instruction="你是一位擅长写古典诗词的诗人,请用古诗词风格回答。",
temperature=0.8,
max_output_tokens=512,
),
)
print(response.text)
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({
apiKey: "sk-your-api-key",
httpOptions: { baseUrl: "https://api.zestai.pro" },
});
const response = await ai.models.generateContent({
model: "gemini-2.5-pro",
contents: "写一首关于秋天的诗。",
config: {
systemInstruction: "你是一位擅长写古典诗词的诗人,请用古诗词风格回答。",
temperature: 0.8,
maxOutputTokens: 512,
},
});
console.log(response.text);
POST https://api.zestai.pro/v1beta/models/gemini-2.5-pro:generateContent
Headers
| Key | Value |
|---|---|
Content-Type | application/json |
x-goog-api-key | sk-your-api-key |
Body
{
"system_instruction": {
"parts": [{ "text": "你是一位擅长写古典诗词的诗人,请用古诗词风格回答。" }]
},
"contents": [
{
"parts": [{ "text": "写一首关于秋天的诗。" }]
}
],
"generationConfig": {
"temperature": 0.8,
"maxOutputTokens": 512
}
}
流式输出(Streaming)
from google import genai
client = genai.Client(
api_key="sk-your-api-key",
http_options={"base_url": "https://api.zestai.pro"},
)
for chunk in client.models.generate_content_stream(
model="gemini-2.5-pro",
contents="请详细介绍一下黑洞的形成过程。",
):
print(chunk.text, end="", flush=True)
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({
apiKey: "sk-your-api-key",
httpOptions: { baseUrl: "https://api.zestai.pro" },
});
const stream = await ai.models.generateContentStream({
model: "gemini-2.5-pro",
contents: "请详细介绍一下黑洞的形成过程。",
});
for await (const chunk of stream) {
process.stdout.write(chunk.text ?? "");
}
流式接口使用独立的 :streamGenerateContent 端点,响应为持续推送的 JSON 数组片段。
POST https://api.zestai.pro/v1beta/models/gemini-2.5-pro:streamGenerateContent
Headers
| Key | Value |
|---|---|
Content-Type | application/json |
x-goog-api-key | sk-your-api-key |
Body
{
"contents": [
{
"parts": [{ "text": "请详细介绍一下黑洞的形成过程。" }]
}
]
}
多轮对话(Chat)
Gemini SDK 提供了原生的 Chat 会话对象,可自动维护对话历史,无需手动管理消息数组。
from google import genai
from google.genai import types
client = genai.Client(
api_key="sk-your-api-key",
http_options={"base_url": "https://api.zestai.pro"},
)
# 创建 Chat 会话(历史自动维护)
chat = client.chats.create(
model="gemini-2.5-pro",
config=types.GenerateContentConfig(
system_instruction="你是一个有帮助的助手。",
),
)
response1 = chat.send_message("我叫小明,我是一名程序员。")
print(f"助手: {response1.text}")
response2 = chat.send_message("你还记得我是做什么的吗?")
print(f"助手: {response2.text}")
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({
apiKey: "sk-your-api-key",
httpOptions: { baseUrl: "https://api.zestai.pro" },
});
// 创建 Chat 会话(历史自动维护)
const chat = ai.chats.create({
model: "gemini-2.5-pro",
config: {
systemInstruction: "你是一个有帮助的助手。",
},
});
const response1 = await chat.sendMessage({ message: "我叫小明,我是一名程序员。" });
console.log(`助手: ${response1.text}`);
const response2 = await chat.sendMessage({ message: "你还记得我是做什么的吗?" });
console.log(`助手: ${response2.text}`);
HTTP 请求需手动在 contents 中传入完整对话历史。注意 Gemini 原生的历史消息 role 为 user / model,与 OpenAI 的 assistant 不同。
POST https://api.zestai.pro/v1beta/models/gemini-2.5-pro:generateContent
Headers
| Key | Value |
|---|---|
Content-Type | application/json |
x-goog-api-key | sk-your-api-key |
Body
{
"contents": [
{
"role": "user",
"parts": [{ "text": "我叫小明,我是一名程序员。" }]
},
{
"role": "model",
"parts": [{ "text": "你好,小明!很高兴认识你,有什么我可以帮助你的吗?" }]
},
{
"role": "user",
"parts": [{ "text": "你还记得我是做什么的吗?" }]
}
]
}
图像理解(多模态)
支持直接传入图片字节数据进行理解与分析,适用于 gemini-2.5-pro、gemini-2.0-flash 等具备视觉能力的模型。
import httpx
from google import genai
from google.genai import types
client = genai.Client(
api_key="sk-your-api-key",
http_options={"base_url": "https://api.zestai.pro"},
)
# 从 URL 获取图片字节
image_bytes = httpx.get("https://example.com/image.jpg").content
response = client.models.generate_content(
model="gemini-2.5-pro",
contents=[
types.Part.from_bytes(
data=image_bytes,
mime_type="image/jpeg", # 支持 image/jpeg, image/png, image/webp, image/gif
),
"请描述这张图片的内容。",
],
)
print(response.text)
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({
apiKey: "sk-your-api-key",
httpOptions: { baseUrl: "https://api.zestai.pro" },
});
// 从 URL 获取图片并转为 base64
const imageResp = await fetch("https://example.com/image.jpg");
const imageBytes = await imageResp.arrayBuffer();
const base64Image = Buffer.from(imageBytes).toString("base64");
const response = await ai.models.generateContent({
model: "gemini-2.5-pro",
contents: [
{
parts: [
{
inlineData: {
mimeType: "image/jpeg",
data: base64Image,
},
},
{ text: "请描述这张图片的内容。" },
],
},
],
});
console.log(response.text);
图片需提前转为 base64 字符串后填入 inline_data.data 字段。
POST https://api.zestai.pro/v1beta/models/gemini-2.5-pro:generateContent
Headers
| Key | Value |
|---|---|
Content-Type | application/json |
x-goog-api-key | sk-your-api-key |
Body
{
"contents": [
{
"parts": [
{
"inline_data": {
"mime_type": "image/jpeg",
"data": "<base64 编码的图片字符串>"
}
},
{ "text": "请描述这张图片的内容。" }
]
}
]
}
HTTP 接口说明
接口地址格式
| 功能 | 方法 | 接口地址 |
|---|---|---|
| 普通生成 | POST | https://api.zestai.pro/v1beta/models/{model}:generateContent |
| 流式生成 | POST | https://api.zestai.pro/v1beta/models/{model}:streamGenerateContent |
请求头
| Header | Value | 说明 |
|---|---|---|
Content-Type | application/json | 固定值 |
x-goog-api-key | sk-your-api-key | 您的令牌 |
请求体结构
{
"system_instruction": {
"parts": [{ "text": "系统提示词(可选)" }]
},
"contents": [
{
"role": "user",
"parts": [{ "text": "用户输入的内容" }]
}
],
"generationConfig": {
"temperature": 1.0,
"maxOutputTokens": 8192,
"topP": 0.95,
"stopSequences": [],
"candidateCount": 1,
"responseMimeType": "text/plain"
}
}
响应体结构
{
"candidates": [
{
"content": {
"parts": [{ "text": "模型生成的回复内容" }],
"role": "model"
},
"finishReason": "STOP",
"index": 0
}
],
"usageMetadata": {
"promptTokenCount": 10,
"candidatesTokenCount": 50,
"totalTokenCount": 60
},
"modelVersion": "gemini-2.5-pro"
}
| 字段 | 说明 |
|---|---|
candidates[].content.parts[].text | 模型生成的文本内容 |
candidates[].finishReason | 停止原因:STOP(正常结束)、MAX_TOKENS(达到长度限制)、SAFETY(安全过滤) |
usageMetadata.promptTokenCount | 输入消耗的 Token 数 |
usageMetadata.candidatesTokenCount | 输出消耗的 Token 数 |
usageMetadata.totalTokenCount | 本次总 Token 消耗(计费依据) |
请求参数说明
generate_content() / generateContent() 主要参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | ✅ | 模型 ID,例如 gemini-2.5-pro、gemini-3-flash-preview |
contents | string / array | ✅ | 输入内容,可以是纯文本字符串,或包含文本、图片等 Part 的数组 |
config | object | — | 生成参数配置,见下表 |
config / generationConfig 常用字段
| 字段 | Python | JavaScript | HTTP JSON | 默认值 | 说明 |
|---|---|---|---|---|---|
| 系统提示词 | system_instruction | systemInstruction | system_instruction | — | 设定模型角色与行为的系统级指令 |
| 最大输出长度 | max_output_tokens | maxOutputTokens | maxOutputTokens | 模型默认值 | 限制单次回复最大 Token 数 |
| 随机性 | temperature | temperature | temperature | 1.0 | 范围 0~2,越低越稳定,越高越创意 |
| 核采样 | top_p | topP | topP | 0.95 | 与 temperature 二选一,请勿同时修改 |
| 候选数量 | candidate_count | candidateCount | candidateCount | 1 | 单次请求返回的候选回复数量 |
| 停止词 | stop_sequences | stopSequences | stopSequences | — | 遇到指定字符串时停止,传入字符串数组 |
| 响应格式 | response_mime_type | responseMimeType | responseMimeType | text/plain | 可设为 application/json 开启结构化输出 |
与 OpenAI 格式对比
| 特性 | Gemini 原生格式 | OpenAI 兼容格式 |
|---|---|---|
| Base URL | https://api.zestai.pro | https://api.zestai.pro/v1 |
| SDK | google-genai / @google/genai | openai / openai npm 包 |
| 鉴权 Header | x-goog-api-key | Authorization: Bearer |
| 多轮对话 role | user / model | user / assistant |
| 系统提示词 | system_instruction 独立字段 | messages 中 role: "system" |
| 多轮对话 | client.chats.create() 原生 Chat 对象 | 手动维护 messages 数组 |
| 流式端点 | :streamGenerateContent | stream: true 参数 |
| 图像输入 | Part.from_bytes() / inline_data | image_url 类型的 content part |