Gemini 이미지 생성 코드 예제: JavaScript, Python, cURL

2026년 3월 22일 기준 Gemini 이미지 생성 코드의 가장 안전한 기본값은 native Gemini API와 gemini-3.1-flash-image-preview입니다. 처음부터 텍스트가 많은 그래픽이나 고가치 이미지가 목표가 아니라면, 먼저 이 경로부터 잡는 편이 가장 안정적입니다.

이 판단이 중요한 이유는 현재 Gemini image stack이 검색 결과만으로는 꽤 쉽게 오해되기 때문입니다. 어떤 페이지는 Gemini 앱을 설명하고, 어떤 페이지는 AI Studio를 다루고, 또 어떤 페이지는 raw API docs만 보여 줍니다. 여기에 오래된 2.5 이미지 튜토리얼까지 섞이면 개발자는 출발선을 잘못 잡기 쉽습니다. 실제로 필요한 first step은 더 좁고 실용적입니다. 먼저 current model을 고르고, working native request 하나를 실행하고, 실제 이미지를 저장한 다음, 그 뒤에 editing, Pro, Batch가 필요한지 판단하면 됩니다.

맨 앞에 두어야 할 caveat도 있습니다. Gemini Apps, AI Studio, Gemini API는 서로 연결되어 있지만 free와 paid를 하나의 규칙으로 설명할 수는 없습니다. Google의 billing 페이지는 새 계정이 Free tier에서 시작한다고 말하지만, Google이 2026년 2월 26일 공개한 Nano Banana 2 개발자 글은 이 모델을 AI Studio에서 쓰려면 paid API key가 필요하다고 분명히 적고 있습니다. 이 차이를 놓치면 코드 문제가 아니라 전제부터 잘못 잡고 디버깅하게 됩니다.

핵심 요약

• 새 image-generation 코드는 generic compatibility layer보다 native Gemini API에서 시작하는 편이 낫습니다. imageSize, aspectRatio, multi-turn editing, 더 넓은 image feature가 native route에서 더 잘 드러납니다.
• 기본값은 gemini-3.1-flash-image-preview입니다. 이미지 안 텍스트 품질, infographic 완성도, premium output의 가치가 비용 차이를 넘어설 때만 gemini-3-pro-image-preview를 본격적으로 고려하면 됩니다.
• 첫 request는 단순해야 합니다. 먼저 한 장을 생성해서 저장하고, 그다음 editing, grounding, Batch, 긴 prompt pipeline을 붙이세요.
• Gemini 3 image models에서는 imageSize와 aspectRatio를 명시하는 편이 좋습니다. 현재 docs는 512, 1K, 2K, 4K와 더 넓은 aspect ratio 범위를 공개합니다.
• 가격, paid key, 종료 날짜, rate limits는 모두 live fact입니다. gemini-2.5-flash-image는 아직 cheapest row이지만, deprecations 페이지는 종료일을 2026년 10월 2일로 적고 있습니다.

앱, AI Studio, API 차이부터 정리하고 싶다면 Gemini 이미지 생성 튜토리얼부터 보는 편이 낫습니다. 다음 고민이 syntax보다 pricing이면 Gemini image generation API 가격 가이드가 더 맞고, 실제 목표가 편집이라면 Gemini image-to-image editing guide가 더 적합합니다.

먼저 고를 것은 Gemini 이미지 생성 코드 경로다

이 주제에서 가장 비싼 실수는 prompt가 아니라 출발 surface를 잘못 고르는 것입니다. Gemini 앱이나 AI Studio에서 이미지를 만든 경험이 있으면 API도 비슷할 것처럼 느껴지기 쉽습니다. 하지만 API는 앱의 전제를 그대로 가져오지 않습니다. model ID, billing, response handling, quota를 직접 이해해야 하고, 그 차이가 실제 구현 비용을 좌우합니다.

대부분의 새 구현에서 가장 믿을 수 있는 출발점은 Gemini API image generation and editing docs입니다. Google은 여기에서 Gemini 3.1 Flash Image Preview를 current default로 제시하고, 실제 코드를 바꾸는 요소로 responseModalities, aspectRatio, imageSize, multi-turn editing을 설명합니다. 그래서 이 글도 OpenAI compatibility가 아니라 native Gemini route를 중심에 둡니다. compatibility layer는 migration에는 유용하지만, 지금의 image capability를 배우는 첫 입구로는 덜 선명합니다.

