Gemini Generate Content

Gemini Generate Content 适合使用 Gemini 原生格式的项目，支持文本、多模态输入、函数调用、JSON 输出和流式返回。

接口概览

能力	方法	路径
生成内容	`POST`	`/v1beta/models/{model}:generateContent`
流式生成	`POST`	`/v1beta/models/{model}:streamGenerateContent`

Gemini 原生格式使用 Query 参数认证：

?key=$API_KEY

请求体

参数	类型	必填	说明
`contents`	array	是	当前对话内容
`systemInstruction`	object	否	系统指令
`generationConfig`	object	否	生成参数
`tools`	array	否	函数调用、代码执行等工具
`toolConfig`	object	否	工具调用配置
`safetySettings`	array	否	安全过滤配置
`cachedContent`	string	否	缓存内容名称
`labels`	object	否	请求标签

参数	类型	必填	说明
`role`	string	否	`user`、`model`、`function`、`tool`
`parts`	array	是	内容块数组

parts

字段	说明
`text`	文本内容
`inlineData`	base64 媒体内容
`fileData`	文件 URI 引用
`functionCall`	模型发起的函数调用
`functionResponse`	工具调用结果

字段大小写

Gemini API 的类型定义使用 lowerCamelCase，例如 systemInstruction、generationConfig、inlineData、mimeType。Google REST 示例里有时会出现 inline_data、mime_type 这类 snake_case 写法；如果遇到客户端兼容问题，优先使用官方 SDK 或保持同一种写法。

请求示例

curl "https://cdn.12ai.org/v1beta/models/gemini-3-pro-preview:generateContent?key=$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{"text": "用一句话解释 Gemini API"}]
    }]
  }'

from google import genai

client = genai.Client(
    api_key="sk-xxx",
    http_options={"base_url": "https://cdn.12ai.org"},
)

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="用一句话解释 Gemini API",
)

print(response.text)

{
  "contents": [
    {"role": "user", "parts": [{"text": "我有两只狗。"}]},
    {"role": "model", "parts": [{"text": "好的。"}]},
    {"role": "user", "parts": [{"text": "它们一共有几条腿？"}]}
  ]
}

{
  "contents": [{
    "parts": [{"text": "列出 3 个常见 HTTP 状态码，返回 JSON"}]
  }],
  "generationConfig": {
    "responseMimeType": "application/json"
  }
}

curl "https://cdn.12ai.org/v1beta/models/gemini-3-pro-preview:streamGenerateContent?alt=sse&key=$API_KEY" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "contents": [{
      "parts": [{"text": "写一个很短的故事"}]
    }]
  }'

响应结构

字段	类型	说明
`candidates`	array	候选输出
`usageMetadata`	object	token 用量
`modelVersion`	string	模型版本
`responseId`	string	响应 ID
`promptFeedback`	object	提示词过滤或拦截信息，可能为空

candidates

字段	说明
`content.parts`	输出内容块
`finishReason`	停止原因，例如 `STOP`、`MAX_TOKENS`、`SAFETY`
`safetyRatings`	安全评分

响应示例

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Gemini API 是 Google Gemini 模型的原生内容生成接口。"
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 8,
    "candidatesTokenCount": 18,
    "totalTokenCount": 26
  },
  "modelVersion": "gemini-3-pro-preview",
  "responseId": "response_xxx"
}

多模态输入

图片、音频、视频、PDF 等文件建议使用 inlineData 传入 base64 内容。

{
  "contents": [{
    "parts": [
      {"text": "描述这张图片"},
      {
        "inlineData": {
          "mimeType": "image/jpeg",
          "data": "<BASE64_IMAGE_DATA>"
        }
      }
    ]
  }]
}

函数调用

{
  "contents": [{
    "parts": [{"text": "把灯调成蓝色"}]
  }],
  "tools": [{
    "functionDeclarations": [{
      "name": "set_light_color",
      "description": "设置灯光颜色",
      "parameters": {
        "type": "object",
        "properties": {
          "color": {"type": "string"}
        },
        "required": ["color"]
      }
    }]
  }]
}

生成配置

参数	说明
`generationConfig.temperature`	随机性
`generationConfig.topP`	核采样参数
`generationConfig.topK`	Top-K 采样
`generationConfig.maxOutputTokens`	最大输出 token 数
`generationConfig.responseMimeType`	输出 MIME 类型，例如 `application/json`
`generationConfig.responseSchema`	结构化输出 schema

常见错误

状态码	Gemini 状态	处理方式
`400`	`INVALID_ARGUMENT`	检查 `contents`、参数大小写和 JSON 结构
`401`	`UNAUTHENTICATED`	检查 `?key=$API_KEY`
`404`	`NOT_FOUND`	检查模型名和路径
`429`	`RESOURCE_EXHAUSTED`	降低频率或稍后重试
`500`	`INTERNAL`	重试；如持续出现，联系支持

更多参数细节可参考 Google Gemini Generate Content API。

Gemini Generate Content

On this page