imagen-4.0-generate-001 종료 — generate_images에서 generate_content로 마이그레이션하기

mini_knows·2026년 8월 17일

AI트렌드 GeminiAPI Imagen 마이그레이션 Imagen4 종료 nanobanana 이미지생성API

AI 트렌드·이슈

목록 보기

75/119

안녕하세요, 미니지식공간입니다.

imagen-4.0-generate-001을 비롯한 Imagen 4 엔드포인트 3종이 2026년 8월 17일에 종료된다. Imagen 4 종료 이후 generate_images 기반 코드는 대체 경로가 없으므로, Nano Banana(구글이 Gemini 네이티브 이미지 생성 기능에 붙인 브랜드명)로 불리는 Gemini 3.x 이미지 모델과 generate_content 계열 호출로 옮겨야 한다. 이 글은 공식 문서의 Before/After 예제를 기준으로 무엇을 어떤 순서로 고쳐야 하는지를 정리한다.

Before / After 한 장 요약

항목	Before (Imagen 4)	After (Nano Banana)
모델 ID	`imagen-4.0-generate-001` 외 2종	`gemini-3.1-flash-image` / `gemini-3-pro-image`
파이썬 메서드	`client.models.generate_images`	`client.models.generate_content` (문서 안내)
REST 엔드포인트	`/v1beta/models/{model}:predict`	`/v1beta/interactions` (이미지 생성 가이드 예제)
응답	`response.generated_images`	콘텐츠 파트 / `interaction.output_image`
장수 제어	`numberOfImages` 1~4 (기본 4)	없음. 항상 1장
출력 포맷	`imageFormat` 지정	항상 PNG
워터마크	`addWatermark` 제어	항상 SynthID

종료 팩트

구글은 2026년 6월 15일 Gemini API 릴리스 노트에 Imagen 4 계열 3종의 지원 종료를 공지했다. 세 모델의 릴리스일은 2025년 6월 24일이고, 종료일은 세 개 모두 2026년 8월 17일이다. Gemini 지원 종료 문서(2026년 8월 13일 UTC 최종 수정)의 Imagen 표가 이 날짜와 권장 대체 모델을 함께 기재하고 있다.

종료 대상 모델	릴리스일	종료일	문서상 권장 대체
`imagen-4.0-generate-001`	2025-06-24	2026-08-17	`gemini-3.1-flash-image`
`imagen-4.0-ultra-generate-001`	2025-06-24	2026-08-17	`gemini-3.1-flash-image`
`imagen-4.0-fast-generate-001`	2025-06-24	2026-08-17	`gemini-3.1-flash-image`

적용 범위는 Gemini Developer API와 Agent Platform Gemini API(구 Vertex AI) 양쪽이다. 파이어베이스 AI 로직(Firebase AI Logic) 마이그레이션 문서가 이 점을 명시한다. 다만 같은 문서와 Gemini 지원 종료 문서 모두 "빠르면(as early as) 8월 17일"이라는 표현과 함께, 표의 날짜는 실제로 종료될 수 있는 가장 이른 날짜이고 정확한 종료 시점은 사전 공지한다고 밝히고 있다. 당일 즉시 하드 실패로 바뀌는지는 확인이 필요하다.

1단계 — 대체 모델 선택

파이어베이스 마이그레이션 문서는 기존 모델 성격에 맞춰 thinking level(생성 전 추론 깊이를 정하는 설정)까지 포함해 대체 모델을 지정한다. Fast를 쓰던 자리에는 추론을 최소로, Standard 자리에는 추론을 높게 두라는 구성이다.

Imagen 모델	대체 Gemini 3.x 이미지 모델
`imagen-4.0-fast-generate-001`	`gemini-3.1-flash-image` (thinking level `MINIMAL`)
`imagen-4.0-generate-001`	`gemini-3.1-flash-image` (thinking level `HIGH`)
`imagen-4.0-ultra-generate-001`	`gemini-3-pro-image`
`imagen-3.0-capability-001`	`gemini-3.1-flash-image`

Nano Banana 계열은 네 개다. 이미지 생성 가이드 기준으로 gemini-3.1-flash-lite-image(Nano Banana 2 Lite)가 최저 지연·최저 비용, gemini-3.1-flash-image(Nano Banana 2)가 4K 생성과 다중 참조 이미지 처리를 아우르는 범용 주력, gemini-3-pro-image(Nano Banana Pro)가 최상위, gemini-2.5-flash-image(Nano Banana)가 구세대다. Lite는 다중 참조 입력과 다단계 연속 편집에 최적화되어 있지 않다고 문서가 명시하므로, 편집 파이프라인이 있다면 Lite로 내리기 전에 검증이 필요하다.

2단계 — 호출 코드 교체

기존 코드는 다음 형태였다. 아래는 Imagen 문서(ai.google.dev/gemini-api/docs/imagen)의 공식 예제를 그대로 옮긴 것이다.

from google import genai
from google.genai import types
from PIL import Image
from io import BytesIO

client = genai.Client()

