나노 바나나 API 사용법: 공식 문서·키 발급·현재 코드, 시작 모델은 2.1

나노 바나나(Nano Banana)는 따로 가입하는 서비스가 아니라 Gemini API 안에 있는 이미지 생성 모델 계열의 이름입니다. Google 공식 문서도 "Nano Banana는 Gemini의 기본 이미지 생성 기능의 이름"이라고 설명합니다. 필요한 것은 구글 AI 스튜디오에서 만든 Gemini API 키 하나이고, 처음 호출할 모델은 나노 바나나 2.1(gemini-nano-banana-2.1)입니다. Google 이미지 생성 문서는 새 프로젝트에 모두 2.1을 쓰라고 권합니다. 새로 짜는 코드는 Google 권장대로 Gemini API의 새 호출 방식인 Interactions API로 쓰면 되고, 기존 호출 방식인 generateContent로 만든 코드도 계속 지원됩니다.

2026년 10월 8일 기준으로 달라진 점은 네 가지입니다.

• 나노 바나나 2.1이 2026년 10월 6일 정식 버전으로 나왔습니다. 아래 코드의 기본 모델 ID도 모두 gemini-nano-banana-2.1입니다. 출력 크기는 1K, 2K, 4K이고 512px는 없습니다.
• 나노 바나나 2(gemini-3.1-flash-image)는 같은 날 Gemini API에서 지원 중단됐습니다. 종료일은 발표되지 않았으니 지금 돌아가는 코드가 당장 멈추지는 않지만, 새 코드는 2.1로 씁니다.
• -preview로 끝나는 나노 바나나 모델 ID는 모두 종료됐습니다. 2025년 튜토리얼이나 올해 초 코드를 갖고 있다면 모델 ID부터 확인하세요.
• 1세대 gemini-2.5-flash-image의 종료일은 Google 페이지마다 다르게 적혀 있습니다. 지원 중단 일정 표는 2027년 3월 15일, 가격 페이지 경고문은 2026년 10월 2일입니다.

Interactions API를 일찍 도입했다면 결과를 outputs 배열로 읽는 코드가 2026년 6월 8일 구 스키마 제거와 함께 깨졌다는 점도 함께 확인하세요. 아래의 모델 ID, 날짜, 가격은 2026년 10월 8일 기준 Google 이미지 생성 문서, Gemini API 지원 중단 일정, Gemini API 가격 페이지를 따릅니다.

공식 문서는 어디이고, 이름만 같은 사이트와 무엇이 다른가

공식 나노 바나나 API 문서는 ai.google.dev에 있는 Gemini API 문서의 이미지 생성 페이지입니다. 요청은 generativelanguage.googleapis.com으로 보내고, 인증은 구글 AI 스튜디오에서 발급한 키를 x-goog-api-key 헤더에 넣는 방식입니다.

"Nano Banana API 문서"라는 제목을 단 독립 도메인 사이트도 여럿 있는데, 이런 곳은 자체 회원 가입과 자체 토큰, 자체 엔드포인트를 씁니다. 안에서 Google 모델을 호출하더라도 요청 형식, 가격, 지원 기능은 Google 문서와 다를 수 있고, Google의 가격표나 한도가 그대로 적용된다고 볼 근거도 없습니다. 구분하는 기준은 두 가지면 충분합니다. 요청 주소가 generativelanguage.googleapis.com(Vertex AI를 쓴다면 Google Cloud 주소)인지, 그리고 키를 구글 AI 스튜디오나 Google Cloud 콘솔에서 받았는지입니다.

공식 문서 안에서도 필요한 내용은 여러 페이지에 나뉘어 있습니다. 하려는 일에 따라 아래 페이지를 열면 됩니다.

나노 바나나 모델 5종 중 무엇으로 시작하나: 새 프로젝트는 2.1

Google 이미지 생성 문서는 2026년 10월 8일 기준 나노 바나나를 5개 모델로 나눕니다. 나노 바나나 2.1을 이미지 생성과 대화형 편집의 주력(workhorse) 모델로, 나노 바나나 2를 이전 세대 모델로 소개하고, 새 프로젝트에는 모두 2.1을 쓰라고 권합니다. Google 설명으로는 2.1이 나노 바나나 2의 업데이트 버전으로, Flash급 속도와 비용을 유지하면서 화질, 프롬프트 준수, 멀티턴 인물 일관성, 글자 표현이 나아졌습니다.

