Gemini 原生

用 Google Gemini API 原生格式调用模型。已有基于 google-genai SDK 或 Gemini REST 的代码,只需把 Base URL 和 API Key 换成平台的即可。

项 值
方法与路径 POST /v1beta/models/{model}:generateContent(非流式)
POST /v1beta/models/{model}:streamGenerateContent?alt=sse(流式)
Base URL(SDK 用) https://www.nextai-code.com(不带 /v1beta,SDK 会自动拼接)
鉴权 x-goog-api-key: YOUR_API_KEY、查询参数 ?key=YOUR_API_KEY、或 Authorization: Bearer YOUR_API_KEY(任选其一)
Content-Type application/json

{model} 即模型 ID,例如 gemini-3.8-flash;可用模型以 模型列表 为准(GET /v1beta/models 返回 Gemini 格式列表)。

快速示例

cURL

BASH
curl "https://www.nextai-code.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $NEXTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "用三句话解释量子纠缠。"}]}
    ]
  }'

流式:

BASH
curl -N "https://www.nextai-code.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $NEXTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "写一首关于秋天的短诗。"}]}]}'

Python(google-genai SDK)

PYTHON
import os
from google import genai
from google.genai import types

client = genai.Client(
    api_key=os.environ["NEXTAI_API_KEY"],
    http_options=types.HttpOptions(base_url="https://www.nextai-code.com"),
)

resp = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="用三句话解释量子纠缠。",
)
print(resp.text)

# 流式
for chunk in client.models.generate_content_stream(
    model="gemini-3.8-flash",
    contents="写一首关于秋天的短诗。",
):
    print(chunk.text or "", end="")

SDK 默认使用 v1beta 路径并以 x-goog-api-key 传 Key,流式自动带 alt=sse,无需额外配置。

请求参数

路径与查询参数

参数 位置 必填 说明
model path 是 模型 ID,写在 /models/ 与 : 之间
alt query 流式必填 流式请求须为 sse。不带 alt=sse 时,即使调用 streamGenerateContent 也按非流式返回
key query 否 API Key 的另一种传法

请求体

参数 类型 必填 说明
contents array 是 对话内容,不能为空。每项为 {"role":"user"|"model","parts":[...]};首条未写 role 时按 user 处理
systemInstruction object 否 系统指令,格式同 contents 的单项(只需 parts)
generationConfig object 否 生成参数,见下表
tools array / object 否 工具:functionDeclarations、googleSearch、googleSearchRetrieval、codeExecution、urlContext
toolConfig object 否 如 functionCallingConfig.mode、allowedFunctionNames
safetySettings array 否 [{"category":"...","threshold":"..."}]
cachedContent string 否 已创建的上下文缓存资源名

parts 支持的类型

字段 说明
text 文本
inlineData 内联媒体 {"mimeType":"image/png","data":"<base64>"},可传图片、音频、视频、文档。也兼容 snake_case 写法 inline_data / mime_type
fileData 文件引用 {"mimeType":"...","fileUri":"..."}。fileUri 为 YouTube 链接时可省略 mimeType
functionCall / functionResponse 函数调用与结果(多轮回传)
executableCode / codeExecutionResult 代码执行相关

generationConfig

参数 类型 说明
temperature number 采样温度
topP / topK number 采样参数
maxOutputTokens integer 最大输出 Token
candidateCount integer 候选数量
stopSequences string[] 停止序列
responseMimeType string 如 application/json
responseSchema / responseJsonSchema object 结构化输出的 Schema
presencePenalty / frequencyPenalty number 惩罚系数
responseLogprobs / logprobs boolean / integer 对数概率
seed integer 随机种子
mediaResolution string 输入媒体分辨率
responseModalities string[] 输出模态,如 ["TEXT","IMAGE"],见 Gemini 图像
thinkingConfig object {"thinkingBudget": N, "includeThoughts": true}
speechConfig / imageConfig object 语音 / 图片输出配置,是否生效取决于模型