response = client.models.generate_images(
    model='imagen-4.0-generate-001',
    prompt='Robot holding a red skateboard',
    config=types.GenerateImagesConfig(
        number_of_images= 4,
    )
)
for generated_image in response.generated_images:
  generated_image.image.show()

같은 문서의 REST 예제는 :predict 엔드포인트를 쓰고, 장수는 parameters.sampleCount로 넘긴다.

curl -X POST \
    "https://generativelanguage.googleapis.com/v1beta/models/imagen-4.0-generate-001:predict" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "instances": [
          {
            "prompt": "Robot holding a red skateboard"
          }
        ],
        "parameters": {
          "sampleCount": 4
        }
      }'

대체 코드는 이미지 생성 가이드(ai.google.dev/gemini-api/docs/image-generation)의 공식 예제를 따른다. 현재 이 가이드의 샘플은 GA로 전환된 Interactions API를 사용한다.

from google import genai
from PIL import Image
import base64

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.1-flash-image",
    input="Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme",
)

with open("generated_image.png", "wb") as f:

    f.write(base64.b64decode(interaction.output_image.data))

REST도 엔드포인트가 모델별 :predict에서 단일 /v1beta/interactions로 바뀌고, 모델 ID가 본문 필드로 들어간다.

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-3.1-flash-image",
    "input": [
      {"type": "text", "text": "Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme"}
    ]
  }'

여기서 문서 간 표현이 갈린다는 점은 짚고 넘어갈 필요가 있다. Imagen 문서의 마이그레이션 섹션은 client.models.generate_images를 client.models.generate_content로 바꾸라고 적지만, 이미지 생성 가이드의 현행 샘플은 client.interactions.create를 쓴다. Interactions API가 GA로 승격된 뒤 가이드가 먼저 갱신된 것으로 보이며, 어느 쪽을 표준으로 볼지는 확인이 필요하다. 신규 코드라면 가이드의 현행 샘플을 따르는 편이 무난하다.

응답 처리도 달라진다. Imagen은 response.generated_images 배열을 돌려줬지만, Gemini 이미지 모델은 콘텐츠 파트를 반환한다. 가이드는 편의 속성 interaction.output_image로 마지막 이미지 블록을 꺼낼 수 있다고 안내하면서, 텍스트와 이미지가 교차로 섞인 출력에서는 편의 속성이 모든 파트를 잡지 못하므로 스텝을 직접 순회하라고 덧붙인다.

3단계 — 클라이언트 SDK 앱의 구조 변경

모바일·웹 SDK로 호출하던 앱은 인스턴스 생성부터 바뀐다. 파이어베이스 문서의 웹 After 예제는 getImagenModel 대신 getGenerativeModel을 쓰고, 응답 형식과 화면비를 generationConfig에 명시한다.

const model = getGenerativeModel(ai, {
  model: "*GEMINI_IMAGE_MODEL_NAME*",
  generationConfig: {
    responseModalities: [ResponseModality.IMAGE],
    imageConfig: {
      aspectRatio: ImageConfigAspectRatio.LANDSCAPE_4x3
    }
  },
});

핵심은 세 가지다. ImagenModel → GenerativeModel, 응답 형식(response modality)에 IMAGE 지정, 그리고 화면비 등 이미지 옵션을 GenerationConfig에 중첩된 ImageConfig로 이동. 문서는 이 ImageConfig가 2026년 5월 초 SDK 버전부터 제공된다고 밝히므로, SDK 버전 상향이 선행 조건이다. 안전 설정도 ImagenSafetySettings에서 SafetySetting으로 옮겨야 한다.

4단계 — 사라진 파라미터 처리

파이어베이스 마이그레이션 문서가 정리한 옵션 대응표는 아래와 같다. 여섯 개 중 다섯 개가 미지원이다.

Imagen 옵션	Gemini 3.x 이미지 모델
`numberOfImages`	미지원. 항상 1장 반환. 문서는 루프 실행을 우회책으로 제시하며 candidate count는 대체재가 아니라고 명시
`negativePrompt`	미지원. 레거시 기능이며 `imagen-3.0-generate-002` 이후 지원된 적 없음
`personGeneration`	미지원. 기본적으로 인물 생성 허용
`imageFormat`	미지원. 항상 PNG 반환
`addWatermark`	미지원. 항상 SynthID 워터마크 포함
`aspectRatio`	지원. `ImageConfig`의 `aspectRatio`로 이동

실질적인 영향이 가장 큰 항목은 numberOfImages다. Imagen 4는 기본값이 4였으므로, 별도 설정 없이 쓰던 코드는 호출 1회당 결과 수가 4에서 1로 줄어든다. 후보 이미지 그리드 UI가 있다면 병렬 호출로 바꾸고 동시성 제한과 레이트 리밋을 다시 잡아야 한다. personGeneration으로 인물 생성을 차단하던 서비스라면 안전 설정 기반으로 정책을 재설계해야 하고, JPEG를 전제로 스토리지 용량을 산정했다면 PNG 기준으로 다시 계산해야 한다.

단가 재계산

