> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viviai.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Gemini 原生接口

> 使用 generateContent 与 streamGenerateContent，按 Gemini 原生格式发送消息。

## 请求地址

```http theme={null}
POST https://api.viviai.cc/v1beta/models/YOUR_GEMINI_MODEL:generateContent
```

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

## 鉴权

```http theme={null}
x-goog-api-key: YOUR_API_KEY
Content-Type: application/json
```

这里使用 ViVi-API 密钥。设置环境变量 `VIVI_API_KEY` 的方法见[快速开始](https://docs.viviai.cc/quickstart.md)。

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `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 | 否 | 核采样参数。 |

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

## 调用示例

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

```bash cURL theme={null}
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。"}]}
    ]
  }'
```

```python Python theme={null}
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`，不要只读取第一个内容块。

```json theme={null}
{
  "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`。

## 系统指令与多轮对话

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

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

## 流式输出

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

```bash theme={null}
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` 内容，再对照[错误排查](https://docs.viviai.cc/quickstart.md#常见问题)。

协议参考：[Google Gemini generateContent](https://ai.google.dev/api/generate-content)。ViVi-API 的模型范围与可选功能以实际服务为准。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.