在使用Gemini API做文本生成任务时，generateContent是最常用的推理接口。相比流式响应，非流式推理会一次性返回完整结果，处理逻辑简单、便于调试，适合绝大多数对延迟不敏感的场景。不过要想正确构建这个请求，需要理解它的请求体结构、角色规则和参数含义，否则很容易遇到400错误或者答非所问的情况。本文从接口结构讲起，配合代码示例把非流式推理请求的构建方法讲透。
一、generateContent接口的基本结构
generateContent是一个标准的HTTP POST接口，非流式调用的请求地址格式为：
POST https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent Header: Content-Type: application/json Header: x-goog-api-key: 你的API密钥
接口路径中的模型名称决定了使用哪个模型，冒号后面的generateContent表示要执行的动作。鉴权推荐使用x-goog-api-key请求头，也可以通过URL参数?key=你的密钥传递，但前者更安全，不容易被日志记录。
请求体的核心是contents字段，它是一个数组，每个元素包含role和parts两个属性。role只有两个合法值：user代表用户输入，model代表模型的历史回复。这一点和OpenAI的assistant角色不同，写错了会直接报错。parts则是内容片段数组，纯文本场景下每一段就是一个text对象，多模态场景下还可以放图片、视频等数据。
二、用Python SDK构建非流式请求
官方提供的google-generativeai库封装了HTTP细节，用起来更简洁。先通过pip安装：pip install google-generativeai，然后就可以构建最简单的单轮推理请求：
import google.generativeai as genai
# 配置API密钥
genai.configure(api_key="你的API密钥")
# 选择模型
model = genai.GenerativeModel("gemini-1.5-flash")
# 非流式推理，直接调用generate_content
response = model.generate_content(
"用一句话解释什么是大语言模型"
)
print(response.text)这个调用是同步阻塞的，执行完才返回完整文本。如果需要带上历史对话实现多轮效果，就要手动维护对话列表，把模型的回复以model角色追加回去：
from google.generativeai import GenerativeModel
model = GenerativeModel("gemini-1.5-flash")
chat_history = [
{"role": "user", "parts": [{"text": "我叫小明，我喜欢爬山"}]},
{"role": "model", "parts": [{"text": "你好小明，爬山是很好的运动！"}]},
{"role": "user", "parts": [{"text": "根据我的爱好推荐一个周末活动"}]}
]
response = model.generate_content(contents=chat_history)
print(response.text)注意角色必须严格按user、model交替排列，如果开头就是model角色，或者出现连续两个user角色，服务端会返回400错误。多轮对话时每一轮的parts里的text都要完整保留，API本身是无状态的，不会替你记住上下文。
三、generationConfig参数详解
请求体中的generationConfig对象控制推理行为，是调优的关键。常用参数包括：
{
"contents": [
{
"role": "user",
"parts": [{"text": "写一首关于秋天的短诗"}]
}
],
"generationConfig": {
"temperature": 0.7,
"topP": 0.9,
"topK": 40,
"maxOutputTokens": 1024,
"stopSequences": ["结束"]
}
}temperature控制随机性，0表示尽量确定性的输出，适合分类、抽取这类任务；0.7到1.0之间适合创意写作。maxOutputTokens限制单次回复的最大token数，注意如果设置得太小，回复会被中途截断，返回内容看起来不完整。 Gemini的输出token和输入token共享模型的上下文窗口，超长输入要预留足够的输出空间。
另一个容易被忽略的坑是安全过滤。如果触发了安全策略，response.text可能为空，这时需要检查response.candidates[0].finish_reason，如果是SAFETY说明被拦截了。可以在请求中显式放宽安全设置：
from google.generativeai.types import HarmCategory, HarmBlockThreshold
response = model.generate_content(
"描述一场古代战争的场面",
safety_settings={
HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT: HarmBlockThreshold.BLOCK_ONLY_HIGH
}
)四、用curl直接调用原生REST接口
不依赖SDK时，直接用curl也能完成非流式调用，这种方式便于在服务器脚本或网关中集成：
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: 你的API密钥" \
-d '{
"contents": [
{
"role": "user",
"parts": [{"text": "把下面的话翻译成英文：今天天气很好"}]
}
],
"generationConfig": {
"temperature": 0.2,
"maxOutputTokens": 512
}
}'返回结果在candidates数组中，取candidates[0].content.parts[0].text就是生成的文本。同时返回体里还有usageMetadata字段，记录了输入和输出的token数量，做成本统计时可以直接读取。需要注意的是，Windows的cmd对单引号支持不好，建议在PowerShell或Git Bash中执行上面的命令，或者用Python的requests库发送。
总的来说，非流式推理的核心就三件事：正确的contents结构、合理的generationConfig配置、以及对返回体中candidates和finish_reason的正确解析。把这些细节处理到位，一个稳定可用的Gemini推理调用就搭建完成了。如果后续需要做打字机效果的输出，再切换到streamGenerateContent接口即可，请求体的构建方式基本一致。
Gemini APIgenerateContent非流式推理修改时间：2026-09-06 13:18:49