以上字段均按 Gemini 官方语义转发给模型服务商,是否生效取决于具体模型。

响应

非流式

JSON
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{"text": "量子纠缠是指……"}]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 120,
    "thoughtsTokenCount": 0,
    "totalTokenCount": 129
  }
}
字段 类型 说明
candidates[].content.parts array 输出内容。开启 includeThoughts 时,思考内容为带 "thought": true 的 part
candidates[].finishReason string STOP、MAX_TOKENS、SAFETY 等
promptFeedback object 输入被拦截时出现,含 blockReason
usageMetadata.promptTokenCount integer 输入 Token
usageMetadata.candidatesTokenCount integer 输出 Token
usageMetadata.thoughtsTokenCount integer 思考 Token(计入输出计费)
usageMetadata.cachedContentTokenCount integer 命中缓存的输入 Token
usageMetadata.totalTokenCount integer 总 Token

使用 Gemini 模型时,响应字段与 Google 官方接口一致。

流式

返回 text/event-stream,每个 data: 行是一个完整的 GenerateContentResponse JSON 片段:

CODE
data: {"candidates":[{"content":{"role":"model","parts":[{"text":"秋风"}]},"index":0}],"usageMetadata":{...}}

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"拂过……"}]},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":10,"candidatesTokenCount":42,"totalTokenCount":52}}
  • 与 Gemini 官方一致,没有 [DONE] 结束标记,连接关闭即结束;带 finishReason 的片段为最后一段。
  • 完整用量以最后一个片段的 usageMetadata 为准。

进阶用法

多模态输入

JSON
{
  "contents": [{
    "role": "user",
    "parts": [
      {"inlineData": {"mimeType": "image/jpeg", "data": "<base64>"}},
      {"text": "这张图里有什么?"}
    ]
  }]
}

函数调用

JSON
{
  "contents": [{"role": "user", "parts": [{"text": "北京现在几点?"}]}],
  "tools": [{
    "functionDeclarations": [{
      "name": "get_time",
      "description": "获取城市当前时间",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }]
  }]
}

模型返回 functionCall part 后,把它作为 role: "model" 消息、把执行结果作为 {"functionResponse":{"name":"get_time","response":{...}}} 放入下一条 user 消息继续请求。

思考

JSON
{
  "contents": [{"role": "user", "parts": [{"text": "9.11 和 9.9 哪个大?"}]}],
  "generationConfig": {
    "thinkingConfig": {"thinkingBudget": 2048, "includeThoughts": true}
  }
}

thinkingBudget: 0 表示关闭思考(部分模型不允许关闭)。思考 Token 计入 thoughtsTokenCount,按输出 Token 计费。

非 Gemini 模型能否走此接口

可以,但平台会做格式转换,能力有损:文本、多模态输入、函数调用会被转换,流式同样按 Gemini 格式返回;safetySettings、cachedContent 等 Gemini 特有字段不保证生效。部分模型不支持此接口,调用会报错。需要完整 Gemini 语义时请使用 Gemini 模型;通用场景也可直接用 OpenAI 兼容-Chat。

路径变体

POST /v1/models/{model}:generateContent 与 /v1beta/... 等效,同样支持 x-goog-api-key / ?key= 鉴权。新接入建议统一用 /v1beta。

错误

本接口的错误体为 OpenAI 格式,而不是 Google 的 {"error": {"code", "status"}} 格式(详见 错误码)。使用 google-genai SDK 时请按 HTTP 状态码处理异常。

JSON
{"error": {"message": "...", "type": "...", "code": "..."}}
HTTP 场景
400 请求体不是合法 JSON,或 contents 为空
401 API Key 无效或已过期,请到控制台「API Keys」页检查
402 API Key 额度或账户余额不足
403 调用 IP 不在 API Key 的白名单内、API Key 无权访问该模型等
429 触发限流

通用错误见 错误码。

相关文档