Gemini generateContent — Google 原生格式

OpenOpen8 在 /v1beta/models/{model} 路径下提供 Google Gemini 兼容端点，与 Google AI SDK 和 Gemini REST API 的格式一致。使用 x-goog-api-key 头或 key 查询参数传入你的 OpenOpen8 token 进行认证——无需 Google 凭据。OpenOpen8 将请求路由到你在 URL 路径中指定的模型对应的上游渠道。

端点

方法	路径	说明
`POST`	`/v1beta/models/{model}:generateContent`	生成响应（非流式）
`POST`	`/v1beta/models/{model}:streamGenerateContent`	流式生成响应

模型名在 URL 路径中指定，不在请求体中。例如，要使用 gemini-2.0-flash，发送 POST 到 /v1beta/models/gemini-2.0-flash:generateContent。

认证

通过以下任一方式传入 OpenOpen8 token： 请求头（推荐）：

x-goog-api-key: YOUR_TOKEN

查询参数：

POST /v1beta/models/gemini-2.0-flash:generateContent?key=YOUR_TOKEN

请求参数

contents

object[]

必填

对话历史，由内容对象数组组成。每个对象包含 role 和 parts 数组。

显示内容属性

contents[].role

string

内容作者的角色。用户轮次用 "user"，模型轮次用 "model"。单轮请求可省略。

contents[].parts

object[]

必填

组成该轮次的内容部分数组。

显示 part 属性

contents[].parts[].text

string

文本部分。用于纯文本输入或与其他模态一起提供文本。

contents[].parts[].inlineData

object

内联二进制数据（如 base64 编码的图片或音频）。

显示 inlineData 属性

contents[].parts[].inlineData.mimeType

string

必填

数据的 MIME 类型，例如 "image/jpeg"、"audio/mp3" 或 "video/mp4"。

contents[].parts[].inlineData.data

string

必填

Base64 编码的字节数据。

contents[].parts[].fileData

object

通过 URI 引用的文件，例如 Google Cloud Storage URI 或 Files API URI。

显示 fileData 属性

contents[].parts[].fileData.mimeType

string

文件的 MIME 类型。

contents[].parts[].fileData.fileUri

string

必填

文件的 URI。

contents[].parts[].functionCall

object

模型请求的 function calling。包含 name 和 args。

contents[].parts[].functionResponse

object

function calling 的结果。包含 name 和 response。

systemInstruction

object

系统提示词。结构与 contents 项相同：包含 parts 数组的对象。系统指令仅支持 text 部分。

{
  "systemInstruction": {
    "parts": [{"text": "You are a helpful assistant."}]
  }
}

也接受 system_instruction（snake_case 形式）。

generationConfig

object

控制模型生成输出的参数。也接受 generation_config。

显示 generationConfig 属性

generationConfig.temperature

number

采样温度。值越高越有创造性，值越低越确定。

generationConfig.topP

number

核采样概率质量。也接受 top_p。

generationConfig.topK

number

Top-k 采样。也接受 top_k。

generationConfig.maxOutputTokens

integer

最大生成 token 数。也接受 max_output_tokens。

generationConfig.candidateCount

integer

生成的候选响应数量。默认为 1。

generationConfig.stopSequences

string[]

模型遇到这些序列时停止生成。也接受 stop_sequences。

generationConfig.responseMimeType

string

响应的 MIME 类型。设为 "application/json" 可请求 JSON 输出。也接受 response_mime_type。

generationConfig.responseSchema

object

响应必须遵循的 JSON Schema。需要 responseMimeType 为 "application/json"。也接受 response_schema。

generationConfig.responseModalities

string[]

请求的输出模态，例如 ["TEXT"] 或 ["TEXT", "IMAGE"]。也接受 response_modalities。

generationConfig.thinkingConfig

object

扩展思考配置。也接受 thinking_config。

显示 thinkingConfig 属性

generationConfig.thinkingConfig.includeThoughts

boolean

是否在响应中包含模型的思考内容。也接受 include_thoughts。

generationConfig.thinkingConfig.thinkingBudget

integer

用于思考的最大 token 数。也接受 thinking_budget。

generationConfig.thinkingConfig.thinkingLevel

string

推理强度："low"、"medium" 或 "high"。也接受 thinking_level。

tools

object[]

模型可使用的工具。支持 functionDeclarations、googleSearch、googleSearchRetrieval、codeExecution 和 urlContext。

toolConfig

object

控制模型如何选择工具。

显示 toolConfig 属性

