메인 콘텐츠로 건너뛰기
🔥 최신 출시: Google이 2026년 2월 26일 Nano Banana 2(gemini-3.1-flash-image)를 출시했습니다. Flash급 속도로 Pro급 품질을 제공하며, 종량제 요금은 이미지당 최저 $0.025입니다! Nano Banana 2 문서 보기
🆕 2026년 5월 29일 업데이트(-preview 출시): Google이 공식 문서를 업데이트하고 안정 버전 모델 이름 gemini-3-pro-image(-preview 제외)을 공개했습니다. APIYI는 이미 이를 지원합니다.
  • 이 문서에서는 이제 안정 버전 이름을 사용합니다 gemini-3-pro-image 전체에서 — 새 통합에는 이 이름을 사용하세요.
  • 이전 이름도 계속 작동합니다: gemini-3-pro-image-preview은 계속 정상적으로 작동하며, 요금은 변경되지 않았고, 코드를 변경할 필요가 없습니다.
참고: Google은 안정 버전이 미리보기 버전과 출력 품질, 안전 필터링 또는 기타 동작에서 차이가 있는지 아직 명확히 밝히지 않았습니다. 테스트하고 의견을 공유해 주시기 바랍니다.
모든 이미지 API는 동기식입니다. 폴링할 작업 ID가 없으며, 요청 처리 중 클라이언트 연결이 끊기면 요청 요금은 계속 청구되지만 결과는 사라집니다. 이 모델에는 넉넉한 타임아웃을 설정하세요. 이미지 API 필수 사항 및 모범 사례를 참조하세요.
Nano Banana Pro(코드명)는 Google의 이미지 생성 모델 시리즈로, 현재 다음 버전을 사용할 수 있습니다.

​
최신 버전

  • Nano Banana 2.1: gemini-nano-banana-2.1 (🆕 2026년 10월 6일 출시, Nano Banana 2의 업그레이드 버전) — 세부 정보 보기
  • Nano Banana 2: gemini-3.1-flash-image (🔥 2026년 2월 26일 출시) — 세부 정보 보기
  • Nano Banana Pro: gemini-3-pro-image (2025년 11월 20일 출시)

​
이전 버전

  • 정식 출시 버전: gemini-2.5-flash-image (안정 버전, 10가지 종횡비 지원)
  • 미리보기 버전: gemini-2.5-flash-image-preview (⚠️ 2025년 10월 30일 지원 종료)
핵심 장점
  • 🔥 Nano Banana Pro의 새로운 기능:
    • 🎯 4K 고해상도 지원: 1K, 2K, 4K의 세 가지 해상도를 지원하며, 최대 4096×4096까지 지원합니다.
    • 📝 최고 수준의 텍스트 렌더링: 이미지에 선명하고 읽기 쉬운 텍스트를 표시하여 포스터와 광고에 적합합니다.
    • ✨ 부분 편집: 카메라 앵글, 초점, 색 보정, 장면 조명을 조정할 수 있습니다.
    • 🧠 스마트 추론: Gemini 3 Pro를 기반으로 복잡한 프롬프트를 더 잘 이해합니다.
  • 🚀 공통 장점:
    • ⚡ 생성 속도: Nano Banana Pro는 약 20초, 이전 버전은 약 10초가 소요됩니다.
    • 💰 합리적인 요금: 충전 보너스와 함께 이용하면 매우 경제적입니다.
    • 🔄 완벽한 호환성: Google 공식 Gemini API 형식과 완벽하게 호환됩니다.
    • 🎨 Google 기술: Google의 최신이자 가장 강력한 이미지 생성 및 편집 기술을 기반으로 합니다.

​
인터랙티브 API 테스트

텍스트-투-이미지 API

이미지를 생성하기 위한 텍스트 prompt를 입력합니다. 온라인 테스트를 위한 인터랙티브 Playground가 제공됩니다.

이미지 편집 API

