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

# Gemini 原生格式

> 使用 Google Gemini 原生路径与请求体调用 generateContent、streamGenerateContent 与模型查询。

# Gemini 原生格式

Gemini 原生格式保留 Google Gemini API 的路径和请求体。适合已有 Gemini SDK、`contents`/`parts` 结构或安全设置配置的业务接入。

## 认证

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

也支持 Google API Key 风格：

```http theme={null}
x-goog-api-key: YOUR_API_KEY
```

或查询参数：

```text theme={null}
/v1beta/models/gemini-2.0-flash:generateContent?key=YOUR_API_KEY
```

## 路径

| Method | Path                                           | 说明          |
| ------ | ---------------------------------------------- | ----------- |
| `GET`  | `/v1beta/models`                               | Gemini 模型列表 |
| `POST` | `/v1beta/models/{model}:generateContent`       | 非流式内容生成     |
| `POST` | `/v1beta/models/{model}:streamGenerateContent` | 流式内容生成      |

## 请求体

<ParamField body="contents" type="array<object>" required>
  对话内容列表。每个内容项包含 `role` 和 `parts`。
</ParamField>

<ParamField body="contents[].parts" type="array<object>" required>
  内容片段。支持 `text`、`inlineData`、`fileData`、`functionCall`、`functionResponse` 等。
</ParamField>

<ParamField body="contents[].parts[].videoMetadata" type="object">
  视频输入元数据。仅用于同一个 `part` 中的视频 `inlineData` 或 `fileData`，用于控制模型读取视频的时间范围和抽帧频率。

  支持的字段：

  * `startOffset`：视频起始偏移，Duration 字符串格式，例如 `"3s"`、`"3.5s"`。
  * `endOffset`：视频结束偏移，Duration 字符串格式，例如 `"10s"`。
  * `fps`：视频抽帧帧率，默认 `1.0`，有效范围为 `0 < fps <= 24`。

  当请求中包含多个视频时，每个视频 `part` 可以分别设置自己的 `videoMetadata`。
</ParamField>

<ParamField body="systemInstruction" type="object">
  系统级指令（System Prompt）。用于定义模型行为、角色设定、回复风格等。兼容 `systemInstruction` 和 `system_instruction` 两种写法。
</ParamField>

<ParamField body="generationConfig" type="object">
  生成配置，用于控制模型输出行为。支持以下字段：

  * `temperature`：控制输出随机性，值越高结果越发散。
  * `topP`：Nucleus Sampling（核采样）概率阈值。
  * `topK`：仅从概率最高的 K 个 Token 中采样。
  * `candidateCount`：返回候选结果数量。
  * `maxOutputTokens`：最大输出 Token 数量。
  * `stopSequences`：命中指定字符串后停止生成。
  * `responseMimeType`：指定输出格式，例如 `text/plain`、`application/json`。
  * `responseSchema`：JSON Schema 结构化输出约束。
  * `presencePenalty`：降低重复主题，鼓励新内容生成。
  * `frequencyPenalty`：降低重复词语或句子。
  * `seed`：固定随机种子，便于结果复现。
  * `responseLogprobs`：是否返回 Token 概率信息。
  * `logprobs`：返回的 Token 概率数量。
  * `audioTimestamp`：是否返回音频时间戳。
  * `speechConfig`：语音输出配置（TTS）。
  * `thinkingConfig`：Gemini Thinking 模型推理配置。
</ParamField>

<ParamField body="safetySettings" type="array<object>">
  安全策略配置。每项包含 `category`（风险类别）和 `threshold`（风险拦截等级）。

  支持的风险类别：`HARM_CATEGORY_HATE_SPEECH`、`HARM_CATEGORY_HARASSMENT`、`HARM_CATEGORY_SEXUALLY_EXPLICIT`、`HARM_CATEGORY_DANGEROUS_CONTENT`。
</ParamField>

<ParamField body="tools" type="array<object>">
  Gemini 工具声明列表，用于启用函数调用、搜索、代码执行等能力。支持以下工具类型：

  * `functionDeclarations`：Function Calling 函数声明。
  * `googleSearch`：Google 搜索能力。
  * `codeExecution`：代码执行能力。
  * `urlContext`：URL 内容解析能力。
  * `retrieval`：检索增强生成（RAG）。
  * `googleSearchRetrieval`：Google 检索增强。
</ParamField>