모든 Gemini image model이 같은 위치에 있는 것은 아닙니다. 현재 pricing 페이지는 그 차이를 꽤 분명하게 보여 줍니다. gemini-3.1-flash-image-preview는 fast default lane, gemini-3-pro-image-preview는 premium lane, gemini-2.5-flash-image는 아직 살아 있지만 legacy cost lane입니다. 게다가 deprecations 페이지는 2.5 image line의 종료일을 2026년 10월 2일로 적고 있습니다. 즉, "가장 저렴하다"와 "새 튜토리얼의 기본값이다"는 더 이상 같은 말이 아닙니다.

실무 판단은 단순합니다. 새 workflow라면 Flash Image부터 시작합니다. poster, diagram, infographic처럼 텍스트와 완성도가 중요한 작업이면 Pro를 후보에 넣습니다. 2.5 line을 선택한다면 미래 기본값이 아니라 legacy 저가 경로를 의도적으로 고른 것이라고 말해야 합니다. 이 순서만 맞춰도 뒤의 구현이 훨씬 선명해집니다.

AI Studio를 prompt playground로 쓰는 것은 괜찮습니다. 다만 AI Studio를 production contract처럼 받아들이면 안 됩니다. Nano Banana 2 개발자 글이 paid API key requirement를 분명히 적고 있는 만큼, 실제 architecture와 logging, quota planning은 API route를 기준으로 설계해야 합니다.

JavaScript 예제: 지금 가장 짧은 Node / 서버사이드 경로

Next.js, Node.js, backend JavaScript 환경이라면 현재 가장 자연스러운 path는 @google/genai입니다. client는 서버에 두고, GEMINI_API_KEY를 환경 변수에서 읽고, 반환되는 inlineData를 파일이나 object storage로 저장하면 됩니다.

이 예제가 좋은 이유는 나중에 가장 자주 깨지는 moving parts를 처음부터 다루기 때문입니다. 현재 package name, 현재 model name, explicit image controls, response parsing. 첫날부터 full pipeline을 만들 필요는 없습니다. 실제 이미지 한 장이 돌아오고, 저장되고, 요청한 비율과 크기에 맞는지만 확인하면 충분합니다.

javascript
import { GoogleGenAI } from "@google/genai";
import fs from "node:fs";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const prompt = `
Create a clean 16:9 product hero image of a matte black travel mug
on a light concrete surface. Use soft studio lighting, crisp texture,
and calm negative space on the right for marketing copy.
`;

const response = await ai.models.generateContent({
  model: "gemini-3.1-flash-image-preview",
  contents: prompt,
  config: {
    responseModalities: ["IMAGE"],
    imageConfig: {
      aspectRatio: "16:9",
      imageSize: "2K",
    },
  },
});

for (const part of response.candidates[0].content.parts) {
  if (part.inlineData) {
    const buffer = Buffer.from(part.inlineData.data, "base64");
    fs.writeFileSync("travel-mug-hero.png", buffer);
  }
}

여기서 기억할 점은 네 가지입니다. 첫째, model은 gemini-3.1-flash-image-preview이고 오래된 2.5 샘플이 아닙니다. 둘째, responseModalities: ["IMAGE"]는 설명 텍스트 없이 이미지 자체만 받고 싶을 때 유용합니다. docs는 기본이 text + image라고 하지만, 첫 "save the file" 단계에서는 image-only가 더 깔끔합니다. 셋째, 실제로 중요한 control은 imageConfig에 있습니다. 출력 shape가 중요하다면 명시하는 편이 안전합니다. 넷째, 이 예제는 server-side에 있어야 합니다. 짧은 코드라고 해서 permanent API key를 frontend에 두면 안 됩니다.

이게 먼저 돌아가고 나면, 다음 JavaScript 판단은 pure image output이면 충분한지, 아니면 text-plus-image response가 필요한지입니다. backend worker에는 image-only가 보통 더 단순합니다. creator tool처럼 사용자가 변경 설명이나 다음 제안을 함께 보는 편이 좋다면 mixed response가 더 낫습니다. native Gemini image flow의 장점 중 하나가 바로 이 conversation-friendly 구조입니다.

JavaScript는 과하게 복잡하게 만들기 쉬운 지점이기도 합니다. 첫 request에 grounding, chat state, 거대한 orchestration은 필요하지 않습니다. first image, then editing, then storage, then retries, then quotas. 이 순서가 대체로 가장 빨리 목적지에 갑니다.

Python 예제: 편집과 반복 작업에 가장 깔끔한 현재 경로

