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
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": "用三句话解释量子纠缠。"}]}
]
}'
流式:
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)
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 官方语义转发给模型服务商,是否生效取决于具体模型。
响应
非流式
{
"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 片段:
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为准。
进阶用法
多模态输入
{
"contents": [{
"role": "user",
"parts": [
{"inlineData": {"mimeType": "image/jpeg", "data": "<base64>"}},
{"text": "这张图里有什么?"}
]
}]
}
函数调用
{
"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 消息继续请求。
思考
{
"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 状态码处理异常。
{"error": {"message": "...", "type": "...", "code": "..."}}
| HTTP | 场景 |
|---|---|
| 400 | 请求体不是合法 JSON,或 contents 为空 |
| 401 | API Key 无效或已过期,请到控制台「API Keys」页检查 |
| 402 | API Key 额度或账户余额不足 |
| 403 | 调用 IP 不在 API Key 的白名单内、API Key 无权访问该模型等 |
| 429 | 触发限流 |
通用错误见 错误码。
相关文档
- Gemini 图像
- OpenAI 兼容-Chat:Gemini 模型同样可以用 OpenAI 格式调用
- 模型列表 · Base URL 总览