편집된 이미지를 생성하기 위해 이미지 + 편집 지침을 업로드합니다. 온라인 테스트를 위한 인터랙티브 Playground가 제공됩니다.

​
AI 에이전트로 연동 구현하기

이 prompt를 복사하여 Codex / Claude Code / Cursor에 붙여넣으십시오

먼저 이 페이지의 일반 텍스트 버전을 가져온 후(모든 docs URL 끝에 .md 추가), 프로젝트의 자체 기술 스택에 맞춰 코드를 작성합니다. 타임아웃, 방어적인 parts 파싱, 업로드 압축 및 해상도 매개변수 처리가 이미 요구사항에 반영되어 있습니다.

이 프로젝트에서 Nano Banana Pro(gemini-3-pro-image) 텍스트-이미지 변환 및 이미지 편집 기능을 연동/트러블슈팅하십시오.

코드를 수정하기 전에 문서를 먼저 확인하십시오. 이 페이지의 일반 텍스트 버전인 https://docs.apiyi.com/en/api-capabilities/nano-banana-image/overview.md 를 가져오십시오. 더 자세한 매개변수 정보를 확인하려면 .md를 추가하십시오…

  1. 타임아웃: POST https://api.apiyi.com/v1beta/models/gemini-3-pro-image:generateContent의 Gemini 네이티브 포맷을 호출하십시오. 해상도별 클라이언트 타임아웃을 설정하십시오…

총 7가지 요구사항입니다. 아래 버튼을 사용하여 전체 prompt를 복사하십시오.

​
APIYI의 Nano Banana Pro를 선택해야 하는 이유는?

Nano Banana Pro / 2는 APIYI에서 사용량 기준 1위 모델입니다 — 안정적이고, 신뢰할 수 있으며, 빠릅니다. 전문 팀과 함께 작업하고 싶다면 APIYI가 올바른 선택입니다. 엄격한 콘텐츠 안전 제어를 갖춘 Google의 플래그십 모델로서, APIYI가 신뢰성, 비용, 통합 전반에서 최적화했습니다:

공식 채널 · Gemini와 동일

Google의 기본 Gemini API (/v1beta/models/.../generateContent)와 OpenAI SDK 패턴과 100% 호환됩니다 — 요청 본문, 응답 필드, 오류 코드가 동일합니다. 코드 수정 없이 마이그레이션할 수 있습니다.

동시 실행 수 제한 없음

Google AI Studio의 RPM/RPD 상한에 묶이지 않습니다. 엔터프라이즈 규모의 배치 생성과 피크 트래픽도 쿼터 중단 없이 선형적으로 확장됩니다.

Google 정가의 31-38%

$0.09/image per-call (vs Google 4K $0.24). 충전 보너스와 함께 사용하면 정가의 31.25%까지 낮아집니다 — 4K 절감액은 최대 68.75%입니다.

글로벌 무장벽 액세스

해외 서버나 프록시가 필요 없습니다 — 중국 본토 데이터 센터, 가정용 네트워크 또는 해외 노드에서 api.apiyi.com에 직접 연결할 수 있습니다. 안정적인 지연 시간, 국경 간 재구성 불필요.

전체 모델 라인업

같은 시리즈는 Nano Banana 2 (가성비 + Flash 속도), Nano Banana Pro (최고 품질), 그리고 기존 Nano Banana를 모두 포함합니다 — 시나리오에 따라 자유롭게 조합하세요.

전문 엔터프라이즈 지원

저희 팀은 프로덕션 이미지 생성 배포를 전문으로 하며, 모델 선택, 튜닝, 통합에 대한 깊은 경험을 갖추고 있습니다 — PoC부터 프로덕션까지 엔드투엔드 지원을 제공합니다.

​
호출 방법

