Gemini 原生（文本）

简介

Gemini 原生 API 采用 Google Gemini 的请求与响应格式，适用于 Google 官方客户端（如 google-generativeai SDK）或需要直接使用 Gemini 数据结构的场景。若使用 OpenAI 兼容客户端（如 OpenAI SDK），请使用 /v1/chat/completions 接口。

与 OpenAI 格式的区别

特性	Gemini 原生	OpenAI 兼容
消息结构	`contents[].parts[]`	`messages[].content`
角色名称	`user` / `model`	`user` / `assistant`
流式参数	URL 参数 `?alt=sse`	Body 参数 `stream: true`
系统提示	`systemInstruction`	`messages[0].role: "system"`
多模态	`parts[]` 数组混合	`content[]` 数组混合

API 端点

功能	方法	路径
文本生成（非流式）	POST	`/v1beta/models/{model}:generateContent`
文本生成（流式）	POST	`/v1beta/models/{model}:streamGenerateContent?alt=sse`
单条 Embedding	POST	`/v1beta/models/{model}:embedContent`
批量 Embedding	POST	`/v1beta/models/{model}:batchEmbedContents`

认证

支持两种认证方式：

方式	Header	示例
Bearer Token（推荐）	`Authorization`	`Bearer sk-xxxxxxxxxx`
Google 风格	`x-goog-api-key`	`sk-xxxxxxxxxx`

请求参数

参数	类型	必需	描述
`contents`	array	是	对话内容数组
`generationConfig`	object	否	生成配置参数
`safetySettings`	array	否	安全过滤设置
`systemInstruction`	object	否	系统指令
`tools`	array	否	工具定义（函数调用、搜索等）
`cachedContent`	string	否	缓存内容名称

generationConfig 参数

参数	类型	描述
`temperature`	number	随机性（0-2）
`topP`	number	核采样（0-1）
`topK`	integer	Top-K 采样
`maxOutputTokens`	integer	最大输出 token 数
`stopSequences`	array	停止序列
`candidateCount`	integer	候选响应数量
`thinkingConfig`	object	思考模式配置

基础示例

cURL（非流式）
cURL（流式）
Python
Node.js

curl -X POST "https://console.mixroute.io/v1beta/models/gemini-2.5-pro:generateContent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "用一句话介绍人工智能"}]}
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 1024
    }
  }'

curl -X POST "https://console.mixroute.io/v1beta/models/gemini-2.5-pro:streamGenerateContent?alt=sse" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "写一首关于春天的诗"}]}
    ],
    "generationConfig": {
      "temperature": 0.8,
      "maxOutputTokens": 2048
    }
  }'

import google.generativeai as genai

genai.configure(
    api_key="sk-xxxxxxxxxx",
    transport="rest",
    client_options={"api_endpoint": "https://console.mixroute.io"}
)

model = genai.GenerativeModel("gemini-2.5-pro")
response = model.generate_content("用一句话介绍人工智能")
print(response.text)

import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI("sk-xxxxxxxxxx");

// 自定义端点
const model = genAI.getGenerativeModel(
  { model: "gemini-2.5-pro" },
  { baseUrl: "https://console.mixroute.io/v1beta" }
);

const result = await model.generateContent("用一句话介绍人工智能");
console.log(result.response.text());

高级功能

思考模式（Thinking）

Gemini 2.5 Pro 和 Gemini 3 Pro 支持思考模式，使模型在回答前进行深度推理。Gemini 2.5 Pro - 使用 thinkingBudget：

{
  "contents": [{"role": "user", "parts": [{"text": "给一道几何题并分步解析"}]}],
  "generationConfig": {
    "maxOutputTokens": 16384,
    "thinkingConfig": {
      "includeThoughts": true,
      "thinkingBudget": 8192
    }
  }
}

Gemini 3 Pro - 使用 thinkingLevel：

{
  "contents": [{"role": "user", "parts": [{"text": "解释量子纠缠的原理"}]}],
  "generationConfig": {
    "maxOutputTokens": 16384,
    "thinkingConfig": {
      "includeThoughts": true,
      "thinkingLevel": "MEDIUM"
    }
  }
}