가격은 Google 가격 페이지의 이미지 출력 토큰 단가를 장당으로 환산한 미국 달러 금액이고, Batch로 보내면 절반입니다. 2.1의 Batch 단가는 1K $0.0168, 2K $0.0252, 4K $0.0567입니다. 2.1의 4K 단가는 출시 직후인 10월 6~7일에 $0.0756으로 표시됐다가 4K 한 장을 3,780토큰으로 계산한 $0.113으로 바뀌었습니다. 이미지 생성 문서의 2.1 비율표에는 4K가 아직 2,520토큰으로 남아 있으니 비용은 가격 페이지 기준으로 잡으세요. 다섯 모델 모두 API 이미지 출력에는 무료 등급이 없습니다.

장당 환산가에는 이미지 토큰만 들어 있습니다. 2.1은 입력이 100만 토큰당 $1.50, thinking과 설명 텍스트 출력이 100만 토큰당 $7.50로 따로 붙습니다. 2026년 10월 8일 LaoZhang API를 거쳐 2.1을 호출했을 때 응답에 기록된 1K 한 장의 토큰은 입력 42, 이미지 1,120, 설명 텍스트 394, thinking 854개였습니다. Google 정가를 적용하면 42 × $1.50 + (394 + 854) × $7.50 + 1,120 × $30을 100만으로 나눈 약 $0.043이 한 장의 실제 비용에 가깝습니다. LaoZhang API가 Google의 사용량 기록을 그대로 전달한다는 가정 아래 계산한 값이며, Google 청구서와 대조한 금액은 아닙니다.

안내: laozhang.ai는 이 블로그 운영팀의 자사 서비스입니다. 그 가격은 독립적인 비교가 아니라 자사 제시 가격입니다.

해상도별 단가와 Batch 계산은 나노바나나 2(Nano Banana 2) API 가격: 장당 $0.045~$0.151, 2.1은 1K 절반에 정리돼 있습니다.

모델은 이렇게 고르면 됩니다.

• 새 프로젝트는 나노 바나나 2.1로 시작합니다. 텍스트로 생성, 이미지 편집, 대화로 이어서 고치기, 참조 이미지 14장까지 한 모델로 처리합니다. 1K와 2K 장당 단가는 나노 바나나 2의 절반이고($0.0336 대 $0.067, $0.0504 대 $0.101), 4K도 $0.113으로 나노 바나나 2의 $0.151보다 낮습니다.
• 512px 출력이 꼭 필요할 때만 나노 바나나 2에 남습니다. 2.1은 512px를 지원하지 않습니다. 나노 바나나 2는 지원 중단 상태이므로 언젠가는 옮겨야 합니다. 출시 내용과 이전할 때 확인할 점은 나노바나나 2.1 출시: 가격·사용법, 1K·2K 단가는 나노바나나 2의 절반에 있습니다.
• 1K 이미지를 대량으로 싸게 뽑는 단발성 작업이라면 Lite를 검토합니다. 1K 이미지 출력 단가는 2.1과 같은 $0.0336이지만, 입력(100만 토큰당 $0.25 대 $1.50)과 thinking·텍스트 출력($1.50 대 $7.50) 단가가 낮고 thinking 기본값도 minimal입니다. 다만 Google은 Lite가 여러 참조 입력과 연속 편집에 최적화돼 있지 않다고 적고 있고, 검색 그라운딩도 지원하지 않습니다.
• 정해진 문구가 이미지 안에 정확히 들어가야 할 때는 프로로 올립니다. 2026년 10월 8일 같은 프롬프트 9건을 1K로 한 번씩 생성해 비교했을 때 프로는 요청한 문구를 지켰고, 2.1은 글자 과제 3건에서 문구를 바꿨습니다. Google 자체 평가는 전반적인 선호도와 편집에서 2.1이 프로보다 낫다고 하니, 글자 정확도가 핵심이 아닌 작업은 2.1로 충분합니다. 1K 단가는 프로가 2.1의 약 4배($0.134 대 $0.0336)이므로 2.1로 먼저 만들고 부족한 작업만 모델 ID를 바꿔 프로로 보내는 방식이 비용 면에서 유리합니다. 비교 결과는 나노바나나 2.1 vs 프로 vs GPT Image 2.5 차이: 같은 프롬프트 9건 실측에, 프로 전용 JSON·YAML 설정은 나노 바나나 프로 API 사용법: 공식 JSON·YAML 설정과 이미지 저장에 있습니다.
• 1세대 gemini-2.5-flash-image로 새 코드를 짜지 않습니다. 지원 중단 상태이고 종료일 표기가 Google 페이지끼리 엇갈립니다. 이미지 생성 문서와 지원 중단 일정 표는 대체 모델로 Lite를 제시합니다.

작업별 차이를 더 자세히 보고 싶다면 Nano Banana 2 Lite·2·2.1·Pro 차이: 작업별 선택법, 새 프로젝트는 2.1을 참고하세요.

모든 모델의 생성 이미지에는 SynthID 워터마크가 들어갑니다.

1단계: 구글 AI 스튜디오에서 API 키 받기

