Gemini 图片生成 REST API：当前可直接复制的 cURL 指南

截至 2026 年 3 月 27 日，Gemini 图片生成走原生 REST 最稳的默认路径，是 POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent。 先从这里开始，再加上 responseModalities 和 imageConfig，拿到返回的 inlineData 后保存成图片文件，最后才考虑 OpenAI 兼容层、代理封装或者更贵的模型分支。

这条路线之所以最稳，不是因为别的路径完全没用，而是因为 Google 现在把答案分散在好几页文档里。图片生成文档 讲原生 Gemini 路线，API reference 讲 generateContent 和 imageConfig，OpenAI compatibility 文档 则单独讲兼容层。如果你把这三种页面混着看，很容易误以为它们是同一级默认选项。对新的 raw REST 集成来说，并不是这样。

另一个必须先说清的 caveat 是：当前 Gemini 3 图片模型仍然带有 preview 性质，而且模型命名和推荐路径在最近几个月变动很快。官方 OpenAI 兼容图片示例里还在用 gemini-2.5-flash-image，但 Google 当前的原生图片文档已经把重点转到了 gemini-3.1-flash-image-preview 和 gemini-3-pro-image-preview。如果你不先分清自己到底在调哪一层契约，就很容易把时间浪费在错误的排查方向上。

要点速览

如果你真正卡在 host 和 path 的选择，而不是完整请求流程，先看 Gemini 图片生成 API Base URL。如果你更想要 JavaScript、Python 和 cURL 的多语言示例，可以接着看 Gemini 图片生成代码示例。

先走原生 Gemini REST 路线

对新的 REST 集成来说，最重要的心智模型其实很简单：Gemini 图片生成本质上仍然是一条原生 Gemini API request，只是响应里会返回图片数据。 它不是一个你还没找到的神秘独立图片 host。Google 当前的 API reference 仍然把这条契约定义在 generateContent 下，而图片生成文档也是围绕这条方法族展开。

这对 raw REST 用户尤其重要，因为你通常真正想确认的是三件事：

• 当前正确的 host 和 model path 是什么
• 会影响图片输出的参数应该放在哪里
• 响应里图片数据到底是怎么返回的

原生路径能把这三件事一次讲清。host 明确、文档最新、imageConfig 也直接出现在请求里，不需要先被兼容层重新翻译一次。对 cURL 调试、自建 wrapper、或者暂时不用 SDK 的场景来说，这就是最少歧义的默认答案。

当前默认模型是 gemini-3.1-flash-image-preview。Google 的 models 页面 仍然把它当作当前高效率图片路线，而 gemini-3-pro-image-preview 则是更贵、更偏高质量的一条分支。旧的 gemini-2.5-flash-image 还没有立刻消失，但 Google 的 deprecations 页面 已经给出了 2026 年 10 月 2 日 的下线时间，并把 gemini-3.1-flash-image-preview 标成推荐替代项。

复制一条能跑通的 cURL 请求

一开始不要把事情做复杂。先用一条最小可验证请求，确认 host、model 和图片输出都没问题，再去谈多图编辑、批量生成或者兼容层迁移。最稳的第一条请求长这样：

bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {
          "text": "Create a clean 16:9 product image of a matte black travel mug on a light concrete surface with soft studio lighting and premium ecommerce styling."
        }
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "16:9",
        "imageSize": "2K"
      }
    }
  }'

这条请求的价值不在于 prompt 本身，而在于它一次验证了三层：你确实在调用原生 Gemini Developer API、你选的是当前还活跃的图片模型、并且 responseModalities 与 imageConfig 正在走原生契约。根据 Google 当前 API reference，imageConfig 里可用的 imageSize 仍然包括 512、1K、2K 和 4K。

如果你的场景是文字比较多的海报、图解、信息密度更高的素材，可以把 model path 换成 gemini-3-pro-image-preview，其余请求结构先不动。若你后面真正关心的是价格而不是 REST 写法，直接跳到 Gemini 图片生成 API 价格指南 会更有效率。

把 REST 响应里的图片真正保存出来

很多“REST API 教程”只写到请求发出去为止，但 raw REST 最容易卡住的地方其实是下一步：Gemini 原生响应不会直接给你一个现成文件路径，它会把图片数据包在 JSON 里的 inlineData 里返回。

也正因为如此，第一次调试时很多人会以为“接口只返回了一大段 JSON，所以没出图”。大多数时候不是接口没出图，而是你还没做最后的解码和落盘。

在原生路线里，最稳的处理顺序通常是：

1. 读取 candidates[0].content.parts
2. 找出其中带有 inlineData 的那一段
3. 取出 .inlineData.data
4. 做 base64 解码后写成图片文件

下面这条 shell 管道就是最直接的做法：

bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {
          "text": "Create a square studio photo of a red ceramic teacup on a white background."
        }
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "1:1",
        "imageSize": "1K"
      }
    }
  }' \
| jq -r '.candidates[0].content.parts[] | select(.inlineData) | .inlineData.data' \
| base64 --decode > gemini-image.png

如果你在 macOS 上，本机 base64 命令可能需要改成 base64 -D。真正重要的不是具体命令参数，而是你要先意识到：原生 Gemini REST 的“成功返回”是 JSON 中带有图片字节，而不是立刻出现一个现成 PNG 文件。

