# Gemini 이미지 생성 REST API: 지금 바로 쓰는 cURL 가이드

> Gemini 이미지 생성 REST API를 현재 기준으로 가장 안전하게 호출하는 방법을 정리했습니다. 먼저 native Gemini cURL을 통과시키고, 반환 이미지를 저장한 뒤, 그 다음에 OpenAI 호환 경로를 검토하세요.

- Source: https://www.aifreeapi.com/ko/posts/gemini-image-generation-rest-api
- Language: ko
- 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 이미지 생성을 raw 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)는 native Gemini 흐름을 설명하고, [API reference](https://ai.google.dev/api/generate-content)는 `generateContent` 와 `imageConfig` 계약을 정의하며, [OpenAI compatibility 문서](https://ai.google.dev/gemini-api/docs/openai)는 별도의 호환 endpoint family를 설명합니다. 이 셋을 같이 보면 다 비슷한 첫 선택지처럼 보이지만, 새 raw REST 구현에서는 그렇지 않습니다.

위에서 한 가지 더 고정해 둘 전제가 있습니다. 현재 Gemini 3 이미지 모델은 아직 preview 성격이고, 이미지 모델 추천 경로도 최근 몇 달 사이에 빠르게 바뀌었습니다. 공식 OpenAI 호환 이미지 예제에는 여전히 `gemini-2.5-flash-image` 가 나오지만, native Gemini 최신 이미지 문서는 이미 `gemini-3.1-flash-image-preview` 와 `gemini-3-pro-image-preview` 를 중심으로 설명합니다. 이 차이를 먼저 분리하지 않으면 URL 문제와 모델 문제를 한데 섞어 버리기 쉽습니다.

![Gemini 이미지 생성 REST API 가이드. native generateContent 경로, 현재 모델 선택, cURL 워크플로를 보여 준다.](https://www.aifreeapi.com/posts/ko/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` | 현재 native Gemini 이미지 문서와 가장 잘 맞고 `imageConfig` 를 직접 쓸 수 있다 | Gemini 3 이미지 모델은 아직 preview |
| 텍스트가 많은 이미지나 고가치 비주얼 | 같은 native `generateContent` | `gemini-3-pro-image-preview` | premium branch로 가야 할 이유가 분명할 때 적합하다 | 더 비싸고 역시 preview |
| 기존 OpenAI 스타일 client를 유지해야 함 | `POST /v1beta/openai/images/generations` | 호환 문서가 현재 지원하는 surface 기준 | 클라이언트 변경을 최소화할 수 있다 | native Gemini 기본 경로가 아니라 별도 계약이다 |
| AI Studio는 되는데 cURL은 실패함 | URL만의 문제는 아닌 경우가 많다 | 같은 project와 model을 먼저 확인 | billing, tier, access 차이가 더 자주 원인이다 | 모든 사용자에게 동일한 고정 limit 표는 없다 |

host와 path 분기만 빠르게 정리하고 싶다면 [Gemini 이미지 생성 API Base URL](/ko/posts/gemini-image-generation-api-base-url) 부터 보면 됩니다. SDK 예제까지 함께 보려면 [Gemini 이미지 생성 코드 예제](/ko/posts/gemini-image-generation-code-examples) 가 다음 단계에 더 잘 맞습니다.

## 먼저 native Gemini REST 경로를 쓴다

![native Gemini generateContent 스택을 기본 REST 경로로 보여 주고, 모델 선택과 호환 경로 맥락은 보조적으로 배치한 라우팅 보드.](https://www.aifreeapi.com/posts/ko/gemini-image-generation-rest-api/img/native-route-stack.png)

새로운 REST 구현에서는 이 한 가지 생각부터 고정하면 훨씬 쉬워집니다. **Gemini 이미지 생성은 독립된 이미지 host를 찾는 일이 아니라, 이미지를 반환하는 native Gemini API request를 정확히 쓰는 일** 입니다. 현재 API reference도 이미지를 여전히 `generateContent` 안에서 정의하고 있고, 이미지 생성 가이드 역시 같은 method family 위에서 설명합니다.

raw REST에서 처음 확인하고 싶은 것은 보통 세 가지입니다.

- 지금 맞는 host와 model path가 무엇인가
- 이미지에 영향을 주는 설정은 어디에 놓는가
- SDK 없이 본 실제 response shape는 어떻게 생겼는가

native route는 이 세 가지를 가장 곧바로 보여 줍니다. host가 명확하고, 문서도 가장 최신이며, `imageConfig` 를 그대로 request에 넣을 수 있습니다. cURL 디버깅, 자체 wrapper, SDK 없이 시작하는 환경에서는 이 경로가 가장 덜 헷갈립니다.

실무상 starting model은 `gemini-3.1-flash-image-preview` 입니다. Google의 [models 페이지](https://ai.google.dev/gemini-api/docs/models)는 이를 현재 고효율 이미지 라인으로 보여 주고, `gemini-3-pro-image-preview` 는 premium branch로 둡니다. 예전 라인인 `gemini-2.5-flash-image` 도 아직 보이지만, Google의 [deprecations 페이지](https://ai.google.dev/gemini-api/docs/deprecations)는 이미 **2026년 10월 2일** shutdown date를 적어 두고 있고, 대체 경로로 `gemini-3.1-flash-image-preview` 를 권합니다.

## 동작하는 cURL request를 먼저 하나 복사한다

처음부터 복잡한 workflow를 만들 필요는 없습니다. 먼저 증명해야 하는 것은 host, model, image output 입니다. 첫 request는 단순하면 충분합니다. prompt 하나, current model 하나, 이미지 출력 하나, 명시적인 `aspectRatio` 와 `imageSize` 정도면 충분합니다.

```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"
      }
    }
  }'
```

이 request는 native path, current model, image controls를 한 번에 검증합니다. 현재 [API reference](https://ai.google.dev/api/generate-content)에 따르면 `imageConfig.imageSize` 는 `512`, `1K`, `2K`, `4K` 를 쓸 수 있습니다. 그래서 이미지 제어가 중요할수록 호환 레이어보다 native route가 더 이해하기 쉽습니다.

텍스트가 많은 포스터나 더 비싼 결과물이 필요한 경우라면 model path만 `gemini-3-pro-image-preview` 로 바꾸면 됩니다. 다음 관심사가 REST 모양이 아니라 비용이라면 [Gemini image generation API pricing](/ko/posts/gemini-image-generation-api-pricing) 이 더 직접적입니다.

## REST 응답에서 이미지를 실제 파일로 저장한다

![Gemini 이미지 REST 요청, 반환되는 inline image data, 그리고 파일로 저장하는 decode 단계까지 보여 주는 흐름도.](https://www.aifreeapi.com/posts/ko/gemini-image-generation-rest-api/img/request-response-flow.png)

많은 REST 문서는 요청을 보내는 단계까지만 보여 주지만, raw REST에서 실제로 많이 막히는 지점은 그 다음입니다. **native Gemini 응답은 완성된 파일 경로를 주는 것이 아니라, 이미지 바이트를 `inlineData` 로 JSON 안에 담아 돌려줍니다.**

그래서 첫 시도에서 “JSON만 돌아왔으니 실패했다”고 오해하기 쉽습니다. 대부분은 실패가 아니라, 마지막 decode와 저장이 아직 끝나지 않은 상태입니다.

native route에서는 보통 이렇게 처리합니다.

1. `candidates[0].content.parts` 를 읽는다
2. `inlineData` 가 있는 part를 찾는다
3. `.inlineData.data` 를 꺼낸다
4. base64 decode 후 파일로 저장한다

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 -D` 를 써야 할 수도 있습니다. 핵심은 shell 옵션이 아니라, **성공한 native response도 마지막에 decode-to-file 단계가 필요하다** 는 점입니다.

## OpenAI 호환 이미지 경로가 맞는 경우

OpenAI 호환 경로는 실제로 존재하고, 분명한 용도도 있습니다. Google의 현재 [compatibility 문서](https://ai.google.dev/gemini-api/docs/openai)는 다음 URL을 유지하고 있습니다.

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

이미지 endpoint는:

```text
/v1beta/openai/images/generations
```

기존 OpenAI 스타일 client를 크게 바꾸고 싶지 않다면 이 경로는 합리적입니다. migration cost를 낮추는 것이 목적이라면 맞는 선택일 수 있습니다.

하지만 이것이 “gemini image generation rest api” 검색의 기본 답은 아닙니다. 이 검색에서 보통 필요한 것은 **현재 native Gemini REST 계약** 이지, OpenAI 스타일 client를 유지하기 위한 최소 수정 경로가 아니기 때문입니다.

차이는 docs와 community friction 모두에서 드러납니다. **2026년 3월 27일 기준** 공식 호환 이미지 예제는 아직 `gemini-2.5-flash-image` 를 쓰지만, native Gemini 이미지 문서는 Gemini 3 이미지 모델을 중심으로 설명합니다. forum에서도 native image 설정을 compatibility path에 밀어 넣다가 404나 invalid payload를 맞는 사례가 보입니다.

실무 규칙은 짧게 정리하면 충분합니다.

- 새 프로젝트, cURL, raw REST, 현재 문서 기준이면 native Gemini
- 기존 OpenAI 스타일 stack 유지가 핵심이면 compatibility route
- 첫 디버깅 세션에서 두 계약을 섞지 않는다

## 모델, 비용, 상태 때문에 구현 선택이 달라지는 부분

REST syntax가 맞는다고 해서 implementation choice까지 자동으로 맞는 것은 아닙니다. model lane, preview status, billing, limits가 실제 결정을 바꿉니다.

| 모델 | 현재 역할 | 언제 쓰는가 | caveat |
| --- | --- | --- | --- |
| `gemini-3.1-flash-image-preview` | 새 raw REST의 기본값 | 대부분의 현재 이미지 생성/편집 | 아직 preview |
| `gemini-3-pro-image-preview` | premium branch | 레이아웃, 글자 표현, 고가치 비주얼이 중요할 때 | 비용이 높고 이것도 preview |
| `gemini-2.5-flash-image` | 호환 예제에서 아직 보이는 구형 라인 | 오래된 예제나 의도적 migration context | Google이 **2026년 10월 2일** shutdown date를 명시 |

Google의 [billing 페이지](https://ai.google.dev/gemini-api/docs/billing)는 새 account가 Free Tier에서 시작하며, free limits 안에서 쓸 수 있는 모델은 일부라고 설명합니다. [rate-limits 페이지](https://ai.google.dev/gemini-api/docs/rate-limits)는 실제 active limits가 usage tier에 따라 다르고 AI Studio에서 봐야 한다고 밝힙니다.

그래서 이 글은 “완전 무료 Gemini 이미지 REST API”라고 말하지 않습니다. request가 맞아도 model access, project tier, preview-limit policy 때문에 실패하는 경우가 충분히 있기 때문입니다.

## Troubleshooting: 어느 레이어가 깨졌는지 먼저 나눈다

![Gemini 이미지 REST 워크플로에서 404, 무효 payload, project mismatch, 이미지 decode 누락을 어떻게 구분할지 보여 주는 트러블슈팅 맵.](https://www.aifreeapi.com/posts/ko/gemini-image-generation-rest-api/img/rest-error-triage-map.png)

이 keyword는 처음부터 troubleshooting intent가 강합니다. 많은 사용자가 첫 실패 뒤에야 이 검색을 합니다. 다행히 자주 나오는 failure pattern은 꽤 반복적입니다.

| 보이는 현상 | 자주 나오는 실제 원인 | 다음 행동 |
| --- | --- | --- |
| `/v1beta/openai/images/generations` 에서 404 | compatibility route에서 model이나 request shape가 맞지 않음 | 같은 작업을 native Gemini `generateContent` 로 다시 확인 |
| `Unknown name "generationConfig"` 또는 `generation_config` | native Gemini field를 OpenAI 호환 계약에 넣음 | native로 돌아가거나 호환 schema로 완전히 맞춤 |
| 오래된 image model에서 `model not found` | 낡은 snippet이나 forum example을 복사함 | current models와 deprecations를 다시 확인 |
| AI Studio는 되는데 cURL은 안 됨 | API key, billing, project access가 browser context와 다름 | 같은 project, key, model을 다시 맞춰 본다 |
| JSON은 오는데 이미지 파일이 없음 | request는 성공했고 `inlineData` decode가 아직 안 됨 | `.inlineData.data` 를 꺼내 base64 decode를 수행 |

여기서 시간을 가장 많이 아끼는 방법은 한 번에 한 레이어만 바꾸는 것입니다. host, model, prompt, save logic를 동시에 바꾸지 마세요. 먼저 native request, 그 다음 save step, 그리고 나서야 quota나 compatibility behavior를 보는 순서가 안전합니다.

문제가 이미 URL 선택을 넘어서 429, 400, 500 대응 단계라면 [Gemini API error fix 2026: 429, 400, 500](/ko/posts/gemini-api-error-fix-2026-429-400-500) 로 넘어가는 편이 더 빠릅니다.

## FAQ

### `/v1beta/openai/images/generations` 가 틀린 경로인가요?

틀린 경로는 아닙니다. 이미 OpenAI 스타일 client surface 를 쓰고 있고 그 호출면을 최대한 유지해야 할 때는 합리적인 선택입니다. 다만 새 raw REST 구현에서 가장 먼저 시도할 기본값은 아닙니다. 새 작업이라면 native `generateContent` 를 먼저 검증한 뒤 호환 경로를 비교하는 편이 훨씬 빠릅니다.

### 왜 요청은 성공한 것 같은데 JSON만 돌아오나요?

native Gemini 이미지 REST 에서는 그게 정상입니다. 이미지 바이트가 JSON 안의 `inlineData` 로 돌아오기 때문입니다. 즉, 마지막 저장 단계가 아직 끝나지 않은 상태입니다. `.inlineData.data` 를 꺼내 base64 decode 를 수행한 뒤 파일로 써야 실제 이미지가 생깁니다.

### 지금 기본으로 시작할 모델은 무엇인가요?

현재는 `gemini-3.1-flash-image-preview` 부터 시작하는 것이 가장 안전합니다. native 이미지 문서와 models 페이지가 현재 기준으로 가장 자연스럽게 가리키는 고효율 라인이기 때문입니다. 텍스트가 많은 포스터나 고가치 시각물처럼 실패 비용이 큰 경우에는 `gemini-3-pro-image-preview` 를 볼 수 있습니다. 반면 `gemini-2.5-flash-image` 는 아직 일부 호환 예제에 보이지만, Google 은 이미 **2026년 10월 2일** 종료 일정을 적어 두었습니다.

### AI Studio 는 되는데 cURL 이 안 되면 무엇부터 확인하나요?

가장 먼저 URL 을 바꾸기보다 같은 project, 같은 API key, 같은 model access 로 호출했는지부터 확인합니다. 그다음 billing, tier, live limits 를 봅니다. REST 문법 문제처럼 보이는 현상도 실제로는 프로젝트 컨텍스트 차이인 경우가 많습니다.

## 결론

현재 raw HTTP 이미지 생성이라면 먼저 native 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` 를 검토합니다.

이것이 가장 안전한 현재 기본값입니다. 현행 native Gemini 문서와 가장 잘 맞고, 이미지 계약을 가장 명확하게 유지하며, 이 keyword에서 가장 흔한 오해인 “OpenAI 호환 이미지 경로가 모든 Gemini image REST의 universal default” 라는 착각을 피하게 해 주기 때문입니다.