나노 바나나 API 키는 따로 없습니다. 구글 AI 스튜디오에서 만드는 Gemini API 키가 곧 나노 바나나 API 키이고, 같은 키로 2.1, Lite, 나노 바나나 2, 프로를 모두 호출합니다.

1. 구글 AI 스튜디오에 로그인합니다. 처음 쓰는 계정이라면 서비스 약관에 동의하는 순간 기본 Google Cloud 프로젝트와 API 키가 자동으로 만들어집니다.
2. 이미 Google Cloud를 쓰고 있는 계정이라면 기본 프로젝트가 생기지 않습니다. 왼쪽 대시보드에서 Projects를 열고 Import projects로 쓸 프로젝트를 가져온 뒤, API Keys 페이지에서 그 프로젝트에 키를 만듭니다.
3. Create API key 버튼이 비활성화되고 "You do not have permission to create a key in this project"가 보이면 프로젝트 권한이 부족한 것입니다. 관리자에게 Project Editor 같은 역할을 요청하거나, 조직에 속하지 않은 새 프로젝트를 만들어 키를 발급합니다.
4. 이미지 출력은 유료 등급에서만 되므로, 키가 속한 프로젝트에 결제 계정을 연결합니다. 결제를 연결하면 Tier 1이 됩니다.

키에 관해 2026년에 바뀐 점이 두 가지 있습니다. 2026년 5월 28일부터 구글 AI 스튜디오에서 새로 만드는 키는 모두 auth key(authorization key)입니다. auth key는 Google Cloud 서비스 계정에 묶여 있고, 기본적으로 Gemini API에만 쓰이도록 제한되며, 유출이 감지되면 빠르게 사용이 차단됩니다. 그리고 Gemini API는 제한이 걸려 있지 않은 예전 standard key의 요청을 거부합니다. 예전에 만든 키에 Unrestricted 표시가 붙어 있다면, API Keys 페이지에서 Add restrictions를 눌러 Restrict to Gemini API only를 선택하거나 새 키를 만들어 교체하세요. 오래 쓰지 않은 무제한 키는 2026년 5월 7일부터 Blocked 상태로 막혀 있습니다.

키는 코드에 적지 말고 환경 변수에 넣습니다. Google SDK는 GEMINI_API_KEY(또는 GOOGLE_API_KEY) 환경 변수를 자동으로 읽고, 둘 다 있으면 GOOGLE_API_KEY가 우선합니다.

export GEMINI_API_KEY="구글_AI_스튜디오에서_복사한_키"

웹 페이지나 모바일 앱 코드에 키를 넣으면 사용자가 꺼내 갈 수 있습니다. 브라우저에서 이미지를 만들어야 한다면 요청을 자체 백엔드 서버를 거쳐 보내고, 키는 저장소에 커밋하지 않습니다.

한도는 키가 아니라 프로젝트 단위로 걸립니다. 같은 프로젝트에 키를 여러 개 만들어도 한도는 늘지 않습니다. 나노 바나나 모델에는 분당 이미지 수(IPM) 한도가 따로 있고, 10분 동안의 지출 한도(Tier 1 기준 $10)를 넘으면 429 RESOURCE_EXHAUSTED가 옵니다. 모델별 실제 분당 한도는 구글 AI 스튜디오의 한도 화면에서만 보이며, 2026년 10월 8일 기준 Gemini API 비율 제한 문서에는 2.1 행이 아직 없습니다. 등급별 한도와 올리는 조건은 나노바나나 2 한도 제한, 하루 몇 장? 앱은 5시간 갱신·API는 결제 등급을, 429가 어느 한도에서 왔는지 가르는 방법은 Gemini 이미지 429 오류 해결: 분당·일일·10분 지출 한도부터 구분을 참고하세요.

2단계: SDK 설치하고 첫 이미지 저장하기

Interactions API는 /v1beta/interactions 엔드포인트로 요청하는 Gemini API의 새 호출 방식입니다. 대화 기록을 서버가 보관하고, 응답을 단계(steps) 단위로 돌려줍니다. SDK로 쓰려면 Python은 google-genai, JavaScript는 @google/genai 패키지가 2.3.0 이상이어야 합니다. 버전이 낮으면 client.interactions 자체가 없습니다.

# Python
pip install -U google-genai
pip show google-genai   # Version이 2.3.0 이상인지 확인

# JavaScript / TypeScript
npm install @google/genai

이 단계와 3단계의 Python, JavaScript, REST 코드는 Google 이미지 생성 문서의 예제(2026년 10월 8일 기준 기본 모델 gemini-nano-banana-2.1)에서 프롬프트, 파일 이름, 출력 설정만 바꾼 것입니다. Google 키로 실행한 결과는 아니므로 처음 돌릴 때는 응답에 이미지가 있는지부터 확인하세요. 프롬프트는 한국어로 써도 되며, Google은 한국어(ko-KR)를 권장 언어 목록에 넣어 두었습니다.