Google의 기본 Gemini API 형식을 사용합니다.
  • ✅ 4K 고해상도 지원(1K / 2K / 4K)
  • ✅ 10가지 화면 비율 중 선택 가능
  • ✅ 업계 최고 수준의 텍스트 렌더링
  • ✅ 고급 로컬 편집
  • 📖 Google 공식 API 형식과 완벽하게 호환됩니다. 자세한 내용은 ai.google.dev/gemini-api/docs/image-generation을 참조하세요.

​
지원되지 않는 기능

다음 Google 공식 기능은 APIYI에서 지원되지 않으며 별도 과금이 필요합니다.
  • Google 검색을 통한 그라운딩: tools: [{"google_search": {}}]을 통해 실시간 검색 정보를 제공합니다.
  • thinkingConfig(사고 모드): Nano Banana 2에서만 지원되며 Nano Banana Pro에서는 지원되지 않습니다.
  • 이미지 검색 그라운딩: Nano Banana 2 전용 기능입니다.
그 외 모든 이미지 생성 및 편집 기능은 완벽하게 지원됩니다.

​
가격 비교

비용 대비 효과 추천:
  • Nano Banana Pro: 4K 지원, 가장 강한 텍스트 렌더링, 가격은 공식의 ~38-67% 수준입니다
  • NanoBananaEnterprise: 고가용성 요구사항을 위한 Enterprise HA 채널을 1.4배 요율($0.126/image)로 이용할 수 있습니다
  • Nano Banana: 빠른 생성(~10초), 공식 가격의 52% 수준으로, 일반적인 고품질 이미지 생성에 적합합니다

​
그룹 설정

Nano Banana Pro는 APIYI에서 두 그룹으로 제공됩니다. 대시보드 → 토큰 설정에서 전환하십시오: 왜 1.4x입니까? 1.4x에서도 가격은 Google 정가의 약 50% 수준으로, 공식 가격보다 훨씬 낮습니다. 이는 높은 동시 실행 수 워크로드와 예기치 않은 업스트림 리스크 제어 이벤트를 위한 대체 레인이며, 기업 고객에게 고가용성 보장을 제공합니다. 기본 그룹이 빡빡할 때는 token을 NanoBananaEnterprise로 전환하여 급증을 넘기십시오. 권장 과금 모델: Pay-as-you-go Priority를 선택하십시오 — Nano Banana Pro의 호출당 과금과 Nano Banana 2의 token 기반 과금을 모두 포함하며, 시리즈 전체에 대해 token 하나입니다.
토큰 생성 UI: 과금 모델 '종량제 우선순위'는 NB Pro 호출당 과금 + NB2 token 기반 과금을 포함합니다; 기본 그룹 Default + 대체 그룹 NanoBananaEnterprise (1.4x 레인)

Token settings: Billing model = Pay-as-you-go Priority, primary group = Default, fallback group = NanoBananaEnterprise (1.4x)

더 나아가: 토큰이 다른 이미지 모델(예: GPT-image-2)도 포함한다면, 더 안정적인 Default를 기본 그룹으로 두고 NanoBananaEnterprise을 대체 슬롯에 넣으십시오 — 기본 그룹의 429는 token 교체 없이 자동으로 엔터프라이즈 그룹으로 페일오버됩니다.

​
호환성 참고 사항

이전에 다음 모델을 사용한 적이 있다면 모델 이름만 바꾸면 됩니다.

​
최신 버전으로 업그레이드

  • 모든 이전 버전 → gemini-3-pro-image (🔥 권장, Nano Banana Pro)
    • 4K 고해상도 출력 지원
    • 가장 뛰어난 텍스트 렌더링 기능
    • 로컬 편집 기능

​
안정 버전 사용

  • gpt-4o-image → gemini-2.5-flash-image
  • sora_image → gemini-2.5-flash-image
  • 이전 Nano Banana → gemini-2.5-flash-image
원활하게 전환하려면 다른 매개변수는 그대로 유지합니다.

​
지원되는 해상도 및 종횡비

​
출력 해상도

Nano Banana Pro는 3개의 해상도 티어인 1K, 2K, 4K를 지원합니다(512px 티어는 Nano Banana 2 전용입니다).

