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

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이 답을 아직도 여러 페이지에 나눠 두기 때문입니다. 이미지 생성 문서는 native Gemini 흐름을 설명하고, API reference는 generateContent 와 imageConfig 계약을 정의하며, OpenAI compatibility 문서는 별도의 호환 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 문제와 모델 문제를 한데 섞어 버리기 쉽습니다.

핵심 요약

host와 path 분기만 빠르게 정리하고 싶다면 Gemini 이미지 생성 API Base URL 부터 보면 됩니다. SDK 예제까지 함께 보려면 Gemini 이미지 생성 코드 예제 가 다음 단계에 더 잘 맞습니다.

먼저 native Gemini REST 경로를 쓴다

새로운 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 페이지는 이를 현재 고효율 이미지 라인으로 보여 주고, gemini-3-pro-image-preview 는 premium branch로 둡니다. 예전 라인인 gemini-2.5-flash-image 도 아직 보이지만, Google의 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에 따르면 imageConfig.imageSize 는 512, 1K, 2K, 4K 를 쓸 수 있습니다. 그래서 이미지 제어가 중요할수록 호환 레이어보다 native route가 더 이해하기 쉽습니다.

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

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

많은 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 문서는 다음 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가 실제 결정을 바꿉니다.

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

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

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

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

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

문제가 이미 URL 선택을 넘어서 429, 400, 500 대응 단계라면 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” 라는 착각을 피하게 해 주기 때문입니다.