import base64
from google import genai

client = genai.Client()  # GEMINI_API_KEY 환경 변수를 자동으로 읽음

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="고급 레스토랑 접시에 담긴 작은 바나나 요리, 별자리 조명, 사진처럼 사실적으로",
    response_format={"type": "image"},  # 설명 텍스트 없이 이미지만 받기
)

if interaction.output_image:
    with open("nano_banana.png", "wb") as f:
        f.write(base64.b64decode(interaction.output_image.data))
else:
    print(interaction.output_text)  # 이미지 대신 돌아온 텍스트 확인

response_format을 빼면 모델은 설명 텍스트와 이미지를 함께 돌려줍니다. 요청이 안전 필터에 걸리거나 모델이 텍스트로만 답하면 output_image가 비어 있으니, 저장하기 전에 확인하는 편이 안전합니다. Google 예제는 .png로 저장하지만, 아래에 적은 LaoZhang API 경유 호출에서는 형식을 지정하지 않았을 때 모두 JPEG가 왔습니다. 확장자와 실제 형식을 맞추려면 response_format에 "mime_type": "image/png"처럼 원하는 형식을 넣으세요.

안내: laozhang.ai는 이 블로그 운영팀의 자사 서비스입니다. 그 가격은 독립적인 비교가 아니라 자사 제시 가격입니다.

JavaScript도 구조가 같습니다.

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

const ai = new GoogleGenAI({}); // GEMINI_API_KEY 환경 변수를 자동으로 읽음

const interaction = await ai.interactions.create({
  model: "gemini-nano-banana-2.1",
  input: "고급 레스토랑 접시에 담긴 작은 바나나 요리, 별자리 조명, 사진처럼 사실적으로",
  response_format: { type: "image" },
});

const image = interaction.output_image;
if (image) {
  fs.writeFileSync("nano_banana.png", Buffer.from(image.data, "base64"));
} else {
  console.log(interaction.output_text);
}

SDK 없이 REST로 호출하면 응답 JSON의 steps 배열 안에서 이미지 블록을 꺼내 base64를 풀어야 합니다. 이미지 데이터는 type이 model_output인 단계의 content 안에서 type이 image인 블록의 data에 들어 있습니다.

curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": "고급 레스토랑 접시에 담긴 작은 바나나 요리, 별자리 조명, 사진처럼 사실적으로",
    "response_format": {"type": "image", "aspect_ratio": "16:9", "image_size": "2K"}
  }' > response.json

jq -r '[.steps[] | select(.type == "model_output") | .content[] | select(.type == "image") | .data] | last' response.json \
  | base64 --decode > nano_banana.png

실제 호출 기록이 있는 것은 2026년 10월 8일 LaoZhang API로 2.1을 8번 호출한 결과뿐입니다. Gemini 네이티브 형식(generateContent)으로 7번, OpenAI 호환 형식으로 1번 보냈고, 모두 HTTP 200에 이미지가 왔습니다. 크기는 1K 1:1이 1024×1024, 2K 16:9가 2752×1536, 4K 16:9가 5504×3072로 Google 문서의 2.1 비율표와 같았고, 한 번에 18~35초가 걸렸습니다. LaoZhang API는 크기와 thinking 수준에 관계없이 호출마다 $0.045를 받았습니다. Google 엔드포인트에서의 응답 시간이나 성공률은 이 기록으로 알 수 없습니다.

응답이 200인데 이미지가 없거나 429, 503이 반복되면 Nano Banana API 이미지 안 나옴: 응답별 원인과 조치와 Nano Banana API 오류 해결: 429, 503, 이미지 없음, 요청 거부에서 응답 형태별로 원인을 좁힐 수 있습니다.

3단계: 편집, 이어서 고치기, 참조 이미지, 크기 지정

가진 이미지를 편집하기

편집은 input을 문자열 대신 목록으로 보내면 됩니다. 텍스트 블록에 지시를 넣고, 이미지 블록에 base64로 인코딩한 원본을 넣습니다.

import base64
from google import genai

client = genai.Client()

with open("product.png", "rb") as f:
    source_b64 = base64.b64encode(f.read()).decode("utf-8")

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input=[
        {"type": "text", "text": "배경만 흰색 스튜디오로 바꾸고 제품의 모양과 색은 그대로 유지해 줘"},
        {"type": "image", "data": source_b64, "mime_type": "image/png"},
    ],
)

with open("product_edited.png", "wb") as f:
    f.write(base64.b64decode(interaction.output_image.data))

앞의 결과를 이어서 고치기

