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

# Gemini 原生格式调用指南

> 通过 API易 调用 Gemini 官方 generateContent 格式：google-genai SDK 配置、流式输出、thinking_level 思考控制、思维签名。

API易 完整支持 **Gemini 官方原生格式**（`/v1beta` generateContent 端点）：把 base\_url 指向 `https://api.apiyi.com`，现有 Gemini 代码和官方 SDK 即可无缝迁移，无需任何格式转换。

本页基于 Google 官方文档整理（`ai.google.dev/gemini-api/docs`，2026年6月数据），示例均可直接复制运行。

## 为什么用原生格式

OpenAI 兼容格式也能调 Gemini，但以下能力**只有原生格式有**：

* **完整思考控制**：`thinking_level`（Gemini 3 系列）/ `thinking_budget`（2.5 系列）、思考摘要、思维签名
* **原生多模态 Part**：图片 / 音频 / 视频直接内联传入，支持 `media_resolution` 控费 —— 见 [多模态与代码执行](/api-capabilities/gemini/multimodal)
* **代码执行工具**：`code_execution` 沙箱跑 Python
* **精细的用量字段**：`thoughts_token_count`、`cached_content_token_count` 等

简单文本对话、或要和其它厂商模型共用一套代码 → 用 [OpenAI 兼容模式调用](/api-capabilities/openai/compatible) 即可。

## 快速开始

推荐使用 Google 官方统一 SDK `google-genai`（旧版 `google-generative-ai` 已于 2025年11月30日 停止支持）：

```bash theme={null}
pip install google-genai
```

<CodeGroup>
  ```python Python theme={null}
  from google import genai

  client = genai.Client(
      api_key="YOUR_API_KEY",  # 你的 API易 密钥
      http_options={"base_url": "https://api.apiyi.com"}
  )

  response = client.models.generate_content(
      model="gemini-3.5-flash",
      contents="用一句话介绍你自己"
  )
  print(response.text)
  ```

  ```javascript Node.js theme={null}
  import { GoogleGenAI } from '@google/genai';

  const ai = new GoogleGenAI({
    apiKey: 'YOUR_API_KEY',
    httpOptions: { baseUrl: 'https://api.apiyi.com' }
  });

  const response = await ai.models.generateContent({
    model: 'gemini-3.5-flash',
    contents: '用一句话介绍你自己'
  });
  console.log(response.text);
  ```

  ```bash cURL theme={null}
  curl "https://api.apiyi.com/v1beta/models/gemini-3.5-flash:generateContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: YOUR_API_KEY" \
    -d '{
      "contents": [{
        "parts": [{"text": "用一句话介绍你自己"}]
      }]
    }'
  ```
</CodeGroup>

<Warning>
  注意 base\_url 是 `https://api.apiyi.com`（**不带** `/v1`），与 OpenAI 兼容格式的 `https://api.apiyi.com/v1` 不同。请使用 **API易 密钥**，不是 Google AI Studio 的密钥。
</Warning>

## 流式输出

```python theme={null}
stream = client.models.generate_content_stream(
    model="gemini-3.5-flash",
    contents="写一篇关于量子计算的短文"
)

for chunk in stream:
    print(chunk.text, end="", flush=True)
```

## 思考控制

Gemini 是思考型模型，**两代参数不一样，混用会直接报错**：

| 模型系列 | 参数 | 取值 |
| - | - | - |
| Gemini 3 / 3.1 / 3.5 | `thinking_level` | `minimal`（仅 Flash 系）/ `low` / `high`（默认） |
| Gemini 2.5 | `thinking_budget` | token 数上限（如 0–8192），不设则模型自动控制 |

<Warning>
  对 Gemini 3 系列模型**同时传 `thinking_level` 和 `thinking_budget` 会返回错误**，只能二选一（Gemini 3 系列请用 `thinking_level`）。
</Warning>

```python theme={null}
from google.genai import types

# Gemini 3 系列：按档位控制
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="证明根号2是无理数",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="high")
    )
)

# Gemini 2.5 系列：按 token 预算控制
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="简单问题，要快",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_budget=0)  # 关闭思考
    )
)
```

档位选型：`minimal` 适合低延迟简单任务（分类、抽取）；`low` 适合常规对话；`high` 适合复杂推理和代码 —— 思考 token 按**输出价**计费，档位越高账单越贵。

### 思考摘要与思维签名

* **思考摘要**：`include_thoughts=True` 可在响应中返回思考过程摘要（`part.thought` 为 `True` 的 part）
* **思维签名（thought signatures）**：Gemini 3 引入的加密推理状态。多轮对话（尤其函数调用）时要把响应里的 `thought_signature` 原样回传，模型才能延续推理链。**官方 SDK 自动处理**，手写 REST 请求时注意不要丢弃该字段 —— 详见 [FC函数调用](/api-capabilities/gemini/function-calling)

