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

> 直接给你当前 Gemini 图片生成 REST API 的正确写法：先跑通原生 cURL 请求、把返回图片保存下来，再避开仍然常见的 OpenAI 兼容路径误用。

- Source: https://www.aifreeapi.com/zh/posts/gemini-image-generation-rest-api
- Language: zh
- Published: 2026-03-27
- Updated: 2026-10-08
- Publisher: AI Free API (https://www.aifreeapi.com)

> **2026 年 10 月 8 日更正：** Google 已把 `gemini-2.5-flash-image` 的关停日期从原定的 2026 年 10 月 2 日推迟到 2027 年 3 月 15 日，替代模型改列为 `gemini-3.1-flash-lite-image`（Nano Banana 2 Lite）；文中“10 月 2 日停用”的说法已不适用。

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

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

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

![Gemini 图片生成 REST API 指南，展示原生 generateContent 路线、当前模型选择和 cURL 工作流](https://www.aifreeapi.com/posts/zh/gemini-image-generation-rest-api/img/cover.png)

## 要点速览

| 你的情况 | 第一条该用的路径 | 建议先用的模型 | 为什么这是当前默认答案 | 主要 caveat |
| --- | --- | --- | --- | --- |
| 新项目直接做 raw REST | `POST /v1beta/models/gemini-3.1-flash-image-preview:generateContent` | `gemini-3.1-flash-image-preview` | 最贴近当前 Gemini 原生图片文档，也能直接使用 `imageConfig` | 现有 Gemini 3 图片模型仍然是 preview 路线 |
| 要做文字较多的海报、信息图 | 同样走原生 `generateContent` | `gemini-3-pro-image-preview` | 对复杂布局和高价值图片更稳 | 成本更高，而且同样是 preview |
| 你必须保留现有 OpenAI 风格 client | `POST /v1beta/openai/images/generations` | 以兼容文档当前支持为准 | 最小化迁移成本 | 兼容层是另一套契约，不是新的原生默认路径 |
| AI Studio 能跑，cURL 不行 | 往往不是 URL 本身的问题 | 先确认同一项目和模型 | 项目计费、权限或限额常常才是真正原因 | Google 并没有公开一张所有用户都一样的静态限额表 |

如果你真正卡在 host 和 path 的选择，而不是完整请求流程，先看 [Gemini 图片生成 API Base URL](/zh/posts/gemini-image-generation-api-base-url)。如果你更想要 JavaScript、Python 和 cURL 的多语言示例，可以接着看 [Gemini 图片生成代码示例](/zh/posts/gemini-image-generation-code-examples)。

## 先走原生 Gemini REST 路线

![展示原生 Gemini generateContent 堆栈的路由图，将模型选择和兼容层上下文放在次要位置。](https://www.aifreeapi.com/posts/zh/gemini-image-generation-rest-api/img/native-route-stack.png)

对新的 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 页面](https://ai.google.dev/gemini-api/docs/models) 仍然把它当作当前高效率图片路线，而 `gemini-3-pro-image-preview` 则是更贵、更偏高质量的一条分支。旧的 `gemini-2.5-flash-image` 还没有立刻消失，但 Google 的 [deprecations 页面](https://ai.google.dev/gemini-api/docs/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](https://ai.google.dev/api/generate-content)，`imageConfig` 里可用的 `imageSize` 仍然包括 `512`、`1K`、`2K` 和 `4K`。

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

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

![流程图展示 Gemini 图片 REST 请求、返回的内联图片数据，以及解码后写入文件的保存步骤。](https://www.aifreeapi.com/posts/zh/gemini-image-generation-rest-api/img/request-response-flow.png)

很多“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 文档](https://ai.google.dev/gemini-api/docs/openai) 仍然明确写着：

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

| 模型路线 | 当前角色 | 适合什么时候用 | 当前 caveat |
| --- | --- | --- | --- |
| `gemini-3.1-flash-image-preview` | 新 raw REST 的默认路线 | 多数当前图片生成和编辑场景 | 仍然是 preview |
| `gemini-3-pro-image-preview` | 更高质量的 premium 分支 | 文字较多、图形复杂、一次出错代价高的图片 | 更贵，而且仍然是 preview |
| `gemini-2.5-flash-image` | 旧但还在兼容示例里出现的路线 | 处理旧示例或特定兼容层迁移时 | Google 已给出 **2026 年 10 月 2 日** 的下线时间 |

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

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

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

![故障排查图，展示如何在 Gemini 图片 REST 工作流里区分 404、无效 payload、项目不匹配和缺少图片解码步骤。](https://www.aifreeapi.com/posts/zh/gemini-image-generation-rest-api/img/rest-error-triage-map.png)

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

| 你看到的现象 | 更常见的真实原因 | 下一步该做什么 |
| --- | --- | --- |
| `/v1beta/openai/images/generations` 返回 404 | 你走的是兼容层，而模型或请求形状更适合原生契约 | 先用原生 Gemini `generateContent` 重试同一任务 |
| 兼容层报 `Unknown name "generationConfig"` 或 `generation_config` | 你把原生 Gemini 字段塞到了 OpenAI 兼容契约里 | 要么切回原生，要么完整改成兼容层 schema |
| 旧图片模型返回 `model not found` | 你复制了过时模型 ID 或老帖子里的示例 | 先回到 models 和 deprecations 页面确认当前模型 |
| AI Studio 能跑，cURL 不行 | API key、project billing 或模型访问权限和浏览器里测试的上下文不一致 | 用同一项目和同一 key 回头核对 |
| 返回了 JSON 但没有图片文件 | 请求其实成功了，只是你还没做 `inlineData` 的解码 | 抽取 `.inlineData.data` 后再做 base64 解码 |

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

如果你的问题已经从 endpoint 选择进入了 429、400、500 的修复阶段，下一步更合适的是 [Gemini API 报错修复：429、400、500](/zh/posts/gemini-api-error-fix-2026-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 场景的默认起点。