Gemini SDK使用指南

基础 API

Gemini 原生格式调用

通过问问API 直接使用 Gemini 官方原生格式进行 API 调用。

问问API 除了支持 OpenAI 兼容格式外，也提供了直接使用 Gemini 官方原生格式进行 API 调用的能力。这意味着您可以无缝迁移现有的 Gemini 代码，或直接使用 Gemini 官方 SDK 的原生请求体与问问API 交互。

优势

无缝兼容：直接使用 Gemini 官方请求和响应结构，无需任何转换。

功能完整：支持 Gemini 的所有原生特性，包括多模态输入（文本、图片、视频）、Function Calling、代码执行等。

推理能力：完整支持 Gemini 2.5 系列的思维链推理功能。

便捷迁移：对于已有 Gemini 项目的用户，可以快速切换到问问API，享受更灵活的服务。

配置与使用

要使用 Gemini 原生格式，您需要将 API 请求发送到特定的 /v1beta/ 端点。

环境准备

我们推荐使用 Google 官方的最新 google-genai Python SDK（统一的 Gen AI SDK）。旧版 google-generative-ai 已于 2025 年 11 月 30 日停止支持。

首先，确保您已安装 google-genai 库：

基础配置

配置问问API 服务端点：

基础文本生成

非流式响应

Gemini 2.5 系列推理功能

Gemini 2.5 系列模型支持强大的思维链推理能力，可以显示模型的思考过程。

推理模型类型

gemini-2.5-flash：混合推理型，可通过 thinking_budget 参数调整推理深度（范围：0-16384 tokens）

gemini-2.5-pro：纯推理型，自动启用思维链推理，无法关闭

控制推理预算

显示思考过程

如果您想看到模型的思考过程（thinking tokens），可以设置 include_thoughts=True：

多模态处理

Gemini 模型支持处理图片、音频、视频等多种媒体类型。

图片处理

视频处理

音频处理

媒体分辨率优化

为了节省 tokens 费用，您可以调整媒体文件的分辨率：

代码执行功能

Gemini 模型支持自动执行 Python 代码，非常适合数据分析场景。

Function Calling（工具调用）

Gemini 原生格式完整支持 Function Calling，让模型可以调用外部工具。

定义工具

上下文缓存

问问API 自动为 Gemini 原生格式启用隐式上下文缓存，可以显著降低重复对话的费用。

缓存机制

自动启用：无需手动配置，系统自动缓存上下文

缓存费用：缓存的 tokens 按正常价格的 25% 计费

有效期：缓存会在一定时间后自动过期

检测缓存命中

Tokens 用量追踪

每次 API 调用都会返回详细的 tokens 用量信息。

获取用量统计

注意事项

API 密钥

请确保使用您的问问API 密钥，而非 Google AI Studio 的密钥。

端点配置

Gemini 原生格式使用 https://api.wenwen-ai.com 作为 base_url，兼容 Google 官方 REST API 格式。

模型名称

直接使用 Gemini 官方模型名称，如 gemini-3-pro-preview、gemini-2.5-flash。

多模态支持

完全支持 Gemini 官方的多模态数据格式，可直接传递图片、视频、音频。

重要限制：

媒体文件大小不能超过 20MB

代码执行仅支持 Python，且在沙箱环境中运行

推理 tokens 会增加输出成本，请合理设置 thinking_budget

与 OpenAI 兼容格式的对比

特性	Gemini 原生格式	OpenAI 兼容格式
端点	https://api.wenwen-ai.com	https://api.wenwen-ai.com/v1/chat/completions
SDK	google-genai	openai
推理控制	thinking_budget (0-16384)	reasoning_effort (low/medium/high)
思考过程	include_thoughts=True	不支持
代码执行	tools=[{'code_execution': {}}]	不支持
媒体上传	client.files.upload()	Base64 编码
缓存检测	cached_content_token_count	无详细字段

如果您需要调用其他类型的模型（如 OpenAI 系列）或使用 OpenAI 兼容格式，请参考 OpenAI 官方库使用文档。

完整示例

以下是一个综合示例，展示了多种功能的组合使用：

官方文档入口：https://ai.google.dev/gemini-api/docs?hl=zh-cn

Gemini SDK使用指南

基础 API#

Gemini 原生格式调用#

优势#

配置与使用#

环境准备#

基础配置#

基础文本生成#

非流式响应#

Gemini 2.5 系列推理功能#

推理模型类型#

控制推理预算#

显示思考过程#

多模态处理#

图片处理#

视频处理#

音频处理#

媒体分辨率优化#

代码执行功能#

Function Calling（工具调用）#

定义工具#

上下文缓存#

缓存机制#

检测缓存命中#

Tokens 用量追踪#

获取用量统计#

注意事项#

API 密钥#

端点配置#

模型名称#

多模态支持#

重要限制：#

与 OpenAI 兼容格式的对比#

完整示例#