ZestAI
API文档

Gemini 原生格式调用

使用 Google Gemini 原生 SDK(google-genai / @google/genai)通过 Python、JavaScript 或 HTTP 请求调用 Gemini 模型的完整示例与参数说明。

我们支持 Google Gemini 原生协议,您可以使用官方 SDK(google-genai / @google/genai)直接接入,只需将 base_url 指向我们的平台地址,其余代码无需改动。

如果您不需要使用 Gemini 原生特性(如 Think 模式、结构化输出等),也可以直接使用 OpenAI 格式 调用 Gemini 模型,更加简便。

接入配置

配置项
Base URLhttps://api.zestai.pro
API Key您在控制台创建的 sk- 开头的令牌
SDK 会在 Base URL 后自动拼接 v1beta/... 等路径,请勿手动在 Base URL 中加入 v1beta

安装 SDK

pip 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)

带系统提示词

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)

流式输出(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)

多轮对话(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}")

图像理解(多模态)

支持直接传入图片字节数据进行理解与分析,适用于 gemini-2.5-progemini-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)

HTTP 接口说明

接口地址格式

功能方法接口地址
普通生成POSThttps://api.zestai.pro/v1beta/models/{model}:generateContent
流式生成POSThttps://api.zestai.pro/v1beta/models/{model}:streamGenerateContent

请求头

HeaderValue说明
Content-Typeapplication/json固定值
x-goog-api-keysk-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() 主要参数

参数类型必填说明
modelstring模型 ID,例如 gemini-2.5-progemini-3-flash-preview
contentsstring / array输入内容,可以是纯文本字符串,或包含文本、图片等 Part 的数组
configobject生成参数配置,见下表

config / generationConfig 常用字段

字段PythonJavaScriptHTTP JSON默认值说明
系统提示词system_instructionsystemInstructionsystem_instruction设定模型角色与行为的系统级指令
最大输出长度max_output_tokensmaxOutputTokensmaxOutputTokens模型默认值限制单次回复最大 Token 数
随机性temperaturetemperaturetemperature1.0范围 0~2,越低越稳定,越高越创意
核采样top_ptopPtopP0.95temperature 二选一,请勿同时修改
候选数量candidate_countcandidateCountcandidateCount1单次请求返回的候选回复数量
停止词stop_sequencesstopSequencesstopSequences遇到指定字符串时停止,传入字符串数组
响应格式response_mime_typeresponseMimeTyperesponseMimeTypetext/plain可设为 application/json 开启结构化输出

与 OpenAI 格式对比

特性Gemini 原生格式OpenAI 兼容格式
Base URLhttps://api.zestai.prohttps://api.zestai.pro/v1
SDKgoogle-genai / @google/genaiopenai / openai npm 包
鉴权 Headerx-goog-api-keyAuthorization: Bearer
多轮对话 roleuser / modeluser / assistant
系统提示词system_instruction 独立字段messagesrole: "system"
多轮对话client.chats.create() 原生 Chat 对象手动维护 messages 数组
流式端点:streamGenerateContentstream: true 参数
图像输入Part.from_bytes() / inline_dataimage_url 类型的 content part
两种格式均可调用 Gemini 系列模型,功能上基本等价。如果您的项目已使用 OpenAI SDK,直接使用 OpenAI 格式 即可,无需切换 SDK。