​
종횡비별 출력 크기(픽셀)

아래 표는 Google 공식 문서를 기준으로 1K / 2K / 4K 해상도 티어 전반의 모든 10개 종횡비에 대한 Nano Banana Pro의 실제 출력 크기를 나열합니다. 요청에서는 비율에 aspect_ratio을, 티어에는 image_size(또는 resolution)을 설정합니다.
1:4, 4:1, 1:8, 8:1의 초세로/초가로 비율 또는 512px 저해상도 티어가 필요하면 Nano Banana 2를 사용하십시오(14개 종횡비 + 512px).

​
FAQ

가성비를 중시한다면 Nano Banana 2(gemini-3.1-flash-image)를 선택합니다.
  • Pro 수준의 품질과 Flash급 속도
  • 사용한 만큼 지불하며 이미지당 최저 $0.025
  • 14가지 종횡비(Pro보다 4가지 더 많음)
  • 독점 기능: 추론 모드, 이미지 검색 그라운딩
최고의 품질을 원한다면 Nano Banana Pro(gemini-3-pro-image)를 선택합니다.
  • 가장 높은 충실도
  • 요청당 $0.09
자세한 내용은 Nano Banana 2 문서를 참조하세요.
새 프로젝트에는 Nano Banana Pro를 권장합니다(gemini-3-pro-image).✅ Pro 버전의 장점:
  • 4K 초고해상도 지원(1K, 2K, 4K)
  • 업계 최고 수준의 텍스트 렌더링 품질
  • 고급 로컬 편집 기능
  • 공식 가격의 약 38~67%에 불과한 비용
⚡ 다음과 같은 경우 레거시 버전(gemini-2.5-flash-image)이 적합합니다.
  • 예산에 민감한 경우(이미지당 약 $0.025, Pro는 이미지당 $0.09)
  • 빠른 생성이 필요한 경우(10초, Pro는 20초)
  • 기존 프로젝트를 마이그레이션하는 경우
다른 매개변수는 그대로 두고 모델 이름을 gpt-4o-image 또는 sora_image에서 gemini-3-pro-image(권장 Pro) 또는 gemini-2.5-flash-image(레거시)로 변경하면 됩니다.
모델은 base64로 인코딩된 이미지 데이터를 반환하며, 일반적으로 PNG 또는 JPEG 형식입니다. 코드는 형식을 자동으로 감지하고 해당 파일 형식으로 저장합니다.
예. Nano Banana Pro는 이미지 생성과 편집을 모두 지원합니다. 이미지 편집 API 레퍼런스를 참조하세요.
전체 오류는 다음과 같습니다.
이 오류는 대개 이미지 업로드 용량이 너무 커서 발생합니다. 요청 본문이 지나치게 커지면 연결이 끊어집니다. 다음 모범 사례를 따르세요.
  • 이미지 수 제한: 공식 규정(프롬프트당 최대 이미지 14개)을 준수하고 참조 이미지를 지나치게 많이 추가하지 마세요.
  • 이미지당 용량 제한: 각 이미지를 5MB 미만으로 유지하세요. 공식 이미지당 최대 용량은 7MB이며, base64 인코딩 시 크기가 약 3분의 1만큼 증가하므로 여유를 두세요.
  • 업로드 전에 프런트엔드에서 압축: API로 보내기 전에 프런트엔드(또는 서버 측 릴레이)에서 이미지를 압축하세요. 일반적으로 가장 긴 변의 길이를 제한하고 JPEG/WebP로 변환한 다음 품질 매개변수를 조정합니다.
  • URL 입력으로 전환: Gemini 기본 형식에서는 fileData.fileUri를 통해 이미지 URL을 전달할 수 있으므로, 용량이 큰 base64 요청 본문을 완전히 피할 수 있습니다. Nano Banana 개발자 가이드를 참조하세요.

​
관련 문서