Gemini API核心教程：详解文本生成接口generateContent

详解 generateContent 接口：Gemini API 最核心的调用方法

在基于 Gemini API 构建生成式 AI 应用时，generateContent 接口无疑是你绕不开的核心。简单来说，它就像整个系统的“总控台”：负责接收你的各种输入——无论是文字、图片还是视频，指挥模型进行推理，并把结构化的结果清晰地送回来。接下来的内容，我们就把它掰开揉碎，讲个明白。

一、基础请求结构与必需参数

调用这个接口，第一步就是构造一个规范的请求体，它得符合 REST 或 gRPC 协议。这里头，content 字段是重中之重，所有你要输入的多模态数据都得打包塞进去。当然，有效的 API 密钥和指定的模型名称（比如 gemini-1.5-flash）也是必不可少的“通行证”。

具体流程可以拆解为四步：首先，构建一个 JSON 请求体，其根对象必须包含 model 和 contents 这两个顶层字段。其次，在 contents 数组中，每个元素都是一个 Part 对象，它里面至少得有 text 或 inline_data 字段中的一个。第三，如果要传图片，就得把图像的二进制数据转换成 Base64 编码，填到 inline_data.data 里去，同时别忘了把 mime_type 设置为 image/png 或 image/jpeg。最后，带着所有这些信息，向这个地址发起 POST 请求：https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContentkey={API_KEY}。

二、支持的输入类型组合方式

这个接口的强大之处在于，它能原生理解并处理文本、图像、音频、视频乃至 PDF 的混合输入。所有这些不同类型的“素材”，都统一通过 contents 数组里不同形态的 Part 来表达，系统会自动识别它们，并分发给对应的编码器去处理。

在实际使用中，你会遇到几种典型组合：最基础的是纯文本输入，这时 contents 数组里只放一个 text 类型的 Part 就行，其 value 就是 UTF-8 编码的字符串。如果想要图文并茂，数组里就同时包含一个 text 类型的 Part 和一个 inline_data 类型的 Part，后者负责承载 Base64 编码的图像数据。如果需要上传多张图片也没问题，在数组中放入多个 inline_data 类型的 Part 即可，每个都带着自己独立的 mime_type 和 data。至于处理 PDF 文件，逻辑也类似：把 PDF 的二进制数据 Base64 编码后填入 inline_data.data，并将 mime_type 设置为 application/pdf。

三、响应结构关键字段解析

请求成功之后，你会拿到一个 JSON 格式的响应对象。这里的核心是 candidates 数组，每一个 candidate 里都包含一个 content 字段，这个字段下的 parts 数组，装的就是模型生成的具体内容片段。此外，关于安全过滤和生成状态的重要信息，则藏在 safety_ratings 和 finish_reason 这些字段里。

解读响应时，有几个关键点：首先，通过 candidates[0].content.parts[0].text 这个路径，就能拿到第一条生成的文本内容。其次，务必检查一下 finish_reason 字段的值，如果是 STOP，说明生成过程正常结束；如果显示 MAX_TOKENS，那就意味着输出因为达到长度限制而被截断了。第三，为了确认内容是否安全，可以遍历 safety_ratings 数组，比对各个条目的 category 和 blocked 状态，看看有没有触发安全规则。最后，如果你的应用需要流式响应，那就要改用 generateContentStream 这个端点，它的响应体是 Server-Sent Events 格式的。

四、常见错误码与定位方式

返回的 HTTP 状态码直接反映了请求的合法性和服务可用性。一般来说，4xx 类的错误多半是客户端构造请求时出了问题，而 5xx 错误则指向服务端异常。这时候，结合响应里 error.details 字段的信息，能更精准地定位原因。

有几个常见的错误值得注意：遇到 400 Bad Request，通常是检查 contents 是不是空数组、Part 里是否同时存在 text 和 inline_data 字段，或者 Base64 数据格式有误。看到 403 Forbidden，需要验证三件事：API 密钥是否已经启用了 Gemini API 服务、调用配额是否用完、项目有没有绑定有效的计费账户。如果返回 429 Too Many Requests，基本可以确定是触发了每分钟请求数或令牌数的限制，解决方法是在客户端引入指数退避的重试逻辑。最麻烦的是 500 Internal Error，这属于服务端内部错误，客户端无法自行修复，正确的做法是记录下 request_id 然后联系 Google Cloud 的支持团队。

五、请求头与认证配置要点

除了必备的 API 密钥，在一些特定的部署场景下，显式地声明一些请求头，能更好地确保兼容性和性能。虽然有了 key 参数通常就不再需要 Authorization 头，但 Accept 和 Content-Type 这两个头必须严格匹配，不能出错。

具体来说，有这几个配置要点：第一，务必将 Content-Type 设置为 application/jsonmultipart/form-data。第二，Accept 头也要设为 application/json，避免服务端返回非 JSON 格式的响应。第三，如果需要跨区域调用，记得添加 x-goog-user-project 头，其值填写对应的结算项目 ID。第四，对于企业级部署，还可以附加 x-goog-api-client 头，用来标识所使用的 SDK 版本和运行环境信息，便于追踪和调试。