参数	适用模型	可选值
`thinkingBudget`	Gemini 2.5 Pro	1-24576（token 数量）
`thinkingLevel`	Gemini 3 Pro	`LOW` / `MEDIUM` / `HIGH`

多模态输入

支持图像、音频、视频等多种输入格式。图像输入（Base64）：

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "BASE64_ENCODED_IMAGE"
          }
        },
        {"text": "描述这张图片的内容"}
      ]
    }
  ]
}

图像输入（URL）：

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "fileData": {
            "mimeType": "image/jpeg",
            "fileUri": "https://example.com/image.jpg"
          }
        },
        {"text": "这张图片里有什么？"}
      ]
    }
  ]
}

支持的 MIME 类型：

图像：image/jpeg, image/png, image/gif, image/webp
音频：audio/mp3, audio/wav, audio/aac
视频：video/mp4, video/webm
文档：application/pdf

工具调用（Function Calling）

{
  "contents": [{"role": "user", "parts": [{"text": "上海今天天气怎么样？"}]}],
  "tools": [
    {
      "functionDeclarations": [
        {
          "name": "get_weather",
          "description": "获取指定城市的天气信息",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "城市名称"
              },
              "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"],
                "description": "温度单位"
              }
            },
            "required": ["location"]
          }
        }
      ]
    }
  ],
  "toolConfig": {
    "functionCallingConfig": {
      "mode": "AUTO"
    }
  }
}

工具调用模式：

AUTO：模型自动决定是否调用
ANY：强制调用工具
NONE：禁止调用工具

Google 搜索（Grounding）

启用 Google 搜索获取实时信息：

{
  "contents": [{"role": "user", "parts": [{"text": "今天北京天气怎么样？"}]}],
  "tools": [
    {
      "googleSearch": {}
    }
  ]
}

动态检索配置：

{
  "contents": [{"role": "user", "parts": [{"text": "最新的 AI 新闻"}]}],
  "tools": [
    {
      "googleSearch": {
        "dynamicRetrievalConfig": {
          "mode": "MODE_DYNAMIC",
          "dynamicThreshold": 0.5
        }
      }
    }
  ]
}

流式输出

Python 流式：

import google.generativeai as genai

genai.configure(
    api_key="sk-xxxxxxxxxx",
    transport="rest",
    client_options={"api_endpoint": "https://console.mixroute.io"}
)

model = genai.GenerativeModel("gemini-2.5-pro")
response = model.generate_content(
    "写一篇关于人工智能的文章",
    stream=True
)

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

cURL 流式：

curl -X POST "https://console.mixroute.io/v1beta/models/gemini-2.5-pro:streamGenerateContent?alt=sse" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "讲一个故事"}]}]
  }'

Context Caching（上下文缓存）

对于长文本或多轮对话，使用缓存可以节省 token 消耗。创建缓存：

curl -X POST "https://console.mixroute.io/v1beta/cachedContents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "models/gemini-2.5-pro",
    "displayName": "my-cache",
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "这是一段很长的文档内容..."}]
      }
    ],
    "ttl": "3600s"
  }'

使用缓存：

{
  "cachedContent": "cachedContents/abc123",
  "contents": [
    {"role": "user", "parts": [{"text": "基于上述文档，总结要点"}]}
  ]
}

图像生成

使用 Gemini 2.0 Flash 或 Imagen 模型生成图像：

{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "生成一张日落时分海边的图片"}]
    }
  ],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"]
  }
}

Imagen 模型：

curl -X POST "https://console.mixroute.io/v1beta/models/imagen-3.0-generate-002:predict" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "instances": [
      {"prompt": "一只可爱的猫咪在阳光下"}
    ],
    "parameters": {
      "sampleCount": 1
    }
  }'

Embedding API

单条 Embedding

curl -X POST "https://console.mixroute.io/v1beta/models/text-embedding-004:embedContent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "content": {
      "parts": [{"text": "这是一段需要向量化的文本"}]
    }
  }'

响应示例：

{
  "embedding": {
    "values": [0.0123, -0.0456, 0.0789, ...]
  }
}

