Gemini generateContent

兼容 Google Gemini 官方 POST /v1beta/models/{model}:generateContent 接口，用于调用 Gemini 系列模型进行文本、视觉、代码等任务。

WARNING

建议使用官方原生接口。本接口为 Gemini 原生格式，是调用 Gemini 系列模型的推荐方式。若通过本接口调用非 Gemini 模型，由代理侧进行格式转换，可能存在参数缺失或行为差异等问题。具体支持范围请咨询 FreeAPI。

请求

Endpoint

POST https://www.free-api.ai/api/v1beta/models/{model}:generateContent

流式版本：

POST https://www.free-api.ai/api/v1beta/models/{model}:streamGenerateContent

路径参数

名称	必填	说明
model	是	模型名称，例如 gemini-2.5-pro、gemini-2.5-flash

请求头

名称	必填	说明
Authorization	是	Bearer your-api-key
Content-Type	是	application/json

请求参数

字段	类型	必填	说明
contents	array	是	对话内容数组，每项包含 role 与 parts
systemInstruction	object	否	系统指令，结构同 contents 元素
generationConfig	object	否	生成配置
safetySettings	array	否	安全分级配置
tools	array	否	工具定义（function calling / googleSearch 等）
toolConfig	object	否	工具使用配置

contents 结构

{
  "role": "user | model",
  "parts": [
    { "text": "..." },
    { "inlineData": { "mimeType": "image/jpeg", "data": "<base64>" } },
    { "fileData": { "mimeType": "image/jpeg", "fileUri": "..." } }
  ]
}

generationConfig 常用字段

字段	类型	说明
temperature	number	采样温度
topP	number	核采样
topK	integer	Top-K 采样
maxOutputTokens	integer	最大输出 Token 数
stopSequences	string[]	停止序列
responseMimeType	string	响应 MIME 类型，例如 application/json
responseSchema	object	响应 JSON Schema
responseModalities	string[]	响应模态，例如 ["TEXT"]、["TEXT", "IMAGE"]
thinkingConfig	object	思考配置，如 { "thinkingBudget": 4096 }

请求示例

cURL

curl "https://www.free-api.ai/api/v1beta/models/gemini-2.5-pro:generateContent" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{ "text": "用一句话解释相对论。" }]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 512
    }
  }'

多模态（图像输入）

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "这张图片里有什么？" },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "<base64-encoded-image>"
          }
        }
      ]
    }
  ]
}

Python (google-genai SDK)

from google import genai

client = genai.Client(
    api_key="your-api-key",
    http_options={"base_url": "https://www.free-api.ai/api"},
)

resp = client.models.generate_content(
    model="gemini-2.5-pro",
    contents="用一句话解释相对论。",
)
print(resp.text)

响应示例

非流式

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          { "text": "时间和空间相对于观察者而言，不是绝对的。" }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": []
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 12,
    "candidatesTokenCount": 18,
    "totalTokenCount": 30
  }
}

流式 (streamGenerateContent)

流式接口返回 JSON 数组片段，每个片段结构与非流式响应一致，内容以增量方式在 candidates[0].content.parts 中累加。

finishReason 取值

值	含义
STOP	模型自然结束
MAX_TOKENS	达到最大 Token 限制
SAFETY	被安全策略阻断
RECITATION	命中复述检测
OTHER	其他原因

常见错误

HTTP 状态	说明
400	请求参数错误
401 / 403	鉴权失败
429	请求频率限制
5xx	上游服务异常