# Gemini 图片生成 API Base URL：原生 Gemini 与 OpenAI 兼容地址怎么选

> 别再猜 Gemini 图片生成该用哪个 base URL。本文直接给出当前原生 Gemini 地址、OpenAI 兼容地址，以及 404、参数被忽略时该先排查什么。

- Source: https://www.aifreeapi.com/zh/posts/gemini-image-generation-api-base-url
- Language: zh
- Published: 2026-03-24
- Updated: 2026-03-24
- Publisher: AI Free API (https://www.aifreeapi.com)

**截至 2026 年 3 月 24 日，Gemini 原生图片生成该用的 base URL 是 `https://generativelanguage.googleapis.com/v1beta`，而大多数开发者第一条应该测试的完整路径，是 `POST /models/gemini-3.1-flash-image-preview:generateContent`。** 只有当你明确在沿用 OpenAI 兼容层时，才应该把 base URL 换成 `https://generativelanguage.googleapis.com/v1beta/openai/`。

这正是这个关键词真正要解决的问题。Google 当前的 [图片生成文档](https://ai.google.dev/gemini-api/docs/image-generation)、[API reference](https://ai.google.dev/api/generate-content) 和 [OpenAI compatibility 文档](https://ai.google.dev/gemini-api/docs/openai) 都各自提供了一部分答案，但没有哪一页会直接告诉你：做 Gemini 图片生成时，哪个 host 才是默认正确路线。

最稳的做法其实很简单。先用原生 `generateContent` 跑通一条最小请求，确认它真的返回图片，然后再决定自己是否需要 OpenAI 兼容层、是否该切模型、或问题是不是其实出在项目配额而不是 URL。若你后面还想补完整教程，可以继续看 [Gemini 图片生成教程：App、AI Studio 和 API](/zh/posts/gemini-image-generation-tutorial) 和 [Gemini 图片生成代码示例：JavaScript、Python 和 cURL](/zh/posts/gemini-image-generation-code-examples)。

快速结论：

- 新的 Gemini 图片生成工作，默认先从 `https://generativelanguage.googleapis.com/v1beta` 开始。
- 大多数开发者第一条应该测试的完整路径，是 `/models/gemini-3.1-flash-image-preview:generateContent`。
- 只有当你的工程明确建立在 OpenAI 兼容 client 之上时，才该改用 `https://generativelanguage.googleapis.com/v1beta/openai/`。

![Gemini 图片生成 API base URL 指南，对比原生 Gemini 路线与 OpenAI 兼容 URL](https://www.aifreeapi.com/posts/zh/gemini-image-generation-api-base-url/img/cover.png)

## 要点速览

| 你的情况 | Base URL | 第一条该想到的路径 | 适合什么时候用 | 主要 caveat |
| --- | --- | --- | --- | --- |
| 新的原生 Gemini 图片生成 | `https://generativelanguage.googleapis.com/v1beta` | `/models/gemini-3.1-flash-image-preview:generateContent` | 你要的是当前最清晰的 Gemini 图片 API 契约与原生图片控制 | 图片生成仍然挂在 `generateContent` 下面，不是独立 `/images` host |
| 已经在用 OpenAI SDK 或 OpenAI 风格工具链 | `https://generativelanguage.googleapis.com/v1beta/openai/` | OpenAI 风格 client 的 `images.generate()` 等方法 | 你要尽量少改现有 OpenAI client 结构 | 兼容层的图片能力更窄，额外参数可能被静默忽略 |
| AI Studio 或 Gemini App 能用，但代码报错 | 往往不是 base URL 本身的问题 | 先检查项目、key、模型和配额 | 你是把 UI 体验直接映射成 API 契约 | App、AI Studio、API 并不完全等价 |
| 实际跑在 Vertex AI 上 | 不要默认用 Gemini Developer API host | 改查 Vertex AI 自己的 endpoint family | 你的项目绑定的是 Vertex AI | 即使模型没错，host 用错也会白白浪费排查时间 |

如果你只记一条规则，就记这一条：**新的 Gemini 图片生成，默认先走原生 Gemini Developer API，不要先走 OpenAI 兼容 host。**

真正实操时，还可以再补一条判断顺序：先证明 host 和 model path 没问题，再去看图片尺寸、长宽比、编辑能力、计费和配额。把这些层级拆开之后，很多原本看起来像“base URL 有坑”的问题，会一下子变成可以直接定位的小问题。

## 原生 Gemini 图片生成应该用这个 base URL

![原生 Gemini 图片 endpoint 结构图，展示 host、model path、generateContent 动作，以及当前 Flash Image 与 Pro 的分流。](https://www.aifreeapi.com/posts/zh/gemini-image-generation-api-base-url/img/native-route-anatomy.png)

官方 Gemini API reference 现在依然把图片生成放在 `generateContent` 这条主方法族下面，而不是单独拆出一个“只管图片”的 host。也正因为如此，很多人第一次看到原生路线时会觉得路径有点奇怪，因为它不像一些旧式图片 API 那样直接写成 `/images/generations`。

原生路线真正该记住的是这两层：

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

以及大多数开发者第一条应该测试的完整图片生成路径：

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

Google 当前的图片文档仍然把 `gemini-3.1-flash-image-preview` 放在默认快车道位置，把 `gemini-3-pro-image-preview` 放在更贵、更高价值的分支。这也是为什么这篇文章不会让你从旧的 2.5 时代图片示例开始。对新集成来说，最值得问的问题不是“最老还能跑的是什么”，而是“Google 当前最明确在教哪条原生路径”。

原生路线还有一个实用优势，就是图片能力本身讲得更清楚。`imageSize`、`aspectRatio`、图像编辑、多轮迭代，这些真正会影响图片行为的东西，都是在原生文档里更容易看懂。你如果关心的是 Gemini 现在如何做图片，而不只是“有没有一个能兼容 OpenAI 的入口”，那原生 host 才是更稳的默认答案。

调试时还有个容易忽略的小点：Google 官方示例既允许你把 key 放在 `?key=` 里，也允许走 `x-goog-api-key` header。它们都不改变真正的 endpoint 契约，但能帮助你把“认证写法问题”和“host/path 选错”拆开看，少走很多弯路。

## 什么时候 `/v1beta/openai/` 才是对的

![对比决策图：左侧是原生 Gemini 图片生成，右侧是 OpenAI 兼容路线，说明什么情况下应该继续走原生，什么情况下兼容层更适合迁移。](https://www.aifreeapi.com/posts/zh/gemini-image-generation-api-base-url/img/native-vs-openai-route.png)

OpenAI 兼容 base URL 当然是真实存在的，不是过时文档，也不是 bug。Google 当前的兼容文档仍然告诉 OpenAI library 用户可以把 base URL 指向：

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

这个地址适合什么场景？答案并不复杂：你已经有一套 OpenAI 风格的 client、wrapper 或内部工具，希望尽量少改调用面。在这种情况下，用兼容层是合理的。

真正不合理的是，把这条 host 当成所有 Gemini 图片 API 问题的默认答案。Google 自己的兼容文档也写得很清楚：如果你并不是已经在使用 OpenAI libraries，那么更推荐你直接调用 Gemini API。本题里这点尤其重要，因为图片生成并不是“换个 host 就完全一样”。当前兼容文档里，图片生成主要是围绕 `gemini-2.5-flash-image` 和 `gemini-3-pro-image-preview` 展开的，而且文档还提醒你，未列出的额外参数可能被静默忽略。

这就是很多人被带偏的地方。host 没错，不代表它就是你当前任务最好的默认路线。如果你需要的是原生图片控制、想直接跟当前 Gemini 图片文档对齐，或者你一开始就在调 raw REST，那么原生 `generateContent` 更适合。

实操上可以这样判断：

- 你是新项目、自己调 raw REST、或者按当前 Gemini 图片文档学习：走原生 Gemini。
- 你已经有 OpenAI 风格 client，希望最小改动完成迁移：再考虑 OpenAI 兼容层。
- 不要在同一轮排查里来回混用两条 host，除非你非常清楚自己在比较什么。

## 先复制一个能跑通的 REST 请求

一开始不要急着做复杂工作流。先证明原生 host、模型路径和图片返回都是通的，再去谈优化。最小请求可以先长这样：

```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 hero image of a matte black travel mug on a light concrete surface with soft studio lighting."
        }
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "16:9",
        "imageSize": "2K"
      }
    }
  }'
```

这条请求的价值就在于它同时验证了三件事：host 是对的、model 是对的、原生图片控制字段也真的生效。如果你后续确实要走更高成本分支，再把 model path 改成：

```text
/models/gemini-3-pro-image-preview:generateContent
```

只有当图片内文字质量、更复杂的构图、或高价值产出真的会改变结果时，这条 Pro 分支才更值。如果你下一步真正关心的是成本而不是 URL，直接去看 [Gemini 图片生成价格指南](/zh/posts/gemini-image-generation-api-pricing) 会更合适。

## 故障排查

别把所有错误都怪到 base URL 上。真正高频的失误往往是把兼容层和原生层混着试、把 UI 体验当成 API 契约，或者还没确认项目配额就开始来回换 endpoint。

![Gemini 图片生成 URL 报错排查图，展示错误 host、兼容层能力不匹配、模型选择与项目配额之间的分流关系。](https://www.aifreeapi.com/posts/zh/gemini-image-generation-api-base-url/img/error-troubleshooting-map.png)

base URL 确实经常被用错，但它不是所有报错的根源。当前 Gemini 图片相关 forum 线程里，最常见的情况其实是：开发者看到 404、model not found、参数没生效，就立刻怀疑整个 host 错了。很多时候，真正的问题更具体。

| 你看到的现象 | 更常见的真实原因 | 下一步应该做什么 |
| --- | --- | --- |
| OpenAI 兼容图片路径上报 404 或 model not found | 你把原本更适合原生 `generateContent` 的模型或行为放进了兼容层 endpoint family | 先用原生 Gemini host 复现同一任务 |
| `imageSize`、`aspectRatio` 这类参数像是被忽略 | 你走的是兼容层，而这些能力不在它当前明确支持的图片参数集合里 | 如果这些控制真的重要，就改回原生 Gemini API |
| AI Studio 或 Gemini App 里能用，代码里不行 | UI 行为和 API 项目行为并不完全等价 | 先确认 API key、项目、模型可用性，而不是直接改 host |
| URL 修正后又遇到 429 或配额问题 | host 是对的，但当前项目配额、preview model 限制或 tier 还在挡你 | 去看项目级配额，而不是继续改 endpoint |
| 一切看起来都差不多，但请求表现始终不稳定 | 你可能把旧 2.5 示例、原生 Gemini 文档和 OpenAI 兼容假设混在了一次排查里 | 固定一条路线、一个模型、一种请求形状，先跑通再说 |

这里最容易被忽视的，其实是配额。Google 当前的 [rate limits 文档](https://ai.google.dev/gemini-api/docs/rate-limits) 明确说配额按项目而不是按 API key 计算，而且 requests per day 会在 Pacific time 的午夜重置。文档同样提醒：preview models 的限制更紧。这意味着 URL 正确，也一样可能失败，尤其是你还没确认项目上下文的时候。

第二个容易误判的是兼容层行为。Google forum 已经出现过多条图片生成相关讨论：同一个开发者在 OpenAI 兼容图片请求里撞上 404，但换到原生 `generateContent` 后又能跑通。这不等于兼容文档是错的，而是说明最稳的排查顺序应该是：先证明原生路线，再把兼容层当作迁移层来用，而不是一开始就把它当成所有图片场景的默认答案。

如果你的问题已经不再是 URL，而是 429、400、500 这类更底层的报错，可以直接去看 [Gemini API 报错修复：429、400、500](/zh/posts/gemini-api-error-fix-2026-429-400-500)。

更稳的排查动作可以固定成一套顺序：先锁定一条原生请求，确认能回图；再确认项目、模型和配额；最后才去比较兼容层是否值得保留。顺序一旦反过来，排查时间通常会被“看起来都像 URL 问题”的假象拖得很长。

## 发请求前先确认这四件事

如果你想让团队里的排查成本明显下降，最好在第一条请求发出去之前，就把几个容易混淆的前提锁死。很多“地址到底对不对”的争论，其实不是技术难题，而是不同人拿着不同 host、不同 model、不同项目上下文在比较结果。

第一，确认你到底在调 **Gemini Developer API** 还是 **Vertex AI**。这一步听起来很基础，但它会直接决定 host family。只要产品边界没有先说清楚，后面的 404、权限错误和 model not found 都会被放大成“是不是 base URL 全错了”。

第二，第一轮验证时只保留一套最小变量：一个 host、一个 model、一个认证写法。不要一边试 `?key=`，一边又换 `x-goog-api-key`，再同时切 OpenAI 兼容层和原生层。变量一多，日志看起来会更丰富，但结论反而更不可靠。

第三，把你已经验证过的完整 endpoint 直接写进项目文档或环境说明。很多团队并不是不会调 API，而是有人从旧 issue、旧示例、旧聊天记录里复制了过时路径，导致同一个问题每隔几周又重新出现一次。

第四，只有在原生请求已经稳定回图之后，才把 SDK wrapper、代理层、兼容层、重试逻辑一层层加回去。这样做的好处是，每多一层你都知道问题是从哪一层开始出现的，而不是把所有失败都模糊地归到 URL 身上。

## 不要把 Gemini Developer API、AI Studio 和 App 混为一谈

这个关键词之所以容易乱，就是因为 Google 把几个相关但不同的产品一起放在了搜索结果里。

**Gemini Developer API** 才是 `generativelanguage.googleapis.com` 这个 host 所属的产品契约。本文回答的就是这件事。

**AI Studio** 是贴近这个 API 的一个 UI 和项目入口，但它并不会把问题自动简化成“抄浏览器里看到的行为就行”。项目计费、模型可用性、API key 归属，仍然会改变结果。Google 当前的 [billing FAQ](https://ai.google.dev/gemini-api/docs/billing) 说 AI Studio 在用户链接付费 API key 之前仍然可以免费使用部分功能，但这并不会改变原生 Gemini 图片请求该使用哪个 host。

**Gemini App** 距离 base URL 问题更远。它对于人工出图或编辑当然有帮助，但 App 体验不是你代码里真正要调用的 API 契约。也正因为这样，Gemini App 的帮助页面适合帮助你理解产品边界，却不能替代本文要回答的 endpoint 问题。

如果你其实跑在 **Vertex AI**，那就先确认这一点。Vertex AI 有自己的 endpoint family，把 Gemini Developer API 的 host 直接搬过去，只会让排查方向从一开始就错掉。

## 结论

如果你做的是当前 Gemini Developer API 下的图片生成，默认应该使用：

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

并优先从这条路径开始测试：

```text
/models/gemini-3.1-flash-image-preview:generateContent
```

只有在你的工程明确要保留 OpenAI 兼容调用面时，才切到：

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

这是当前最稳的默认答案，因为它和官方原生 Gemini 图片文档一致，也最能避开这个关键词背后最常见的误区：把 OpenAI 兼容 host 误当成所有 Gemini 图片请求的通用默认地址。

如果你团队里会有人继续追问“那我到底先贴哪条 URL 到代码里”，就把答案简化成两步：先贴原生 `https://generativelanguage.googleapis.com/v1beta`，再把模型路径补成 `gemini-3.1-flash-image-preview:generateContent`。只有在代码栈本身已经绑定 OpenAI 兼容语义时，才讨论 `/v1beta/openai/`。