批量 Embedding

curl -X POST "https://console.mixroute.io/v1beta/models/text-embedding-004:batchEmbedContents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "requests": [
      {
        "model": "models/text-embedding-004",
        "content": {"parts": [{"text": "第一段文本"}]}
      },
      {
        "model": "models/text-embedding-004",
        "content": {"parts": [{"text": "第二段文本"}]}
      }
    ]
  }'

响应示例：

{
  "embeddings": [
    {"values": [0.0123, -0.0456, ...]},
    {"values": [0.0234, -0.0567, ...]}
  ]
}

响应格式

{
  "candidates": [
    {
      "content": {
        "parts": [{"text": "回复文本"}],
        "role": "model"
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 10,
    "candidatesTokenCount": 20,
    "totalTokenCount": 30
  }
}

错误处理

HTTP 状态码	错误类型	描述
400	INVALID_ARGUMENT	请求参数无效
401	UNAUTHENTICATED	API 密钥无效或缺失
403	PERMISSION_DENIED	无权访问该模型
404	NOT_FOUND	模型不存在
429	RESOURCE_EXHAUSTED	超出速率限制
500	INTERNAL	服务器内部错误

错误响应示例：

{
  "error": {
    "code": 400,
    "message": "Invalid value at 'contents[0].parts[0]'",
    "status": "INVALID_ARGUMENT"
  }
}

与 OpenAI 格式对比

特性	Gemini 原生	OpenAI 兼容
Base URL	`https://console.mixroute.io/v1beta`	`https://console.mixroute.io/v1`
消息结构	`contents[].parts[]`	`messages[].content`
角色名称	`user` / `model`	`user` / `assistant`
系统提示	`systemInstruction`	`messages[0].role: "system"`
流式请求	URL 参数 `?alt=sse`	Body 参数 `stream: true`
温度范围	0-2	0-2
工具调用	`tools[].functionDeclarations`	`tools[].function`
搜索增强	`tools[].googleSearch`	不支持
思考模式	`thinkingConfig`	不支持

curl --request POST \
  --url 'https://console.mixroute.io/v1beta/models/gemini-2.5-pro:generateContent' \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "contents": [
      {"role": "user", "parts": [{"text": "用一句话介绍人工智能"}]}
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 1024
    }
  }'

{
  "candidates": [
    {
      "content": {
        "parts": [{"text": "人工智能是一门研究如何让计算机模拟和实现人类智能的学科。"}],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": []
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 10,
    "candidatesTokenCount": 20,
    "totalTokenCount": 30
  },
  "modelVersion": "gemini-2.5-pro"
}

当下热门模型

OpenAI 官方库使用

文本系列

文本向量系列

图像系列

视频系列

其他

Gemini 原生（文本）

简介

与 OpenAI 格式的区别

API 端点

认证

请求参数

generationConfig 参数

基础示例

高级功能

思考模式（Thinking）

多模态输入

工具调用（Function Calling）

Google 搜索（Grounding）

流式输出

Context Caching（上下文缓存）

图像生成

Embedding API

单条 Embedding

批量 Embedding

响应格式

错误处理

与 OpenAI 格式对比

当下热门模型

OpenAI 官方库使用

文本系列

文本向量系列

图像系列

视频系列

其他

​简介

​与 OpenAI 格式的区别

​API 端点

​认证

​请求参数

​generationConfig 参数

​基础示例

​高级功能

​思考模式（Thinking）

​多模态输入

​工具调用（Function Calling）

​Google 搜索（Grounding）

​流式输出

​Context Caching（上下文缓存）

​图像生成

​Embedding API

​单条 Embedding

​批量 Embedding

​响应格式

​错误处理

​与 OpenAI 格式对比

简介

与 OpenAI 格式的区别

API 端点

认证

请求参数

generationConfig 参数

基础示例

高级功能

思考模式（Thinking）

多模态输入

工具调用（Function Calling）

Google 搜索（Grounding）

流式输出

Context Caching（上下文缓存）

图像生成

Embedding API

单条 Embedding

批量 Embedding

响应格式

错误处理

与 OpenAI 格式对比