```python theme={null}
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="分析这段代码的时间复杂度：def fib(n): return n if n <= 1 else fib(n-1) + fib(n-2)",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="high", include_thoughts=True)
    )
)

for part in response.candidates[0].content.parts:
    if getattr(part, "thought", False):
        print(f"[思考摘要] {part.text}")
    else:
        print(f"[最终答案] {part.text}")
```

## 常用配置参数

通过 `config`（`GenerateContentConfig`）传入：

| 参数 | 说明 |
| - | - |
| `system_instruction` | 系统指令 |
| `temperature` | 0–2。**Gemini 3 系列官方建议保持默认 1.0**，调低反而可能损伤推理质量 |
| `max_output_tokens` | 最大输出（含思考 token） |
| `thinking_config` | 思考控制，见上文 |
| `response_mime_type` | 设为 `application/json` 强制 JSON 输出 |
| `response_schema` | 配合 JSON 输出的结构约束（结构化输出） |
| `tools` | 函数声明 / `code_execution` 等工具 |
| `media_resolution` | 多模态输入分辨率控费，见 [多模态页](/api-capabilities/gemini/multimodal) |

## 用量字段（usage\_metadata）

```python theme={null}
usage = response.usage_metadata
print(f"输入: {usage.prompt_token_count}")
print(f"输出: {usage.candidates_token_count}")
print(f"思考: {usage.thoughts_token_count}")
print(f"缓存命中: {usage.cached_content_token_count}")
```

| 字段 | 说明 | 计费 |
| - | - | - |
| `prompt_token_count` | 输入 tokens | 按输入价 |
| `candidates_token_count` | 输出 tokens | 按输出价 |
| `thoughts_token_count` | 思考 tokens | **按输出价**，控档位可省 |
| `cached_content_token_count` | 缓存命中 tokens | 按官方折扣，见 [缓存计费](/api-capabilities/gemini/prompt-caching) |
| `total_token_count` | 总量 | — |

## 支持的模型与价格

| 模型 | 输入（每 1M tokens） | 输出（每 1M tokens） | 说明 |
| - | - | - | - |
| `gemini-3.5-flash` | \$1.50 | \$9.00 | 当前主力，多项指标反超 3.1 Pro，1M 上下文 |
| `gemini-3.1-pro-preview` | \$1.80 | \$10.80 | Pro 旗舰 |
| `gemini-3-pro-preview` | \$1.80 | \$10.80 | 上代 Pro |
| `gemini-3-flash-preview` | \$0.44 | \$2.64 | 轻量快速 |
| `gemini-3.1-flash-lite` | \$0.25 | \$1.50 | 超低价 |
| `gemini-2.5-pro` | \$1.25 | \$10.00 | 2.5 系 Pro |
| `gemini-2.5-flash` | \$0.30 | \$2.40 | 2.5 系主力 |
| `gemini-2.5-flash-lite` | \$0.10 | \$0.40 | 最便宜 |

<Tip>
  部分模型提供 `-thinking` / `-nothinking` 后缀别名（如 `gemini-3-flash-preview-nothinking`），固定开启/关闭思考，适合不方便改请求参数的客户端。完整列表见 [模型与价格总览](/api-capabilities/model-info)。
</Tip>

## 与 OpenAI 兼容格式对比

| 特性 | Gemini 原生格式 | OpenAI 兼容格式 |
| - | - | - |
| base\_url | `https://api.apiyi.com` | `https://api.apiyi.com/v1` |
| SDK | `google-genai` | `openai` |
| 思考控制 | `thinking_level` / `thinking_budget` | `reasoning_effort` |
| 思考摘要 / 思维签名 | ✅ | ❌ |
| 代码执行工具 | ✅ | ❌ |
| 媒体输入 | 原生 Part 内联（PIL / bytes） | Base64 image\_url |
| 缓存命中字段 | `cached_content_token_count` | `cached_tokens` |

## 注意事项

* **不支持 Files API**（`client.files.upload()`），媒体一律内联传入且**单文件不超过 20MB** —— 详见 [多模态与代码执行](/api-capabilities/gemini/multimodal)
* 媒体、长上下文的缓存折扣与命中率说明见 [缓存计费](/api-capabilities/gemini/prompt-caching)

## 相关链接

* 同组页面：[多模态与代码执行](/api-capabilities/gemini/multimodal) · [缓存计费](/api-capabilities/gemini/prompt-caching) · [FC函数调用](/api-capabilities/gemini/function-calling)
* 获取 / 管理令牌：`https://api.apiyi.com/token`
* Google 官方文档：`ai.google.dev/gemini-api/docs`


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