한 번 만든 이미지를 조금씩 고칠 때는 이미지를 다시 보낼 필요가 없습니다. 앞 요청의 id를 previous_interaction_id로 넘기면 서버가 이전 대화와 이미지를 이어 받습니다. Google은 2.1에서 멀티턴 인물 일관성이 나아졌다고 설명합니다.

first = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="광합성 과정을 요리 레시피처럼 설명하는 밝은 인포그래픽. 재료는 햇빛, 물, 이산화탄소",
)

second = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input="이 인포그래픽의 글자를 모두 영어로 바꿔 줘. 다른 요소는 바꾸지 마.",
    previous_interaction_id=first.id,
    response_format={"type": "image", "aspect_ratio": "16:9", "image_size": "2K"},
)

with open("infographic_en.png", "wb") as f:
    f.write(base64.b64decode(second.output_image.data))

REST에서는 요청 본문에 "previous_interaction_id" 필드로 같은 값을 넣습니다. 이 기능은 서버 보관(store, 기본값 켜짐)에 기대고 있어서, store=false로 보관을 끄면 이어서 고치기를 쓸 수 없습니다. 보관 기간은 유료 등급 55일, 무료 등급 1일입니다. Lite는 연속 편집에 최적화돼 있지 않으니 이 흐름에는 2.1이나 프로를 씁니다.

여러 장의 참조 이미지를 합치기

여러 사람이나 물체를 한 장면에 넣을 때는 이미지 블록을 여러 개 이어 붙입니다. 모델별 한도는 앞 표의 참조 이미지 행을 따릅니다. 2.1은 물체 10장과 인물 4장을 합쳐 14장까지, 프로는 물체 6장, 인물 5장, 스타일 참조 3장까지입니다.

def image_block(path, mime_type="image/png"):
    with open(path, "rb") as f:
        return {"type": "image", "data": base64.b64encode(f.read()).decode("utf-8"), "mime_type": mime_type}

interaction = client.interactions.create(
    model="gemini-nano-banana-2.1",
    input=[
        {"type": "text", "text": "이 세 사람이 사무실에서 장난스러운 표정으로 찍은 단체 사진"},
        image_block("person1.png"),
        image_block("person2.png"),
        image_block("person3.png"),
    ],
    response_format={"type": "image", "aspect_ratio": "5:4", "image_size": "2K"},
)

이미지가 커서 요청 크기가 부담스럽다면 Files API로 먼저 올리고 참조하는 방법이 Google의 이미지 이해(Image understanding) 문서에 있습니다.

크기, 비율, 출력 형식 정하기

출력 설정은 모두 response_format 한곳에 모입니다. type을 "image"로 두고 aspect_ratio, image_size, 필요하면 mime_type("image/jpeg" 등)을 넣습니다. 지정하지 않으면 입력 이미지 크기를 따르거나 1:1로 나옵니다.

• image_size는 대문자 K로 씁니다. "1K", "2K", "4K"는 되지만 "1k"처럼 소문자로 보내면 거부됩니다. 기본값은 1K입니다.
• 2K와 4K는 2.1, 나노 바나나 2, 프로에서 됩니다. Lite는 1K만 지원합니다.
• 2.1에는 512를 보내지 마세요. 512px(0.5K)는 나노 바나나 2 전용입니다. 2026년 10월 8일 LaoZhang API 경유 호출에서는 2.1에 512를 보냈을 때 오류 없이 1K 이미지가 오고 요금이 붙었고, 하루 전에는 같은 요청이 400 오류였습니다. 나노 바나나 2에서 512를 쓸 때는 이미지 생성 문서 "Generate images up to 4K resolution" 섹션의 512 표기에 오기로 보이는 부분이 있으니 문서를 직접 확인하고 넣으세요. generateContent의 imageSize는 레퍼런스에 512로 적혀 있습니다.
• 2.1과 나노 바나나 2는 화면 비율 14종을 받습니다. 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9에 세로·가로로 긴 1:4, 4:1, 1:8, 8:1이 더해지며, Google은 2.1에서 이 넓은 비율의 2K·4K 출력에 생기던 타일 모양 결함을 고쳤다고 밝혔습니다. Lite와 프로는 앞의 10종만 받습니다.
• 설명 텍스트와 이미지를 둘 다 받고 싶다면 response_format에 [{"type": "text"}, {"type": "image"}]처럼 목록을 넘깁니다.

안내: laozhang.ai는 이 블로그 운영팀의 자사 서비스입니다. 그 가격은 독립적인 비교가 아니라 자사 제시 가격입니다.

그림이 들어간 이야기나 단계별 안내서처럼 글과 그림이 번갈아 나오는 출력은 Google 문서가 프로(gemini-3-pro-image)로 예제를 보여 줍니다. 이때 output_image는 마지막 이미지 하나만 돌려주므로 steps를 직접 순회해야 합니다.

