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

# Gemini 原生接口

> Google Gemini generateContent API 兼容格式

使用 Gemini 原生 `generateContent` API 调用 Gemini 模型，适用于 Gemini SDK、多模态输入与原生工具调用场景。

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://gogogotoken.ai/v1beta/models/gemini-2.5-pro:generateContent" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "contents": [{
        "role": "user",
        "parts": [{ "text": "Explain quantum entanglement simply." }]
      }]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "candidates": [
      {
        "content": {
          "role": "model",
          "parts": [
            { "text": "Quantum entanglement is a link between particles..." }
          ]
        },
        "finishReason": "STOP"
      }
    ],
    "usageMetadata": {
      "promptTokenCount": 8,
      "candidatesTokenCount": 34,
      "totalTokenCount": 42
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "message": "Invalid API key",
      "code": "invalid_api_key"
    }
  }
  ```
</ResponseExample>

## 接口说明

该接口保留 Gemini 原生请求结构。若你已经使用 Gemini 官方 SDK，通常只需要把 Base URL 指向 `https://gogogotoken.ai` 并使用 gogogotoken 的 API Key。

## 端点

| 模式  | 端点                                                                             |
| --- | ------------------------------------------------------------------------------ |
| 非流式 | `POST /v1beta/models/{model}:generateContent`                                  |
| 流式  | [`POST /v1beta/models/{model}:streamGenerateContent`](/overseas/gemini-stream) |

## 路径参数

<ParamField path="model" type="string" required default="gemini-2.5-pro">
  Gemini 模型 ID，例如 `gemini-2.5-pro`、`gemini-2.0-flash`。完整列表以 `GET /v1/models` 返回结果为准。
</ParamField>

## 请求头

<ParamField header="Authorization" type="string" required>
  API Key 鉴权信息，格式为 `Bearer YOUR_API_KEY`。
</ParamField>

<ParamField header="Content-Type" type="string" required>
  固定为 `application/json`。
</ParamField>

## 请求体

<ParamField body="contents" type="object[]" required default={[{ role: "user", parts: [{ text: "Explain quantum entanglement simply." }] }]}>
  对话内容数组。

  <ParamField body="role" type="string">
    消息角色，常用值为 `user` 或 `model`。
  </ParamField>

  <ParamField body="parts" type="object[]" required>
    内容片段数组，可包含文本、图片、文件或工具相关内容。
  </ParamField>
</ParamField>

<ParamField body="generationConfig" type="object">
  生成配置，例如 `temperature`、`maxOutputTokens`、`responseModalities`。
</ParamField>

<ParamField body="tools" type="object[]">
  Gemini 原生工具定义。
</ParamField>

<ParamField body="systemInstruction" type="object">
  系统指令，用于约束模型行为。
</ParamField>

## 响应体

<ResponseField name="candidates" type="object[]">
  模型候选输出数组。文本通常位于 `candidates[0].content.parts[0].text`。
</ResponseField>

<ResponseField name="finishReason" type="string">
  生成结束原因，例如 `STOP`、`MAX_TOKENS`。
</ResponseField>

<ResponseField name="usageMetadata" type="object">
  token 用量统计，通常包含输入、输出与总 token 数。
</ResponseField>

## 与 OpenAI 兼容格式的对比

| 方式        | 端点                                       | 适用场景                      |
| --------- | ---------------------------------------- | ------------------------- |
| OpenAI 兼容 | `/v1/chat/completions`                   | 已有 OpenAI SDK、统一多厂商代码     |
| Gemini 原生 | `/v1beta/models/{model}:generateContent` | Google 官方 SDK、Gemini 特有参数 |