generateContent 是什么
generateContent 是 Google Gemini 的模型调用接口，路径形如 POST /v1beta/models/{model}:generateContent，请求体用 contents[].parts[] 承载文本与图片等行内数据，系统提示单独放在 systemInstruction，函数工具放在 tools 字段；流式改成 :streamGenerateContent。鉴权用 x-goog-api-key 请求头（也支持 key 查询参数，但会落进代理与访问日志，不建议）。输出文本在 candidates[0].content.parts 中，被安全策略拦截时看 promptFeedback 与 finishReason。
基本信息
| 请求路径 | /v1beta/models/{model}:generateContent |
|---|---|
| 流式路径 | /v1beta/models/{model}:streamGenerateContent |
| 鉴权方式 | 请求头 x-goog-api-key |
| 请求结构 | contents → parts → text |
| 系统提示 | systemInstruction 独立字段 |
| 响应取值 | candidates[0].content.parts[].text |
典型使用场景
- 多模态理解：图片、PDF 页面截图与文本混合输入后抽取信息
- 长文档问答：把整篇材料放进 contents 做归纳
- 工具调用：用 tools 声明函数，让模型产出调用参数
- 流式前端：用 streamGenerateContent 降低首字延迟
- 海外业务接入：多供应商路由中的一路候选
最小调用与参数
最小调用与参数
# 密钥走请求头，不要拼进 URL
export GEMINI_API_KEY=你的密钥
cat > payload.json <<'EOF'
{"systemInstruction":{"parts":[{"text":"你只回答技术问题"}]},
"contents":[{"parts":[{"text":"用一句话解释 DNS"}]}],
"generationConfig":{"temperature":0.2,"maxOutputTokens":256}}
EOF
curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" -H "Content-Type: application/json" -d @payload.json响应字段逐列读法
| 字段 | 含义 | 异常表现 |
|---|---|---|
| candidates[0].content.parts | 模型输出，可能被拆成多段 | 为空说明被拦截或未产生内容 |
| finishReason | STOP 正常、MAX_TOKENS 截断、SAFETY 拦截 | MAX_TOKENS 需提高上限或缩短输入 |
| promptFeedback | 输入侧的安全判定结果 | blockReason 非空表示请求被拒 |
| usageMetadata | 输入输出 token 计数 | 为空时无法做成本对账 |
生成参数逐项读法
| 参数 | 作用 | 取值建议 |
|---|---|---|
| temperature | 控制随机性 | 抽取与分类取 0-0.3，创意写作再调高 |
| maxOutputTokens | 输出长度上限 | 太小会被截断，finishReason 显示 MAX_TOKENS |
| topP | 候选词采样范围 | 通常不必同时调，与 temperature 二选一 |
| stopSequences | 遇到即停止的字符串 | 用于截断多余尾巴，注意不要误伤正常内容 |
| responseMimeType | 声明返回格式 | 需要结构化结果时配合 schema 使用 |
Gemini 用 contents 与 parts，而不是 OpenAI 的 messages 结构；直接把旧请求体搬过来会返回参数错误。迁移时要做请求体适配层。
被安全策略拦截不一定是模型出错：先看 promptFeedback 与 finishReason 定位是输入侧还是输出侧触发，再决定改写提示词还是补人工兜底。