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

截至 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 当前的 图片生成文档、API reference 和 OpenAI compatibility 文档 都各自提供了一部分答案，但没有哪一页会直接告诉你：做 Gemini 图片生成时，哪个 host 才是默认正确路线。

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

快速结论：

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

要点速览

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

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

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

官方 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/ 才是对的

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 图片生成价格指南 会更合适。

故障排查

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

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

这里最容易被忽视的，其实是配额。Google 当前的 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。

更稳的排查动作可以固定成一套顺序：先锁定一条原生请求，确认能回图；再确认项目、模型和配额；最后才去比较兼容层是否值得保留。顺序一旦反过来，排查时间通常会被“看起来都像 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 说 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/。