toolConfig.functionCallingConfig

object

function calling 配置。

显示 functionCallingConfig 属性

toolConfig.functionCallingConfig.mode

string

function calling 模式："AUTO"、"ANY" 或 "NONE"。

toolConfig.functionCallingConfig.allowedFunctionNames

string[]

当 mode 为 "ANY" 时，限制只能调用此列表中的函数。

safetySettings

object[]

覆盖默认安全过滤器。每项指定一个 category 和 threshold。

响应字段

candidates

object[]

生成的响应候选数组。

显示 candidate 属性

candidates[].content

object

生成的内容。

显示 content 属性

candidates[].content.role

string

生成内容的角色，始终为 "model"。

candidates[].content.parts

object[]

内容部分数组。每个部分包含 text 字段（文本输出）或 functionCall（tool calling）。带 thought: true 的部分包含模型的内部推理（启用思考时）。

candidates[].finishReason

string

模型停止的原因。常见值："STOP"（自然结束）、"MAX_TOKENS"（达到 token 限制）、"SAFETY"（安全过滤）、"RECITATION"。

candidates[].index

integer

此候选的索引。

candidates[].safetyRatings

object[]

各危害类别的安全评级。

usageMetadata

object

请求的 token 用量。

显示 usageMetadata 属性

usageMetadata.promptTokenCount

integer

输入 contents 中的 token 数量。

usageMetadata.candidatesTokenCount

integer

生成候选中的 token 数量。

usageMetadata.totalTokenCount

integer

总 token 用量。

usageMetadata.thoughtsTokenCount

integer

用于思考的 token 数量（启用扩展思考时）。

promptFeedback

object

关于提示词的反馈，包括安全评级和拦截原因（如果提示词被拦截）。

示例

非流式
流式
多轮对话

curl "https://openopen8.ai/v1beta/models/gemini-2.0-flash:generateContent" \
  -H "x-goog-api-key: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "Explain the difference between RAM and ROM."}]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 512
    }
  }'

响应示例：

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "RAM (Random Access Memory) is volatile memory used for temporary storage while your computer is running..."
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": []
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 11,
    "candidatesTokenCount": 142,
    "totalTokenCount": 153
  }
}

cURL

curl "https://openopen8.ai/v1beta/models/gemini-2.0-flash:streamGenerateContent" \
  -H "x-goog-api-key: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Count from 1 to 5."}]}
    ]
  }'

服务端返回以换行符分隔的 JSON 对象流，每个代表一个部分响应块。每个块的结构与非流式响应相同，包含部分 candidates[].content.parts[].text。

cURL

curl "https://openopen8.ai/v1beta/models/gemini-2.0-flash:generateContent" \
  -H "x-goog-api-key: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "systemInstruction": {
      "parts": [{"text": "You are a geography expert."}]
    },
    "contents": [
      {"role": "user", "parts": [{"text": "What is the longest river in Africa?"}]},
      {"role": "model", "parts": [{"text": "The Nile is the longest river in Africa."}]},
      {"role": "user", "parts": [{"text": "How long is it in kilometers?"}]}
    ]
  }'

思考模型

OpenOpen8 支持 Gemini 思考模型，模型在生成响应前进行额外推理。有三种方式启用思考： 1. 思考模型后缀 — 在支持的模型名后追加 -thinking：

POST /v1beta/models/gemini-2.5-flash-thinking:generateContent
POST /v1beta/models/gemini-2.5-pro-thinking:generateContent

2. 强度后缀 — 追加 -low、-medium 或 -high 精细控制：

POST /v1beta/models/gemini-2.5-flash-high:generateContent

3. generationConfig 中的 thinkingConfig — 显式传入配置：

{
  "contents": [...],
  "generationConfig": {
    "thinkingConfig": {
      "includeThoughts": true,
      "thinkingBudget": 8192
    }
  }
}

启用思考后，响应中带 "thought": true 的部分包含模型的推理内容。这些部分默认不展示给终端用户——由你的应用决定是否显示。

如果只需要文本输出，不想处理思考部分，设置 includeThoughts: false，让模型在内部推理但不在响应体中包含这些 token。

概览

对话与补全

媒体与多模态

其他端点

Gemini generateContent — Google 原生格式

端点

认证

请求参数

响应字段

示例

思考模型

概览

对话与补全

媒体与多模态

其他端点

​端点

​认证

​请求参数

​响应字段

​示例

​思考模型

端点

认证

请求参数

响应字段

示例

思考模型