Python은 Gemini image generation을 배우기에 특히 편한 환경입니다. official docs가 읽기 쉽고, SDK도 compact하며, editing pattern이 script로 잘 떨어집니다. 그래서 batch tooling, 내부 운영, 편집 자동화에 특히 잘 맞습니다.

Python의 강점은 generation에서 editing으로 넘어갈 때 mental model이 거의 바뀌지 않는다는 점입니다. Gemini docs는 image generation과 image editing을 같은 generate_content 흐름 안에서 보여 줍니다. input만 달라질 뿐, call pattern 자체는 크게 달라지지 않습니다. 실제 visual workflow와 잘 맞는 구조입니다.

python
from google import genai
from google.genai import types
from PIL import Image

client = genai.Client()

base_image = Image.open("living-room.png")
prompt = """
Using the provided image of a living room, change only the blue sofa
to a vintage brown leather chesterfield sofa. Keep the pillows,
lighting, coffee table, and room layout unchanged.
"""

response = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=[prompt, base_image],
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
        image_config=types.ImageConfig(
            aspect_ratio="4:3",
            image_size="2K",
        ),
    ),
)

for part in response.parts:
    if part.text is not None:
        print(part.text)
    elif part.inline_data is not None:
        image = part.as_image()
        image.save("living-room-edit.png")

이 예제에서 중요한 것은 두 가지입니다. 하나는 prompt discipline입니다. 국소 편집을 원한다면 바뀌면 안 되는 요소를 분명하게 적어야 합니다. Gemini는 지시를 잘 따르지만, layout이나 lighting을 유지해야 한다는 점을 명시하지 않으면 결과가 흔들릴 수 있습니다. 다른 하나는 base image가 contents 안에서 text prompt와 함께 들어간다는 점입니다. current Gemini image editing은 "별도 edit mode"보다 "context를 넣고 controlled change를 요청한다"는 방식으로 이해하는 편이 더 정확합니다.

여기서부터는 multi-turn workflow가 긴 one-shot prompt보다 더 중요해집니다. image generation docs도 conversational editing을 권합니다. 실제로 좋은 production prompt는 가장 긴 prompt가 아니라 가장 잘 나눠진 prompt인 경우가 많습니다. 첫 instruction, 첫 결과, 그리고 필요한 delta만 요청하는 follow-up. 80% 맞은 이미지를 버리고 매번 처음부터 다시 쓰는 것은 대개 비효율적입니다.

Python은 이런 follow-up 자동화와 특히 잘 맞습니다. asset pipeline, moderation hook, post-processing에도 쉽게 연결됩니다. 하지만 이 지점에서 자주 나오는 실수도 있습니다. notebook이나 단발 script로 proof of concept는 됐는데 retries, logging, usage 관찰을 붙이지 않은 채 production으로 가는 경우입니다. user-facing flow가 될 예정이라면 그 "지루한 부분"도 미리 넣는 편이 낫습니다.

cURL과 raw REST 예제: 저수준 디버깅이나 언어 독립 통합이 필요할 때

SDK가 너무 추상적으로 느껴지거나 runtime이 Python / Node가 아니라면 raw REST는 여전히 가장 믿을 수 있는 truth source입니다. cURL은 full app을 만들기에는 불편하지만, Gemini API가 기대하는 request shape를 가장 직접적으로 보여 줍니다. model choice, payload serialization, proxy layer, AI Studio와 실제 코드의 차이를 확인할 때 특히 유용합니다.

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 16:9 studio photo of a white sneaker on a soft gray background with crisp side lighting and premium ecommerce styling."
        }
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "16:9",
        "imageSize": "2K"
      }
    }
  }'

이 cURL sample의 가치는 shell로 보낼 수 있다는 데만 있지 않습니다. cURL에서는 성공하고 SDK에서는 실패한다면 문제는 client version, wrapper, response parsing 쪽에 있을 가능성이 큽니다. 반대로 cURL에서도 실패하면 API contract, billing, rate limits, model choice 쪽으로 범위를 좁힐 수 있습니다. 이 분기가 디버깅 속도를 크게 높여 줍니다.

SDK가 없는 언어나 low-dependency 환경에서도 raw REST는 좋은 starting point입니다. 결국 Go, Rust, PHP, 내부 platform layer로 감쌀 수는 있어도, 먼저 wire format을 보는 편이 좋습니다. generateContent, contents, generationConfig, responseModalities, imageConfig를 눈으로 확인하면 나중에 internal wrapper를 만들 때도 훨씬 선명합니다。