<ParamField body="toolConfig" type="object">
  工具调用配置。

  常用于配置 `functionCallingConfig.mode`：`AUTO`（模型自动决定是否调用工具）、`ANY`（强制调用工具）、`NONE`（禁止调用工具）。

  `allowedFunctionNames`：指定允许调用的函数列表。
</ParamField>

<ParamField body="cachedContent" type="string">
  Gemini Cached Content 标识。用于复用上下文缓存，降低长上下文请求的 Token 消耗与响应延迟。
</ParamField>

## 请求示例

<RequestExample>
  ```bash theme={null}
  curl -X POST https://octopusx.ai/v1beta/models/gemini-2.0-flash:generateContent \
    -H "x-goog-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "contents": [
        {
          "role": "user",
          "parts": [
            { "text": "用三句话介绍 Gemini 原生接口。" }
          ]
        }
      ],
      "generationConfig": {
        "temperature": 0.7,
        "maxOutputTokens": 300
      }
    }'
  ```
</RequestExample>

### 多模态输入

```bash theme={null}
curl -X POST https://octopusx.ai/v1beta/models/gemini-2.0-flash:generateContent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "识别这张图片里的核心信息。" },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "BASE64_IMAGE_DATA"
            }
          }
        ]
      }
    ]
  }'
```

### 视频输入（带 videoMetadata）

`videoMetadata` 与视频数据放在同一个 `part` 中，可用于只分析视频片段或调整抽帧密度。

```bash theme={null}
curl -X POST https://octopusx.ai/v1beta/models/gemini-2.0-flash:generateContent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "总结这段视频 3 到 12 秒之间发生了什么。" },
          {
            "fileData": {
              "mimeType": "video/mp4",
              "fileUri": "https://example.com/demo-video.mp4"
            },
            "videoMetadata": {
              "startOffset": "3s",
              "endOffset": "12s",
              "fps": 2
            }
          }
        ]
      }
    ]
  }'
```

### 流式生成

```bash theme={null}
curl -N -X POST https://octopusx.ai/v1beta/models/gemini-2.0-flash:streamGenerateContent \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "写一个 5 行以内的发布公告。" }
        ]
      }
    ]
  }'
```

## 响应示例

<ResponseExample>
  ```json 200 theme={null}
  {
    "candidates": [
      {
        "content": {
          "role": "model",
          "parts": [
            {
              "text": "Gemini 原生接口使用 contents 和 parts 表达输入内容。它支持文本、图片、文件和函数调用等能力。通过统一网关可以继续使用相同 API Key 与计费体系。"
            }
          ]
        },
        "finishReason": "STOP",
        "safetyRatings": [
          {
            "category": "HARM_CATEGORY_HARASSMENT",
            "probability": "NEGLIGIBLE"
          }
        ]
      }
    ],
    "usageMetadata": {
      "promptTokenCount": 18,
      "candidatesTokenCount": 58,
      "totalTokenCount": 76
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "message": "field contents is required",
      "type": "invalid_request_error",
      "param": "",
      "code": "invalid_request"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "message": "Invalid API key provided",
      "type": "invalid_request_error",
      "param": "",
      "code": "invalid_api_key"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "message": "用户额度不足",
      "type": "new_api_error",
      "param": "",
      "code": "insufficient_user_quota"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "message": "当前请求频率过高，请稍后再试",
      "type": "new_api_error",
      "param": "",
      "code": "too_many_requests"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "message": "bad response body",
      "type": "new_api_error",
      "param": "",
      "code": "bad_response_body"
    }
  }
  ```
</ResponseExample>

## 常见安全设置

| category                          | 说明   |
| --------------------------------- | ---- |
| `HARM_CATEGORY_HARASSMENT`        | 骚扰内容 |
| `HARM_CATEGORY_HATE_SPEECH`       | 仇恨言论 |
| `HARM_CATEGORY_SEXUALLY_EXPLICIT` | 色情内容 |
| `HARM_CATEGORY_DANGEROUS_CONTENT` | 危险内容 |

| threshold                | 说明        |
| ------------------------ | --------- |
| `BLOCK_NONE`             | 不屏蔽       |
| `BLOCK_ONLY_HIGH`        | 仅屏蔽高风险    |
| `BLOCK_MEDIUM_AND_ABOVE` | 屏蔽中等及以上风险 |
| `BLOCK_LOW_AND_ABOVE`    | 屏蔽低等及以上风险 |

## 相关接口

* [通用对话接口（默认非流式）](./chat-completions-non-stream)
* [模型列表](./models)