Gemini 原生协议

Gemini 原生接口保留 Google Gemini 的请求和响应结构，适合直接使用 contents、generationConfig、safetySettings、工具调用和多模态 parts 的客户端。

如果你的客户端使用 OpenAI Chat Completions 格式，请改用 Gemini Chat。两种协议的请求体和响应体不能混用。

基础地址与鉴权

基础地址：

https://cubicspaces.cloud

推荐通过 x-goog-api-key 请求头传递 Cubicspaces API Key：

x-goog-api-key: YOUR_API_KEY

请勿把 API Key 写入公开代码、前端页面或可公开访问的 URL。

接口列表

功能	方法与路径
查询模型	GET /v1beta/models
非流式生成	POST /v1beta/models/{model}:generateContent
流式生成	POST /v1beta/models/{model}:streamGenerateContent?alt=sse

实际可用模型以账户权限和平台配置为准。文字模型包括：

模型
gemini-3.1-pro-preview
gemini-3.1-flash-lite
gemini-3-flash-preview

非流式请求

curl "https://cubicspaces.cloud/v1beta/models/gemini-3.1-pro-preview:generateContent" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "用一句话介绍 Gemini。" }
        ]
      }
    ],
    "generationConfig": {
      "thinkingConfig": {
        "thinkingLevel": "low"
      },
      "maxOutputTokens": 512
    }
  }'

模型名称位于 URL 路径中，请求体中不需要额外传递 model。

原生响应

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          { "text": "Gemini 是 Google 推出的多模态生成式 AI 模型系列。" }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 12,
    "candidatesTokenCount": 18,
    "thoughtsTokenCount": 32,
    "totalTokenCount": 62
  },
  "modelVersion": "gemini-3.1-pro-preview",
  "responseId": "example-response-id"
}

文本通常从下面的位置读取：

candidates[0].content.parts[*].text

thoughtsTokenCount 等用量字段仅在响应包含相应类型的 token 时出现。

流式请求

curl -N "https://cubicspaces.cloud/v1beta/models/gemini-3.1-pro-preview:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "写一段简短的产品介绍。" }
        ]
      }
    ]
  }'

流式响应使用 SSE。每个 data: 事件携带 Gemini 原生响应片段，文本仍从 candidates[].content.parts[].text 读取。

会话亲和

如需让同一会话的连续请求保持亲和，请在每次请求中携带相同且稳定的 X-Affinity-Key：

X-Affinity-Key: project-or-session-id

不需要额外携带 Cookie。该值应为不含 API Key、邮箱、手机号或提示词内容的非敏感会话标识。完整说明请参阅 缓存与请求亲和。

常用原生字段

• contents：对话内容，由 role 和 parts 组成。
• systemInstruction：系统指令。
• generationConfig：生成配置，例如 maxOutputTokens、temperature 和 thinkingConfig。
• safetySettings：安全策略配置。
• tools、toolConfig：函数调用等工具配置。
• cachedContent：Gemini 缓存内容标识。

字段使用 Gemini 原生 camelCase 命名。不要在该接口中发送 OpenAI 格式的 messages、stream 或 choices 字段。

官方参考

• Gemini GenerateContent API
• Gemini 3 原生 GenerateContent 指南
• Gemini 3.1 Pro Preview 模型说明