단점도 분명합니다. response decode를 직접 해야 하고, parts, chats, file inputs에서 SDK의 편의성은 사라집니다. 그래서 cURL은 daily comfort path보다는 debugging tool / truth source로 이해하는 편이 맞습니다.

실제로 코드가 달라지는 편집, 멀티턴 흐름, 고해상도 옵션

Gemini-native image generation이 얕은 튜토리얼과 가장 크게 갈라지는 지점이 여기입니다. text-to-image 한 번으로 끝나는 페이지는 많지만, 실제 제품 가치는 그 다음에 있습니다. controlled edit, reference image, higher resolution, 이전 결과를 유지한 채 refinement 하는 흐름이 필요하기 때문입니다.

Google의 current docs도 이 점을 꽤 강하게 밀고 있습니다. 단발 생성뿐 아니라 multi-turn image editing을 권하고, chat 안에서 infographic를 만들고 뒤이어 언어만 바꾸는 예시도 보여 줍니다. 중요한 것은 예시의 화려함이 아니라 mental model입니다. Gemini image generation은 단순히 픽셀을 반환하는 endpoint가 아니라, context를 유지한 채 visual state를 계속 수정할 수 있는 시스템에 가깝습니다.

javascript
import { GoogleGenAI } from "@google/genai";
import fs from "node:fs";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const chat = ai.chats.create({
  model: "gemini-3.1-flash-image-preview",
  config: {
    responseModalities: ["TEXT", "IMAGE"],
  },
});

await chat.sendMessage({
  message:
    "Create a vibrant infographic that explains photosynthesis like a colorful kids cookbook.",
});

const response = await chat.sendMessage({
  message: "Update this infographic to be in Spanish. Do not change any other elements.",
  config: {
    responseModalities: ["TEXT", "IMAGE"],
    imageConfig: {
      aspectRatio: "16:9",
      imageSize: "2K",
    },
  },
});

for (const part of response.candidates[0].content.parts) {
  if (part.inlineData) {
    fs.writeFileSync(
      "photosynthesis-es.png",
      Buffer.from(part.inlineData.data, "base64")
    );
  }
}

이 단계에서 imageSize와 aspectRatio는 더 이상 trivia가 아닙니다. 공식 docs는 512, 1K, 2K, 4K와 16:9, 9:16, 21:9, 4:1, 1:4 같은 aspect ratio를 공개합니다. 이는 code path 자체를 바꿉니다. ecommerce asset, banner, social crop, app-store artwork처럼 output shape가 downstream cost에 직결되는 작업에서는 native request에서 미리 지정하는 편이 훨씬 유리합니다.

Pro lane도 여기에서 이해하는 편이 자연스럽습니다. pricing page와 Gemini Apps help는 서로 다른 surface에서 같은 이야기를 합니다. Flash Image는 fast default, Pro는 expensive but higher-stakes lane입니다. poster copy, diagram, infographic label, premium product art처럼 결과의 실패 비용이 큰 일이라면 code level에서도 Pro를 염두에 두어야 합니다.

또 한 가지 capability edge가 있습니다. current pricing page는 Google Search grounding과 image-based grounding 비용을 따로 보여 주고, docs도 search-grounded visual flow를 예시로 듭니다. 즉 premium workflow의 일부는 더 이상 "prompt in, image out"만이 아닙니다. 다만 이것은 day-one requirement가 아닙니다. 먼저 base request를 확실히 만든 뒤, 제품이 정말 필요로 할 때 grounding을 추가해야 합니다.

가격, Batch 모드, 그리고 Pro가 값어치를 하는 시점

code example 글에서 pricing이 전부가 될 필요는 없지만, 무시할 수도 없습니다. model choice와 output resolution이 곧 implementation decision이기 때문입니다.

현재 pricing 페이지 기준으로 Gemini 3.1 Flash Image Preview는 standard mode에서 0.5K 약 $0.045, 1K 약 $0.067, 2K 약 $0.101, 4K 약 $0.151입니다. Gemini 3 Pro Image Preview는 1K / 2K 약 $0.134, 4K 약 $0.24입니다. legacy Gemini 2.5 Flash Image는 standard 약 $0.039, Batch 약 $0.0195가 아직 공식 표에 남아 있습니다. 이 숫자들은 단순한 가격표가 아니라 어떤 sample을 default로 가르쳐야 하는지를 바꿉니다.

