Gemini 原生接口

请求地址

POST https://api.viviai.cc/v1beta/models/YOUR_GEMINI_MODEL:generateContent

模型 ID 放在 URL 中。将 YOUR_GEMINI_MODEL 替换为账号可用的完整模型 ID，不要重复添加 models/。

鉴权

x-goog-api-key: YOUR_API_KEY
Content-Type: application/json

这里使用 ViVi-API 密钥。设置环境变量 VIVI_API_KEY 的方法见快速开始。

请求参数

参数	类型	必填	说明
`contents`	array	是	当前输入与必要的历史消息。
`contents[].role`	string	否	`user` 表示用户，`model` 表示模型回复。
`contents[].parts`	array	是	消息内容块，文本使用 `{"text":"内容"}`。
`systemInstruction`	object	否	顶层系统指令，使用 `parts` 结构。
`generationConfig`	object	否	生成配置。
`generationConfig.maxOutputTokens`	integer	否	最大输出 token 数。
`generationConfig.temperature`	number	否	采样参数，范围及支持情况依模型而定。
`generationConfig.topP`	number	否	核采样参数。

Gemini 原生接口使用 contents 和 parts，助手角色是 model。不要直接发送 OpenAI 的 messages 请求体。

调用示例

cURL 使用 Bash 语法。Python 示例需安装 requests：python -m pip install requests。

curl --fail-with-body \
  "https://api.viviai.cc/v1beta/models/YOUR_GEMINI_MODEL:generateContent" \
  -H "x-goog-api-key: $VIVI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "请用三句话介绍 API。"}]}
    ]
  }'

import os
import requests

model = "YOUR_GEMINI_MODEL"
response = requests.post(
    f"https://api.viviai.cc/v1beta/models/{model}:generateContent",
    headers={"x-goog-api-key": os.environ["VIVI_API_KEY"]},
    json={
        "contents": [
            {"role": "user", "parts": [{"text": "请用三句话介绍 API。"}]}
        ]
    },
    timeout=120,
)
response.raise_for_status()
data = response.json()
candidates = data.get("candidates", [])
if not candidates:
    raise RuntimeError(f"未返回候选结果：{data.get('promptFeedback', data)}")
parts = candidates[0].get("content", {}).get("parts", [])
print("".join(p.get("text", "") for p in parts if not p.get("thought")))

返回结果

以下为结构示意。响应可能包含多个 parts，不要只读取第一个内容块。

{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [{"text": "API 是应用之间通信的接口。"}]
    },
    "finishReason": "STOP"
  }],
  "usageMetadata": {
    "promptTokenCount": 20,
    "candidatesTokenCount": 15,
    "totalTokenCount": 35
  }
}

输出文本：candidates[].content.parts[].text。
结束原因：candidates[].finishReason，例如 STOP、MAX_TOKENS。
用量：usageMetadata，字段可能随模型变化。
无候选结果时，检查 promptFeedback；候选被拦截时也要检查 finishReason。

系统指令与多轮对话

{
  "systemInstruction": {
    "parts": [{"text": "你是一名耐心的编程助手，请使用中文回答。"}]
  },
  "contents": [
    {"role": "user", "parts": [{"text": "我正在学习 Python。"}]},
    {"role": "model", "parts": [{"text": "你想先学习哪部分？"}]},
    {"role": "user", "parts": [{"text": "请介绍列表。"}]}
  ],
  "generationConfig": {"maxOutputTokens": 1024}
}

普通文本对话按顺序带上历史即可。涉及工具调用、思考签名或多模态时，应保留模型要求的完整内容块，避免只保存显示出来的文本。

流式输出

将方法改为 streamGenerateContent，并添加 alt=sse：

curl --no-buffer --fail-with-body \
  "https://api.viviai.cc/v1beta/models/YOUR_GEMINI_MODEL:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $VIVI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "写一段简短的欢迎语。"}]}
    ]
  }'

按 SSE 事件读取 data: 中的 JSON，从每个事件的 candidates[].content.parts 提取文本。Gemini 不使用 OpenAI 的 choices[].delta 结构，也不应依赖 [DONE] 作为结束标记。

接入提示

路径是 /v1beta/models/...，不要拼接成 /v1/v1beta/...。
模型名在 URL 中，生成参数位于 JSON 请求体内。
图片、文件、工具调用等能力依模型和接入渠道而定；本文先覆盖文本调用。
遇到错误时，检查 HTTP 状态码与返回的 error 内容，再对照错误排查。

协议参考：Google Gemini generateContent。ViVi-API 的模型范围与可选功能以实际服务为准。

开始使用

API 参考

请求地址

鉴权

请求参数

调用示例

返回结果

系统指令与多轮对话

流式输出

接入提示

​请求地址

​鉴权

​请求参数

​调用示例

​返回结果

​系统指令与多轮对话

​流式输出

​接入提示

请求地址

鉴权

请求参数

调用示例

返回结果

系统指令与多轮对话

流式输出

接入提示