这也是为什么 raw REST 其实很适合做第一轮验证。你先看清真实响应契约，后面不管切 SDK、加代理还是做内部封装，都会更容易判断问题到底出在请求结构、模型访问、还是你自己的保存逻辑。

什么时候 OpenAI 兼容图片路径才是对的

OpenAI 兼容路径并不是假的。Google 当前的 compatibility 文档 仍然明确写着：

text
https://generativelanguage.googleapis.com/v1beta/openai/

对应图片端点：

text
/v1beta/openai/images/generations

如果你的项目已经深度依赖 OpenAI 风格 client，而你的核心目标是“尽量不改调用面，先把 Gemini 试通”，那这条路径就有意义。它能让你在迁移时少改很多表层代码。

但它不是这个关键词下最好的默认答案。搜索 “gemini image generation rest api” 的读者，通常真正想要的是 当前原生 Gemini 的 REST 契约，而不是 OpenAI 风格 client 的最低改动迁移方案。这两者的工作目标不一样。

这个差异在官方文档和社区踩坑里都很明显。到 2026 年 3 月 27 日 为止，Google 官方兼容图片示例仍然使用 gemini-2.5-flash-image，而当前原生图片文档已经以 Gemini 3 图片模型为主。社区里也已经出现过开发者把原生图片预期硬塞进 OpenAI 兼容路径，结果收到 404 或 invalid payload 的情况。

所以最实用的判断规则就是：

• 新项目、cURL 调试、学习当前图片 API：先走原生 Gemini
• 必须保留 OpenAI 风格 client surface：再考虑兼容层
• 第一轮排查里不要来回混用两套契约

会改变实现决策的模型、价格和状态 caveat

REST 写法对了，不代表你的实现决策也一定对。模型路线、预览状态、计费和限额，都会直接改变你到底应该走哪条路径。

计费和限额也不能忽略。Google 的 billing 页面 仍然写着，新账号会从 Free Tier 开始，而且只有部分模型在免费限制内可用。rate limits 页面 也明确说，限额取决于使用层级，并且要在 AI Studio 里看你自己的实际额度，而不是假设所有项目都一样。

这也是为什么这篇文章不会轻率地把它写成“完全免费的 Gemini 图片 REST API 教程”。当前现实比这复杂。你的请求可能写对了，但模型不在当前 tier、项目限额更紧、或者 preview 路线比你想象中更严格，这些问题在第一眼看上去都会像 REST 语法错误。

故障排查：先判断是哪一层出了问题

这个关键词本身就带有明显的排错意图。很多人不是在设计接口时搜索它，而是在请求已经失败之后才回头找“正确的 REST API 到底应该怎么写”。好消息是，高频失败模式其实非常重复。

排查这类问题时，最省时间的做法永远是一次只动一层。不要同时换 host、换 model、换 prompt、换保存逻辑。先证明原生请求能返回图片，再证明图片能正确落盘，然后才去比较兼容层、配额或者更高阶的封装。

如果你的问题已经从 endpoint 选择进入了 429、400、500 的修复阶段，下一步更合适的是 Gemini API 报错修复：429、400、500。

FAQ

/v1beta/openai/images/generations 是不是错的？

不是错的，但它不是这个关键词下最该先试的默认答案。只有当你已经有一套 OpenAI 风格 client surface，目标又是尽量少改调用层时，这条兼容路径才更合理。只要你是在做新的 raw REST 集成，先回到原生 generateContent，排错会快得多。

为什么我明明请求成功了，却只拿到一段 JSON？

因为原生 Gemini 图片 REST 的成功返回，本来就是把图片数据包在 JSON 里的 inlineData 中。你看到 JSON 并不代表失败，通常只说明还没做最后一步：抽出 .inlineData.data，做 base64 解码，再把它写成 PNG 或其他图片文件。

现在默认应该先用哪个图片模型？

当前默认仍然应该先从 gemini-3.1-flash-image-preview 开始，因为它是官方原生图片文档当前最明确的高效率路线。如果你的场景是海报、信息图、文字较多的素材，才值得往 gemini-3-pro-image-preview 升。旧的 gemini-2.5-flash-image 还会在兼容示例里出现，但 Google 已给出 2026 年 10 月 2 日 的下线时间。

AI Studio 能跑但 cURL 失败，第一步先查什么？

先不要立刻改 URL。先确认你在 AI Studio 里测试的是不是同一个 project、同一把 key、同一个 model。然后再看 billing、tier 和当前限额。很多看上去像“REST 写错了”的问题，本质上其实是项目上下文和访问权限不一致。

结论

如果你现在要通过 Gemini Developer API 做图片生成，默认应该从这条原生路径开始：

text
POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent

配上 responseModalities 和 imageConfig，把响应里的 inlineData 保存成图片文件，然后只有在你明确需要保留 OpenAI 风格 client surface 时，才切到 /v1beta/openai/images/generations。

这是当前最稳的默认答案，因为它和 Google 现行原生图片文档一致，也最能避开这个关键词背后最常见的误区：把 OpenAI 兼容图片路径误当成所有 Gemini 图片 REST 场景的默认起点。