과금 모델 자체가 바뀐다. Imagen 4는 장당 고정 단가였지만 Gemini 이미지 모델은 토큰 과금이고, 요금 페이지가 해상도별 환산 단가를 함께 제공한다. 아래는 유료 등급(Paid Tier) 기준이며 두 계열 모두 무료 등급은 없다.

모델	이미지 출력 토큰 단가	1장 환산
Imagen 4 Fast	장당 과금	$0.02
Imagen 4 Standard	장당 과금	$0.04
Imagen 4 Ultra	장당 과금	$0.06
`gemini-3.1-flash-lite-image`	$30 / 1M	1K $0.0336
`gemini-3.1-flash-image`	$60 / 1M	0.5K $0.045 · 1K $0.067 · 2K $0.101 · 4K $0.151
`gemini-3-pro-image`	$120 / 1M	1K·2K $0.134 · 4K $0.24

요금 페이지는 토큰 소비량도 명시한다. gemini-3.1-flash-image 기준 0.5K(512px) 이미지가 747토큰, 1K(1024×1024) 1,120토큰, 2K(2048×2048) 1,680토큰, 4K(4096×4096) 2,520토큰이다. 텍스트/이미지 입력은 별도로 $0.50/1M이 붙는다.

월 10만 장을 1K로 생성하는 워크로드를 이미지 출력 토큰만으로 환산하면, Imagen 4 Fast는 $2,000, gemini-3.1-flash-lite-image는 $3,360, gemini-3.1-flash-image는 $6,700이 된다. 문서 권장 경로를 그대로 따르면 약 3.4배, Lite로 내리면 약 1.7배 수준이다. 여기에 입력 토큰 비용이 더해지므로 실제 청구액은 더 크다. 배치(Batch) 요금을 쓰면 gemini-3.1-flash-image 1K가 $0.034로 절반이 되므로, 실시간성이 필요 없는 생성은 배치로 돌리는 편이 유효한 절감 수단이다.

문서 간 상충 — 어디로 갈지 헷갈리는 이유

권장 대체 모델이 문서마다 다르다. Gemini 지원 종료 문서와 파이어베이스 마이그레이션 문서는 gemini-3.1-flash-image를 지목하지만, Gemini API 요금 페이지의 경고 문구와 Imagen 문서의 마이그레이션 섹션은 gemini-2.5-flash-image로 옮기라고 적는다.

문제는 gemini-2.5-flash-image 자체의 종료일이 2026년 10월 2일로 이미 잡혀 있다는 점이다. 파이어베이스 문서 상단 공지도 Gemini 2.5 계열이 2026년 10월에 종료된다고 밝힌다. 2.5 Flash Image를 목적지로 잡으면 두 달 만에 다시 마이그레이션해야 한다. 어느 안내가 최신본인지는 확인이 필요하지만, 지금 작업한다면 Gemini 3.x 이미지 모델로 한 번에 가는 편이 합리적이다.

이미지 모델 API의 파라미터 체계가 세대마다 어떻게 갈라지는지는 Seedream 5.0 Pro API를 뜯어본 글에서도 비슷한 패턴으로 다뤘다.

자주 묻는 질문

Q. 기존 API 코드 수정이 필요한가?

필요하다. 모델 ID 교체만으로는 동작하지 않는다. 메서드가 generate_images에서 generate_content(또는 Interactions API)로 바뀌고, 응답이 전용 이미지 객체에서 콘텐츠 파트로 바뀌며, numberOfImages를 포함한 다섯 개 옵션이 대체 모델에 존재하지 않는다.

Q. imagen-4.0-generate-001 호출은 8월 17일에 바로 실패하나?

구글 문서는 표의 날짜를 "가장 이른 종료일"로 규정하고 정확한 시점은 사전 공지한다고 밝힌다. 당일 즉시 하드 실패로 전환되는지는 확인이 필요하다. 다만 예고 날짜에 도달했으므로 운영 코드라면 지체 없이 옮기는 편이 안전하다.

Q. 한 번 호출로 이미지 4장을 받으려면?

방법이 없다. 파이어베이스 문서는 Gemini 이미지 모델이 항상 한 장만 반환한다고 밝히고, 생성을 반복 실행하는 것을 우회책으로 제시하면서 candidate count는 대체재가 아니라고 못 박는다. 호출을 병렬화하고 레이트 리밋을 다시 산정해야 한다.

Q. 워터마크를 끌 수 있나?

없다. addWatermark 옵션 자체가 미지원이며, Gemini 이미지 모델은 생성 이미지에 항상 SynthID 워터마크를 포함한다고 문서에 명시되어 있다.

마무리

이번 종료는 모델 스왑이 아니라 호출 계층·응답 파싱·옵션 설계·단가 모델이 동시에 바뀌는 마이그레이션이다. 체크 순서는 대체 모델 선택 → 호출/응답 코드 교체 → SDK 버전 상향과 ImageConfig 적용 → 미지원 파라미터 우회 → 단가 재산정 정도가 된다. Imagen 호출이 남아 있다면 로그와 청구 대시보드부터 확인해 보시길 권한다.