2026년 3월 24일 기준 Gemini 이미지 생성의 올바른 native base URL은 https://generativelanguage.googleapis.com/v1beta이고, 대부분의 개발자가 가장 먼저 확인해야 할 경로는 POST /models/gemini-3.1-flash-image-preview:generateContent입니다. https://generativelanguage.googleapis.com/v1beta/openai/ 는 OpenAI 호환 레이어를 의도적으로 유지할 때만 쓰는 편이 맞습니다.
이 검색어의 핵심도 바로 여기 있습니다. Google의 image generation docs, API reference, OpenAI compatibility docs는 각각 정답의 일부를 보여 주지만, “Gemini 이미지 생성에서 기본값으로 어떤 host를 써야 하는가”를 한 페이지에서 깔끔하게 말해 주지는 않습니다.
가장 안전한 순서는 단순합니다. 먼저 native generateContent 요청을 한 번 통과시켜 실제 이미지가 반환되는지 확인합니다. 그 다음에야 OpenAI 호환 레이어가 필요한지, 모델을 바꿔야 하는지, 혹은 실제 문제는 quota 쪽인지 판단하면 됩니다. 더 넓은 맥락이 필요하면 Gemini 이미지 생성 튜토리얼과 Gemini 이미지 생성 코드 예제를 이어서 보면 됩니다.
먼저 기억할 것:
- 새로운 Gemini image generation 작업은
https://generativelanguage.googleapis.com/v1beta에서 시작한다. - 첫 전체 경로는
/models/gemini-3.1-flash-image-preview:generateContent를 우선 확인한다. https://generativelanguage.googleapis.com/v1beta/openai/는 OpenAI 호환 client를 유지해야 할 때만 쓴다.
핵심 요약
| 상황 | Base URL | 먼저 떠올려야 할 경로 | 언제 쓰나 | 핵심 caveat |
|---|---|---|---|---|
| 새로운 native Gemini 이미지 생성 | https://generativelanguage.googleapis.com/v1beta | /models/gemini-3.1-flash-image-preview:generateContent | 현재 Gemini 이미지 API를 가장 직접적으로 쓰고 싶을 때 | image generation은 전용 /images host가 아니라 generateContent 아래에 있다 |
| 이미 OpenAI SDK / OpenAI 스타일 도구를 쓰는 경우 | https://generativelanguage.googleapis.com/v1beta/openai/ | images.generate() 같은 호환 메서드 | 기존 OpenAI client 표면을 최대한 유지하고 싶을 때 | 이미지 기능 표면이 더 좁고 일부 추가 파라미터는 무시될 수 있다 |
| AI Studio나 앱은 되는데 코드만 실패 | base URL 자체가 문제는 아닐 수 있다 | project, key, model, quota를 먼저 본다 | UI 동작을 API 계약으로 착각한 경우 | App, AI Studio, API는 같은 것이 아니다 |
| 실제로는 Vertex AI 위에서 동작 | Gemini Developer API host를 기본으로 가정하지 않는다 | Vertex AI endpoint family를 확인한다 | 프로젝트가 Vertex AI 기반일 때 | host를 틀리면 모델이 맞아도 헛디버깅이 된다 |
한 줄 규칙으로 줄이면 이겁니다. 새로운 Gemini 이미지 생성은 native Gemini부터 시작하는 것이 기본값입니다.
실무에서는 여기에 한 단계만 더 붙이면 됩니다. 먼저 host와 model path를 고정하고, 그 다음에 image controls, quota, compatibility 필요 여부를 따로 본다. 이 순서를 지키면 “전부 base URL 문제처럼 보이는” 상황을 훨씬 빨리 걷어낼 수 있습니다.
native Gemini 이미지 생성에는 이 base URL을 쓴다
Gemini 공식 API reference는 지금도 이미지 생성을 generateContent 안에서 설명합니다. 그래서 예전 스타일의 /images/generations endpoint를 기대하고 보면 native 답이 조금 낯설게 보일 수 있습니다. 하지만 Gemini native에서는 host는 일반 Gemini Developer API host이고, 이미지 생성 여부는 model path와 generateContent 조합으로 결정됩니다.
기본은 다음입니다.
texthttps://generativelanguage.googleapis.com/v1beta
그리고 대부분이 가장 먼저 시험해야 할 전체 경로는 다음입니다.
texthttps://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent
현재 Google 문서는 gemini-3.1-flash-image-preview를 fast default로, gemini-3-pro-image-preview를 premium branch로 두고 있습니다. 그래서 이 글도 오래된 2.5 시절 예제부터 시작하지 않습니다. 새 통합에서 중요한 질문은 “무엇이 아직 살아 있나”가 아니라 “Google이 지금 무엇을 current path로 가르치고 있나”입니다.
또 하나 중요한 것은 feature surface입니다. imageSize, aspectRatio, 이미지 편집, multi-turn 같은 image-native 제어는 native route에서 훨씬 이해하기 쉽습니다. 현재 Gemini 이미지 기능을 그대로 쓰고 싶다면 native host를 기준으로 생각하는 쪽이 덜 헷갈립니다.
운영 관점에서도 native 쪽이 더 단순합니다. 공식 예시는 ?key= 방식과 x-goog-api-key header 방식을 모두 보여 주기 때문에, 인증 처리 문제와 endpoint 선택 문제를 분리해서 볼 수 있습니다. 인증 방식이 달라도 기본 contract는 같다는 점이 디버깅에 도움이 됩니다.
/v1beta/openai/ 를 써야 하는 경우는 언제인가
OpenAI 호환 base URL은 실제로 존재하는 공식 경로입니다. Google은 지금도 다음 URL을 안내합니다.
texthttps://generativelanguage.googleapis.com/v1beta/openai/
언제 이 답이 맞을까요? 이미 OpenAI 스타일 SDK, wrapper, 내부 도구를 갖고 있고 client surface를 크게 바꾸고 싶지 않을 때입니다. 그런 전제가 있다면 호환 레이어를 쓰는 것이 합리적입니다.
하지만 그 URL을 Gemini 이미지 생성 전반의 default answer로 취급하는 것은 위험합니다. Google 자체도 OpenAI libraries를 이미 쓰고 있는 게 아니라면 Gemini API를 직접 호출하는 편을 권합니다. 이미지에서는 이 차이가 특히 큽니다. 현재 호환 문서는 이미지 쪽을 주로 gemini-2.5-flash-image와 gemini-3-pro-image-preview 중심으로 설명하고, 문서에 없는 추가 파라미터는 조용히 무시될 수 있다고 적고 있습니다.
혼란은 여기서 시작됩니다. 호환 URL이 valid하다는 것과, 그 URL이 지금 당신에게 가장 좋은 default라는 것은 다릅니다. native image controls가 필요하거나 current Gemini docs의 흐름을 그대로 따라가고 싶다면, 먼저 native route를 택하는 것이 안전합니다.
판단을 단순화하면 이렇습니다.
- 새 구현, raw REST 디버깅, 현재 Gemini docs 기준이면 native.
- OpenAI 기반 stack을 의도적으로 유지해야 하면 compatibility.
- 두 경로를 같은 디버깅 라운드에서 섞지 않는다.
먼저 동작하는 REST request 하나를 복사한다
처음부터 복잡한 workflow를 만들지 마세요. host, model, 이미지 반환이 통하는지 먼저 증명하면 됩니다.
bashcurl -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, native image controls를 한 번에 검증하기 때문입니다. premium branch가 필요하다면 model path만 다음으로 바꾸면 됩니다.
text/models/gemini-3-pro-image-preview:generateContent
이미지 안 텍스트 품질, 더 복잡한 구도, 더 비싼 asset에서 차이가 실제로 중요할 때만 이 경로가 더 낫습니다. 다음 관심사가 URL이 아니라 비용이면 Gemini image generation API pricing을 보는 편이 더 빠릅니다.
Troubleshooting
이미지 생성 실패를 전부 base URL 탓으로 돌리면 안 됩니다. 최근 forum thread를 보면, 404, model not found, ignored parameters가 뜨는 순간 host 전체가 틀렸다고 보는 경우가 많지만 실제 원인은 훨씬 더 구체적인 경우가 많습니다.
| 보이는 현상 | 흔한 실제 원인 | 다음 행동 |
|---|---|---|
| OpenAI-compatible image path에서 404 / model not found | native generateContent 쪽이 더 맞는 모델이나 동작을 compatibility path에 넣고 있다 | 같은 작업을 native Gemini host에서 다시 확인한다 |
imageSize나 aspectRatio가 먹지 않는 것처럼 보인다 | compatibility layer에서 기대한 image controls가 documented surface 밖에 있다 | 그 제어가 중요하면 native Gemini API로 돌아간다 |
| AI Studio나 앱은 되는데 코드만 실패한다 | UI 동작과 API project 동작이 같지 않다 | host를 바꾸기 전에 API key, project, model availability를 확인한다 |
| URL을 바로잡은 뒤 429가 나온다 | host는 맞지만 quota나 project tier가 병목이다 | project 단위 limit를 확인한다 |
| 모든 것이 조금씩 어긋난다 | 2.5 시대 예제, native docs, OpenAI 호환 가정을 한 세션에 섞고 있다 | 한 route, 한 model, 한 request shape로 고정한다 |
가장 자주 놓치는 것은 quota입니다. Google의 rate limits docs는 limit가 API key가 아니라 project 기준으로 적용되고, requests per day가 Pacific time 기준 자정에 reset되며, preview models 제한이 더 빡빡하다고 분명히 적고 있습니다. 즉 URL이 맞아도 project 조건 때문에 실패할 수 있습니다.
또 다른 함정은 compatibility behavior입니다. Google forum에는 OpenAI-compatible image request에서는 404가 나지만 native generateContent로 옮기면 동작하는 사례가 있습니다. 여기서 배워야 할 것은 “compat docs가 틀렸다”가 아니라 “먼저 native route를 증명하고, compatibility는 migration layer로 취급하는 편이 안전하다”는 순서입니다.
문제가 이미 URL을 넘어 429, 400, 500 대응 단계라면 Gemini API error fix 2026: 429, 400, 500로 넘어가는 편이 더 낫습니다.
첫 request 전에 확인할 것
팀 안에서 같은 혼선을 반복하지 않으려면 첫 image request 전에 전제를 몇 가지 고정해 두는 편이 좋습니다. base URL 혼란은 문서가 없어서라기보다, 서로 다른 host, 다른 model, 다른 project context를 한 번에 비교하면서 커지는 경우가 많습니다.
먼저 Gemini Developer API 와 Vertex AI 를 분리해서 생각해야 합니다. 이 구분이 흐리면 404나 model not found가 모두 “host가 틀린 것 같다”는 이야기로 흘러가기 쉽습니다. 그 다음 첫 검증에서는 host 하나, model 하나, 인증 방식 하나만 남기세요. ?key= 와 x-goog-api-key 를 동시에 바꾸거나, native와 compatibility를 같은 라운드에서 오가면 로그는 많아져도 결론은 흐려집니다.
한 번 통과한 전체 endpoint는 그대로 문서나 runbook에 남겨 두는 것이 좋습니다. 실제로 많은 팀이 시간을 잃는 이유는 어려운 새 문제 때문이 아니라, 누군가 오래된 예제나 예전 이슈의 path를 다시 가져와 검증된 경로가 팀 안에 고정되어 있지 않기 때문입니다.
마지막으로 proxy, SDK wrapper, retry, compatibility abstraction은 native request가 안정적으로 이미지를 돌려준 뒤에 차례대로 얹는 편이 안전합니다. 이렇게 하면 어느 층에서 문제가 들어왔는지 바로 볼 수 있고, 모든 실패를 막연하게 URL 탓으로 돌리는 일을 줄일 수 있습니다.
핵심은 검증 순서를 팀 전체가 같은 방식으로 유지하는 것입니다. 순서만 고정돼도 같은 실수를 반복해서 다시 추적하는 비용이 크게 줄어듭니다.
Gemini Developer API, AI Studio, App를 같은 것으로 보지 말 것
이 keyword가 헷갈리는 이유는 Google이 서로 관련 있지만 같은 것은 아닌 product를 같은 검색 결과에 보여 주기 때문입니다.
Gemini Developer API 가 generativelanguage.googleapis.com host의 본체입니다. 이 글이 답하는 contract도 바로 이것입니다.
AI Studio 는 API에 가까운 UI / project surface이지만, 거기 보이는 동작을 그대로 API contract라고 생각하면 안 됩니다. billing, project, model availability는 여전히 별개의 문제입니다. Google의 billing FAQ는 paid API key를 연결하기 전까지 무료 사용이 남아 있다고 설명하지만, 그렇다고 native 이미지 요청에 써야 할 host 자체가 바뀌는 것은 아닙니다.
Gemini app 은 base URL 질문에서 더 멀리 있습니다. 수동 이미지 생성에는 유용하지만, 앱의 동작이 곧 코드가 호출할 API contract는 아닙니다. product boundary를 이해하는 데는 도움이 되지만 endpoint 정답을 대신하지는 못합니다.
실제로 Vertex AI 위에서 동작 중이라면 그 점부터 분리해야 합니다. Vertex AI에는 자체 endpoint family가 있고, Gemini Developer API host를 그대로 들고 가면 처음부터 디버깅 레이어를 잘못 잡게 됩니다.
결론
현재 Gemini Developer API에서 이미지 생성을 한다면 default answer는 다음입니다.
texthttps://generativelanguage.googleapis.com/v1beta
그리고 가장 먼저 시험할 path는 다음입니다.
text/models/gemini-3.1-flash-image-preview:generateContent
다음 URL로 바꾸는 것은:
texthttps://generativelanguage.googleapis.com/v1beta/openai/
를 정말로 필요로 하는 OpenAI-compatible stack일 때뿐입니다.
이 순서가 가장 안전한 이유는 현재 native Gemini docs와 맞고, 이미지 기능의 contract를 가장 분명하게 유지하며, 이 검색어 뒤에 숨어 있는 가장 흔한 실수, 즉 OpenAI 호환 host를 Gemini 이미지 요청 전체의 universal default로 착각하는 문제를 막아 주기 때문입니다.
팀 안에서 아주 짧게 정리해야 한다면 이렇게 말하면 됩니다. 먼저 native host https://generativelanguage.googleapis.com/v1beta를 쓰고, 첫 검증은 gemini-3.1-flash-image-preview:generateContent로 한다. /v1beta/openai/는 OpenAI 호환 client 표면을 유지해야 할 때만 꺼낸다.