그렇다면 Pro가 진짜 worth it인 시점은 언제일까요. 이미지 한 번 실패하는 비용이 model price 차이보다 더 클 때입니다. poster, diagram, infographic, premium 브랜드 자산처럼 텍스트 품질과 마감이 outcome을 좌우한다면 Pro가 맞습니다. 반대로 ideation, variation, cost-sensitive volume generation이라면 Flash Image가 여전히 더 강한 기본값입니다.

Batch mode는 아키텍처를 바꾸는 두 번째 판단입니다. pricing page의 economics는 꽤 명확합니다. 이미지 수가 많고 응답 지연을 허용할 수 있다면 Batch는 비용을 크게 낮춥니다. 특히 2.5 line과 Flash Image line에서 그렇습니다. 첫 sample code의 모양을 바꾸지는 않지만, prototype에서 scheduled generation으로 넘어갈 때 추천이 달라집니다.

여기서 2.5 image line의 위치도 솔직하게 말해야 합니다. 아직 useful하고 official하며 cheaper합니다. 하지만 fresh한 code-example page가 이것을 main recommendation으로 두는 것은 정확하지 않습니다. 지금의 2.5는 retirement clock이 보이는 cheap legacy branch입니다.

문제 해결: Gemini 이미지 생성 코드 예제에서 자주 생기는 실수

첫 번째 실수는 오래된 2.5 image tutorial을 그대로 current default처럼 복사하는 것입니다. 지금은 그렇지 않습니다. current docs, pricing, launch materials는 모두 Gemini 3 image line을 기본 추천으로 밀고 있습니다. gemini-2.5-flash-image를 쓴다면 legacy-cost route를 의도적으로 택한 것이라고 이해하는 편이 맞습니다.

두 번째 실수는 앱, AI Studio, Gemini API를 하나의 product contract처럼 보는 것입니다. Gemini Apps help는 consumer surface 이해에는 좋고, AI Studio는 prompt 실험에 좋습니다. 하지만 실제 코드가 따르는 contract는 API입니다. billing, launch post, docs를 분리해서 읽지 않으면 paid key와 quota 전제에서 쉽게 어긋납니다.

세 번째 실수는 explicit image controls를 생략하는 것입니다. 출력 shape가 중요하면 aspectRatio, 크기가 중요하면 imageSize를 적어야 합니다. docs가 말하듯 지정하지 않으면 input image size를 따르거나 square output이 나올 수 있습니다. 실험에는 괜찮아도 production 기본값으로는 약합니다.

네 번째 실수는 image generation을 one-shot endpoint로만 보는 것입니다. 실제 workflow는 multi-turn editing을 더 자주 필요로 하고, 좋은 partial result를 유지한 채 delta만 수정하는 편이 더 빠르고 저렴하며 제어하기 쉽습니다.

다섯 번째 실수는 project-level quota를 무시하는 것입니다. rate limits 페이지는 limit가 project 단위로 걸리고 requests per day가 Pacific time 자정에 reset된다고 설명합니다. 429 confusion이 많은 이유가 여기에 있습니다. 마법 숫자를 외우기보다 quota를 live project state로 확인하는 편이 정확합니다.

여섯 번째 실수는 가장 싼 row를 첫 번째로 가르쳐야 한다고 생각하는 것입니다. 교육 순서로는 current default first, cheaper legacy second, premium Pro third가 reader에게 더 좋은 판단을 줍니다.

일곱 번째 실수는 SynthID watermark를 잊는 것입니다. workflow를 항상 망치지는 않지만, 실제 product characteristic인 이상 구현 가이드가 말하지 않을 이유는 없습니다. 실제 고민이 "어떤 sample을 쓸까"가 아니라 "왜 갑자기 안 되지"라면 다음으로 Gemini image generation limit reset과 Gemini image API free tier를 보는 편이 맞습니다.

결론

2026년의 Gemini image generation code examples에서 중요한 것은 가장 화려한 sample이 아니라, 다음 implementation decision을 가장 명확하게 만들어 주는 sample입니다.

먼저 native Gemini API에서 시작하세요. 대부분의 새 workflow에서는 gemini-3.1-flash-image-preview가 기본값입니다. JavaScript, Python, cURL 가운데 하나로 실제 이미지 한 장을 저장하고, 그다음 complexity를 더합니다. output shape가 중요해지는 순간 aspectRatio와 imageSize를 명시하세요. gemini-3-pro-image-preview는 text-heavy, infographic-heavy, premium output의 가치가 비용 차이를 넘을 때만 선택하면 됩니다. gemini-2.5-flash-image는 cheap legacy lane으로 다루세요. 이 구조만 맞춰도 이후 구현은 훨씬 선명해집니다.