interaction = client.interactions.create(
    model="gemini-3-pro-image",
    input="모나크 나비의 한살이를 짧은 이야기로 쓰고, 단계마다 삽화를 넣어 줘",
)

image_count = 0
for step in interaction.steps:
    if step.type == "model_output":
        for block in step.content:
            if block.type == "text":
                print(block.text)
            elif block.type == "image":
                image_count += 1
                with open(f"story_{image_count}.png", "wb") as f:
                    f.write(base64.b64decode(block.data))

Google 검색 그라운딩, thinking, 비디오 입력, Batch

기본 생성과 편집이 되면 나머지 기능은 같은 이미지 생성 문서 안에서 찾을 수 있습니다. 필요한 순간에 어디를 보면 되는지만 정리합니다.

• Google 검색 그라운딩(Grounding with Google Search): 오늘 날씨 차트나 최근 사건처럼 실시간 정보가 필요한 이미지를 만들 때 씁니다. tools=[{"type": "google_search"}]를 넣으면 됩니다. 2.1과 나노 바나나 2는 search_types에 "image_search"를 넣어 Google 이미지 검색 결과를 시각 참고로 쓸 수 있는데, 이때 응답의 google_search_result 단계에 들어 있는 search_suggestions를 화면에 표시해야 합니다. 이미지 검색으로 실존 인물 사진을 가져오지는 않으며, Lite는 그라운딩을 지원하지 않습니다. 검색 요청은 Gemini 3 계열 전체를 합쳐 월 5,000건까지 무료이고, 그 뒤로는 1,000건당 $14입니다.
• thinking: Gemini 3 계열 이미지 모델은 복잡한 프롬프트를 처리할 때 항상 추론 과정을 거치며, API에서 끌 수 없습니다. 중간에 구도를 시험하는 이미지를 최대 2장 만들지만 이 이미지는 과금되지 않고, 추론 토큰은 과금됩니다. 2.1은 minimal, medium, high 세 단계를 받고 기본값이 medium입니다. 나노 바나나 2와 Lite는 minimal과 high 두 단계이고 기본값이 minimal입니다. 수준은 generation_config={"thinking_level": "high"}처럼 지정합니다. 앞의 LaoZhang API 경유 호출에서는 minimal로 낮춘 요청에도 thinking 토큰이 기록됐고(587~936개), 2K에서 high는 minimal보다 약 10초 더 걸렸습니다. 각 설정을 한 번씩만 보낸 결과라 경향으로 일반화하기는 어렵습니다.
• 비디오와 PDF 입력: 영상 썸네일이나 포스터를 만들 때 YouTube URL이나 Files API로 올린 영상을 참고 자료로 넣을 수 있습니다. 2.1, 나노 바나나 2, Lite만 됩니다. 2.1 모델 페이지는 입력 형식으로 텍스트, 이미지, 비디오와 함께 PDF도 적고 있습니다.
• Batch: 이미지 생성 문서의 모든 기능을 Batch API로 돌릴 수 있습니다. 결과는 최대 24시간 안에 나오는 대신 비율 제한이 넉넉하고 단가가 절반입니다. 당장 볼 필요가 없는 대량 생성에 맞습니다. 2.1은 Batch를 지원하지만 Flex 추론과 Priority 추론은 지원하지 않으며, 2026년 10월 8일 기준 비율 제한 문서의 Batch 대기 토큰 표에는 2.1 행이 아직 없습니다.

안내: laozhang.ai는 이 블로그 운영팀의 자사 서비스입니다. 그 가격은 독립적인 비교가 아니라 자사 제시 가격입니다.

예전 코드가 멈췄을 때: 날짜별 변경 사항과 2.1로 옮기기

2025년에 쓰인 튜토리얼과 2026년 상반기 코드가 지금 동작하지 않는 이유는 대부분 아래 표에 있습니다. 코드에서 왼쪽 열의 흔적을 찾아 오른쪽처럼 바꾸면 됩니다. 대체 모델은 Google 지원 중단 일정 표가 2026년 10월 8일 기준으로 제시한 ID입니다.

종료된 preview ID를 보내는 코드나 ComfyUI 노드는 요청이 실패합니다. 오류 메시지만으로 원인이 보이지 않을 때는 모델 ID 문자열부터 표와 대조하세요.

나노 바나나 2에서 2.1로 옮길 때는 모델 ID만 바꾸면 요청 형식은 그대로 쓸 수 있지만, 세 가지를 확인합니다.

