# Gemini 이미지 생성 API Base URL: native Gemini와 OpenAI 호환 URL을 올바르게 고르는 법

> Gemini 이미지 생성에서 어떤 base URL을 써야 하는지 바로 정리합니다. 현재 native Gemini URL, OpenAI 호환 URL이 맞는 경우, 404와 무시되는 파라미터를 어떻게 구분할지까지 담았습니다.

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

**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](https://ai.google.dev/gemini-api/docs/image-generation), [API reference](https://ai.google.dev/api/generate-content), [OpenAI compatibility docs](https://ai.google.dev/gemini-api/docs/openai)는 각각 정답의 일부를 보여 주지만, “Gemini 이미지 생성에서 기본값으로 어떤 host를 써야 하는가”를 한 페이지에서 깔끔하게 말해 주지는 않습니다.

가장 안전한 순서는 단순합니다. 먼저 native `generateContent` 요청을 한 번 통과시켜 실제 이미지가 반환되는지 확인합니다. 그 다음에야 OpenAI 호환 레이어가 필요한지, 모델을 바꿔야 하는지, 혹은 실제 문제는 quota 쪽인지 판단하면 됩니다. 더 넓은 맥락이 필요하면 [Gemini 이미지 생성 튜토리얼](/ko/topics/nano-banana)과 [Gemini 이미지 생성 코드 예제](/ko/posts/gemini-image-generation-code-examples)를 이어서 보면 됩니다.

먼저 기억할 것:

- 새로운 Gemini image generation 작업은 `https://generativelanguage.googleapis.com/v1beta`에서 시작한다.
- 첫 전체 경로는 `/models/gemini-3.1-flash-image-preview:generateContent`를 우선 확인한다.
- `https://generativelanguage.googleapis.com/v1beta/openai/` 는 OpenAI 호환 client를 유지해야 할 때만 쓴다.

![Gemini 이미지 생성 API base URL 가이드. native Gemini 경로와 OpenAI 호환 URL을 비교한다.](https://www.aifreeapi.com/posts/ko/gemini-image-generation-api-base-url/img/cover.png)

## 핵심 요약

| 상황 | 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 이미지 endpoint 구조도. host, model path, generateContent 동작, 현재 Flash Image와 Pro 분기를 보여 준다.](https://www.aifreeapi.com/posts/ko/gemini-image-generation-api-base-url/img/native-route-anatomy.png)

Gemini 공식 API reference는 지금도 이미지 생성을 `generateContent` 안에서 설명합니다. 그래서 예전 스타일의 `/images/generations` endpoint를 기대하고 보면 native 답이 조금 낯설게 보일 수 있습니다. 하지만 Gemini native에서는 host는 일반 Gemini Developer API host이고, 이미지 생성 여부는 model path와 `generateContent` 조합으로 결정됩니다.

기본은 다음입니다.

```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`를 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/` 를 써야 하는 경우는 언제인가

![Decision board comparing Gemini-native image generation with the OpenAI-compatible route, showing when to stay native and when compatibility is the safer migration choice.](https://www.aifreeapi.com/posts/ko/gemini-image-generation-api-base-url/img/native-vs-openai-route.png)

OpenAI 호환 base URL은 실제로 존재하는 공식 경로입니다. Google은 지금도 다음 URL을 안내합니다.

```text
https://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, 이미지 반환이 통하는지 먼저 증명하면 됩니다.

```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, native image controls를 한 번에 검증하기 때문입니다. premium branch가 필요하다면 model path만 다음으로 바꾸면 됩니다.

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

이미지 안 텍스트 품질, 더 복잡한 구도, 더 비싼 asset에서 차이가 실제로 중요할 때만 이 경로가 더 낫습니다. 다음 관심사가 URL이 아니라 비용이면 [Gemini image generation API pricing](/ko/posts/gemini-image-generation-api-pricing)을 보는 편이 더 빠릅니다.

## Troubleshooting

![Troubleshooting map for Gemini image generation URL errors, showing the split between wrong host, unsupported compatibility behavior, model choice, and quota-project issues.](https://www.aifreeapi.com/posts/ko/gemini-image-generation-api-base-url/img/error-troubleshooting-map.png)

이미지 생성 실패를 전부 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](https://ai.google.dev/gemini-api/docs/rate-limits)는 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](/ko/posts/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](https://ai.google.dev/gemini-api/docs/billing)는 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는 다음입니다.

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

그리고 가장 먼저 시험할 path는 다음입니다.

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

다음 URL로 바꾸는 것은:

```text
https://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 표면을 유지해야 할 때만 꺼낸다.