Gemini 原生格式

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

http

POST /v1beta/models/{model}:{action}

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

默认示例模型为。

当前可用模型

模型	说明
	Gemini 3.6 Flash 最新
	Gemini 3.1 Pro 预览版
	Gemini 3.1 Flash Lite 预览
	Gemini 3 Flash 预览版
	Gemini 2.5 Pro
	Gemini 2.5 Flash
	Gemini 2.5 Flash Lite

路径

Method	Path	说明
`GET`		Gemini 模型列表
`POST`		非流式内容生成
`POST`		流式内容生成

将替换为具体模型 ID（可选值见上方「当前可用模型」），将替换为或。

本页调试台默认调用非流式。

请求头

类型	必填	说明
string	是	请求身份认证。使用 Bearer Token，示例：。也可改用或查询参数
string	否	Google API Key 风格认证，示例：；与二选一
string	是	请求内容类型，必须设置为

查询参数也可用于认证，例如：/v1beta/models/gemini-3.6-flash:generateContent?key=YOUR_API_KEY。

请求体

类型	必填	说明
array	是	对话内容列表。多轮对话时在与之间交替
object	否	系统级指令（System Prompt）；兼容与
object	否	生成配置，控制模型输出行为
array	否	安全策略配置
array	否	Gemini 工具声明列表
object	否	工具调用配置
string	否	Cached Content 标识，用于复用上下文缓存
object	否	自定义键值对标签，用于请求追踪与计费归因

contents 内容项

名称	类型	必填	说明
	string	否	内容角色：或
	array	是	内容片段。支持、（ + Base64 ）、（ + ）、、等

parts.videoMetadata

视频输入元数据。仅用于同一个中的视频或，用于控制模型读取视频的时间范围和抽帧频率。多个视频时可各自设置。

类型	必填	说明
string	否	视频起始偏移，Duration 字符串，例如、
string	否	视频结束偏移，例如
number	否	抽帧帧率，默认，有效范围 < fps ≤

generationConfig

类型	必填	说明
number	否	输出随机性，范围 –，默认
number	否	核采样概率阈值
integer	否	仅从概率最高的 K 个 Token 中采样
integer	否	返回候选结果数量，默认
integer	否	最大输出 Token 数量
array	否	命中指定字符串后停止生成，最多 5 个
string	否	输出格式：（默认）/ /
object	否	结构化输出 Schema（OpenAPI 3.0 子集）；需配合
object	否	标准 JSON Schema 约束；与二选一
array	否	输出模态，例如；图像生成可用
integer	否	固定随机种子，便于结果复现
number	否	降低重复主题，鼓励新内容
number	否	降低重复词语或句子
boolean	否	是否返回 Token 概率信息
integer	否	返回的 Token 概率数量，范围 –
boolean	否	是否为选举、政务等公共事务类问题启用增强回答
object	否	语音输出配置（TTS），可含、等
boolean	否	是否返回音频时间戳，仅用于音频理解场景
object	否	Thinking 模型推理配置
string	否	媒体分辨率： / /
object	否	图像生成配置；常用（如、）、（ / / ）

thinkingConfig

类型	必填	说明
boolean	否	是否在响应中返回思考摘要
integer	否	思考 Token 预算（Gemini 2.5 系列）；动态思考，关闭
string	否	思考强度： / （Gemini 3 系列，与二选一）

safetySettings 项

类型	必填	说明
string	是	风险类别，见下方「常见安全设置」
string	是	风险拦截等级，见下方「常见安全设置」
string	否	判定方式：（按严重程度）或（按概率）

tools

支持以下工具类型：

类型	说明
	Function Calling 函数声明
	Google 搜索能力
	代码执行能力
	URL 内容解析能力
	检索增强（RAG），已废弃，仅旧模型可用
	Google 检索增强；新模型请改用

toolConfig

常用于配置：

值	说明
	模型自动决定是否调用工具
	强制调用工具
	禁止调用工具

可选：指定允许调用的函数列表。

请求示例

文本生成

bash

curl -X POST https://octopusx.ai/v1beta/models/gemini-3.6-flash:generateContent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "用三句话介绍 Gemini 原生接口。" }
        ]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 300
    }
  }'

也可使用：

bash

curl -X POST https://octopusx.ai/v1beta/models/gemini-3.6-flash:generateContent \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "用三句话介绍 Gemini 原生接口。" }
        ]
      }
    ]
  }'

多模态输入

bash

curl -X POST https://octopusx.ai/v1beta/models/gemini-3.6-flash:generateContent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "<BASE64_IMAGE>"
            }
          },
          {
            "text": "请描述这张图片的主要内容。"
          }
        ]
      }
    ]
  }'

视频输入（videoMetadata）

bash

curl -X POST https://octopusx.ai/v1beta/models/gemini-3.6-flash:generateContent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "fileData": {
              "mimeType": "video/mp4",
              "fileUri": "https://example.com/demo.mp4"
            },
            "videoMetadata": {
              "startOffset": "3s",
              "endOffset": "10s",
              "fps": 1.0
            }
          },
          {
            "text": "总结该片段中的关键动作。"
          }
        ]
      }
    ]
  }'

流式生成

bash

curl -X POST https://octopusx.ai/v1beta/models/gemini-3.6-flash:streamGenerateContent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "用三句话介绍 Gemini 原生接口。" }
        ]
      }
    ]
  }'

响应示例

200 - 非流式

json

{
  "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
  }
}

响应字段

名称	类型	说明
	array	候选结果列表
	object	含（通常为）与
	string	结束原因，例如
	array	安全评级列表
	object	Token 用量；含、、

常见安全设置

值	说明
	骚扰内容
	仇恨言论
	色情内容
	危险内容

threshold

值	说明
	不屏蔽
	仅屏蔽高风险
	屏蔽中等及以上风险
	屏蔽低等及以上风险

OpenAI 格式

官方格式

OpenAI 格式

官方格式

OpenAI 格式

OpenAI 格式

OpenAI 格式

OpenAI 格式

Gemini 原生格式

当前可用模型

路径

请求头

请求体

contents 内容项

parts.videoMetadata

generationConfig

thinkingConfig

safetySettings 项

tools

toolConfig

请求示例

文本生成

多模态输入

视频输入（videoMetadata）

流式生成

响应示例

200 - 非流式

响应字段

常见安全设置

category

threshold

相关接口

Gemini 原生格式 ​

当前可用模型 ​

路径 ​

请求头 ​

请求体 ​

contents 内容项 ​

parts.videoMetadata ​

generationConfig ​

thinkingConfig ​

safetySettings 项 ​

tools ​

toolConfig ​

请求示例 ​

文本生成 ​

多模态输入 ​

视频输入（videoMetadata） ​

流式生成 ​

响应示例 ​

200 - 非流式 ​

响应字段 ​

常见安全设置 ​

category ​

threshold ​

相关接口 ​

Gemini 原生格式

当前可用模型

路径

请求头

请求体

contents 内容项

parts.videoMetadata

generationConfig

thinkingConfig

safetySettings 项

tools

toolConfig

请求示例

文本生成

多模态输入

视频输入（videoMetadata）

流式生成

响应示例

200 - 非流式

响应字段

常见安全设置

category

threshold

相关接口