1. 512 요청 빼기: 2.1은 1K, 2K, 4K만 냅니다. 512px 미리보기를 쓰던 흐름은 1K로 바꾸거나 그 부분만 나노 바나나 2에 남깁니다.
2. thinking 기본값 확인: 나노 바나나 2의 기본값은 minimal, 2.1은 medium입니다. 지정하지 않고 옮기면 응답 시간과 thinking 토큰 비용이 달라질 수 있으니, 예전과 비슷하게 맞추려면 thinking_level을 minimal로 명시하고 실제 사용량을 확인합니다.
3. 비용 다시 계산하기: 이미지 장당 단가는 내려가지만 2.1의 thinking·텍스트 출력 단가(100만 토큰당 $7.50)는 나노 바나나 2($3)보다 높습니다. 장당 단가만 보지 말고 응답의 토큰 사용량으로 계산합니다.

나노 바나나 2의 종료 날짜로 2026년 10월 29일을 적은 글이 있다면, 이 날짜는 2.1 출시 당일 Google 지원 중단 일정 페이지에 잠시 올라왔다가 10월 7일까지 지워진 값입니다. 2026년 10월 8일 기준 정해진 종료일은 없습니다.

1세대 gemini-2.5-flash-image는 Google 페이지끼리 날짜가 맞지 않습니다. Gemini API 지원 중단 일정 표는 종료일을 2027년 3월 15일로, 가격 페이지 경고문은 2026년 10월 2일로 적고 있습니다. 어느 쪽이 적용될지 Google이 정리하지 않았으니, 이 모델을 쓰는 서비스는 지금 옮겨 두는 편이 안전합니다. 1세대 모델은 입력 이미지 3장 이하에서 가장 잘 동작했고 출력이 1024px 고정이었기 때문에, 2.1로 옮기면 참조 이미지 수와 출력 크기 선택 폭이 넓어집니다. 단가가 1세대의 $0.039보다 낮은 쪽을 원한다면 1K 전용인 Lite($0.0336)가 Google이 제시하는 대체 모델입니다.

generateContent 코드를 계속 쓰는 경우

Google은 "generateContent는 계속 완전히 지원되며, 새 개발에는 Interactions API를 권장한다"고 밝히고 있습니다. 잘 돌아가는 generateContent 코드를 급하게 바꿀 필요는 없고, 모델 ID만 현재 것으로 바꾸면 됩니다. 이때 크기와 비율은 imageConfig(Python SDK는 image_config) 안에 넣습니다. 아래 두 예제는 generateContent 레퍼런스의 필드를 따른 형태이며, Google 키로 실행한 결과는 아닙니다. 앞에 적은 LaoZhang API 호출 7번은 같은 generationConfig.imageConfig 필드를 쓰는 Gemini 네이티브 형식이었습니다.

안내: laozhang.ai는 이 블로그 운영팀의 자사 서비스입니다. 그 가격은 독립적인 비교가 아니라 자사 제시 가격입니다.

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-nano-banana-2.1",
    contents="고급 레스토랑 접시에 담긴 작은 바나나 요리, 별자리 조명, 사진처럼 사실적으로",
    config=types.GenerateContentConfig(
        response_modalities=["IMAGE"],
        image_config=types.ImageConfig(aspect_ratio="16:9", image_size="2K"),
    ),
)

for part in response.candidates[0].content.parts:
    if part.inline_data:
        with open("nano_banana.png", "wb") as f:
            f.write(part.inline_data.data)

curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-nano-banana-2.1:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "고급 레스토랑 접시에 담긴 작은 바나나 요리, 별자리 조명, 사진처럼 사실적으로"}]}],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
    }
  }'

REST 응답에서는 candidates[].content.parts[] 가운데 inlineData가 있는 부분에 base64 이미지가 들어 있습니다. aspectRatio로 받는 비율은 1:1, 1:4, 4:1, 1:8, 8:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9입니다. imageSize는 레퍼런스에 512, 1K, 2K, 4K로 적혀 있지만 2.1에서는 1K, 2K, 4K만 씁니다.

나중에 Interactions로 옮길 때는 아래 대응 관계만 알면 대부분 기계적으로 바뀝니다.

같은 모델을 Google Cloud 프로젝트의 IAM 인증과 리전 설정 아래에서 써야 한다면 Gemini API 대신 Vertex AI를 씁니다. 수명 주기도 다릅니다. Vertex AI에서 나노 바나나 2는 정식(GA) 모델이고 지원 종료가 2027년 5월 28일 이후로 잡혀 있으며, 2.1은 global 리전에서만 제공됩니다. 두 경로의 차이는 Gemini API와 Vertex AI API 선택 기준: 빠른 개발인지, 클라우드 거버넌스인지에서, Vertex AI 쪽 모델 ID와 인증, 종료 일정은 Vertex AI 나노 바나나 API: 현재 모델 ID·인증·비용에서 볼 수 있습니다.

나노 바나나 API 자주 묻는 질문

