Generate Content

generateContent 是 Gemini 原生 REST API 里最常用的生成接口，适合文本问答、多轮对话、结构化输出以及多模态理解场景。

请求地址

POST https://huobaoapi.com/v1beta/models/{model}:generateContent

示例模型：

• gemini-3-flash-preview
• gemini-3-pro-preview
• gemini-2.5-flash

鉴权

• Google 官方原生示例使用 x-goog-api-key: $GEMINI_API_KEY
• 如果通过YL中转调用，可使用平台 API Key；下方示例按YL网关地址编写

最小请求示例

这是你要的 generateContent 接口写法，对应模型 gemini-3-flash-preview：

curl "https://huobaoapi.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ]
      }
    ]
  }'

对应 Google 官方原生写法：

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ]
      }
    ]
  }'

常用请求字段

字段	必填	说明
contents	是	对话内容数组，至少包含一条消息
contents[].role	否	角色，常见为 user 或 model
contents[].parts	是	消息内容片段数组
parts[].text	否	文本输入
parts[].inlineData	否	Base64 编码的图片、音频、视频等内联数据
parts[].fileData	否	已上传文件引用
system_instruction	否	系统提示词；部分 SDK 中对应 systemInstruction
generationConfig	否	生成配置，例如温度、输出格式、思考配置
safetySettings	否	安全过滤配置
tools	否	工具定义，例如 Google Search、函数调用等

请求体示例

纯文本生成

{
  "contents": [
    {
      "parts": [
        {
          "text": "Explain how AI works in a few words"
        }
      ]
    }
  ]
}

带系统提示词

{
  "system_instruction": {
    "parts": [
      {
        "text": "You are a concise assistant."
      }
    ]
  },
  "contents": [
    {
      "parts": [
        {
          "text": "Explain how AI works in a few words"
        }
      ]
    }
  ]
}

带生成参数

{
  "contents": [
    {
      "parts": [
        {
          "text": "Explain how AI works in a few words"
        }
      ]
    }
  ],
  "generationConfig": {
    "temperature": 0.7,
    "topP": 0.8,
    "topK": 20,
    "maxOutputTokens": 256,
    "responseMimeType": "text/plain"
  }
}

多轮对话

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Hello"
        }
      ]
    },
    {
      "role": "model",
      "parts": [
        {
          "text": "Great to meet you. What would you like to know?"
        }
      ]
    },
    {
      "role": "user",
      "parts": [
        {
          "text": "Explain how AI works in a few words"
        }
      ]
    }
  ]
}

返回结构示例

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "AI learns patterns from data and uses them to make predictions."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "avgLogprobs": -0.12
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 8,
    "candidatesTokenCount": 14,
    "totalTokenCount": 22
  },
  "modelVersion": "gemini-3-flash-preview"
}

常见返回字段

字段	说明
candidates	候选结果数组
candidates[].content.parts[].text	模型输出文本
candidates[].finishReason	停止原因，常见如 STOP
usageMetadata	token 统计信息
modelVersion	实际返回的模型版本
promptFeedback	提示词过滤或阻止信息

流式输出

如果你要流式返回，需要使用：

POST /v1beta/models/{model}:streamGenerateContent?alt=sse

示例：

curl "https://huobaoapi.com/v1beta/models/gemini-3-flash-preview:streamGenerateContent?alt=sse" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works"
          }
        ]
      }
    ]
  }'

适用场景

• 文本问答
• 多轮聊天
• 图文理解
• 音频、视频、PDF 理解后输出文本
• JSON 结构化输出
• 工具调用和搜索增强

注意事项

• generateContent 通常是同步接口，直接返回生成结果
• 如果输入的是图片、音频、视频等多模态内容，输出仍然通常是文本
• 如果需要视频生成，不应使用这个接口，而应看 Veo 3.1 Fast 视频生成
• 如果需要流式文本输出，使用 streamGenerateContent

参考文档

• Gemini Text Generation: https://ai.google.dev/gemini-api/docs/text-generation
• Gemini 3 Developer Guide: https://ai.google.dev/gemini-api/docs/gemini-3