나노 바나나 API를 무료로 쓸 수 있나요?

API로 이미지를 받는 데는 무료 등급이 없습니다. Google 가격 페이지는 다섯 모델 모두 이미지 출력의 무료 등급을 "Not available"로 표시하고 있어서, 키를 만든 뒤 프로젝트에 결제를 연결해야 이미지가 나옵니다. 가장 싼 공식 단가는 2.1과 Lite의 1K 이미지 장당 $0.0336, Batch로는 $0.0168이며, 여기에 입력과 thinking 토큰 비용이 더해집니다. API가 아닌 Gemini 앱에서는 무료 계정도 나노 바나나 2로 이미지를 만들 수 있지만 하루 장수는 공개돼 있지 않습니다. 앱 쪽 모델과 한도는 제미나이 이미지 생성 방법: 앱에서 API까지 모델·한도·코드에 정리돼 있습니다.

Google 직접 호출 대신 LaoZhang API를 쓰면 비용이 어떻게 달라지나요?

LaoZhang API는 2026년 10월 8일 기준 2.1을 크기와 thinking 수준에 관계없이 호출당 $0.045로 받습니다(LaoZhang 문서의 Nano Banana 2.1 페이지). 앞의 토큰 기록으로 Google 정가를 계산하면 1K는 약 $0.043, 2K는 약 $0.060, 4K는 약 $0.119이므로, 1K만 쓴다면 큰 차이가 없고 2K와 4K를 많이 쓸수록 정액 쪽이 유리해집니다. LaoZhang API는 HTTP 200 응답이면 이미지가 없어도 한 번 과금하고, 요청 형식과 기능이 Google 엔드포인트와 다를 수 있습니다. 조건별 비교는 Nano Banana API 비용·안정성 비교: Google 직접 호출과 laozhang.ai에 있습니다.

나노 바나나 2 코드는 언제까지 쓸 수 있나요?

2026년 10월 8일 기준 Gemini API에서 나노 바나나 2(gemini-3.1-flash-image)의 종료일은 발표되지 않았습니다. 지원 중단 상태라 새 기능이나 개선은 2.1 쪽으로 가고, 종료일이 정해지면 Google 지원 중단 일정 페이지에 올라옵니다. 지금 돌아가는 코드는 그대로 두되, 512px를 쓰지 않는 흐름부터 2.1로 옮기는 편이 안전합니다.

나노 바나나 프로 API는 따로 신청해야 하나요?

아닙니다. 같은 Gemini API 키로 모델 ID만 gemini-3-pro-image로 바꾸면 됩니다. 요청 형식도 2.1과 같습니다. 이전 preview ID인 gemini-3-pro-image-preview는 2026년 6월 25일 종료됐으니 쓰지 않습니다.

요청이 거부되거나 "검열"처럼 이미지가 안 나오면 어떻게 하나요?

안전 필터에 걸리면 이미지 대신 텍스트 설명만 돌아오거나 거부 응답이 옵니다. 먼저 output_text나 응답 JSON의 텍스트 블록에 적힌 이유를 확인하고, 실존 인물, 저작권 캐릭터, 폭력 묘사처럼 걸리기 쉬운 요소를 프롬프트에서 줄여 보세요. 응답 유형별 조치는 Nano Banana API 오류 해결: 429, 503, 이미지 없음, 요청 거부에 있습니다.

프롬프트는 어떻게 써야 결과가 좋아지나요?

Google 이미지 생성 문서 후반부에 사진, 스티커, 로고, 제품 사진 등 유형별 프롬프트 템플릿이 있습니다. 글자를 넣는 이미지는 문구를 먼저 정한 뒤 그 문구로 이미지를 요청하는 편이 결과가 좋다고 문서에 적혀 있습니다. 한국어 예시와 검증용 템플릿은 Nano Banana 프롬프트 작성법: 실전 가이드와 검증용 템플릿 50개에 모여 있습니다.

ComfyUI나 Claude Code 같은 도구에서 나노 바나나 2.1을 쓸 수 있나요?

ComfyUI는 Partner Node 목록에 "Nano Banana 2.1" 노드를 두고 있으며, ComfyUI 0.39.1 이상이 필요합니다. 이 노드는 Gemini API 키가 아니라 Comfy 계정 로그인과 선불 크레딧으로 과금됩니다. Claude Code 같은 코딩 도구에서는 같은 Gemini API 키와 모델 ID를 스킬이나 MCP 서버에 설정하면 되고, 설정 방법은 Claude Code에 나노바나나 연결: 스킬·MCP와 현행 모델 ID에 있습니다. 어느 도구든 설정에 preview ID나 gemini-3.1-flash-image가 남아 있다면 gemini-nano-banana-2.1로 바꿉니다.