Nano Banana 2 이미지 생성/편집

개요

Nano Banana 2(코드명)는 2026년 2월 26일에 출시된 Google의 최신 이미지 생성 모델이며, 모델 ID는 gemini-3.1-flash-image입니다. Pro급 품질을 Flash급 속도와 비용으로 제공해 이미지 생성의 비용 효율성을 새롭게 정의하며, Nano Banana 시리즈의 최신 플래그십 모델입니다.

🔥 2026년 2월 26일 출시: Nano Banana 2를 사용할 수 있습니다! Pro급 품질, Flash급 속도, Google 가격의 최저 36%에 해당하는 token 기반 과금! 이미지당 $0.025부터 시작하는 512px! 4K 출력, 14가지 화면 비율, 이미지 검색 그라운딩 등 다양한 독점 기능을 지원합니다.

🆕 2026년 5월 29일 업데이트(-preview 출시): Google이 공식 문서를 업데이트하고 정식 모델 이름 gemini-3.1-flash-image(-preview 제외)을 공개했습니다. APIYI에서 이미 지원합니다.

이제 이 문서에서는 정식 이름 gemini-3.1-flash-image을 일관되게 사용합니다 — 새로 통합할 때 이 이름을 사용하세요.
기존 이름도 계속 사용할 수 있습니다: gemini-3.1-flash-image-preview은 이전처럼 계속 작동하며, 가격은 변경되지 않고 코드 변경도 필요하지 않습니다.

참고: Google은 정식 버전이 미리 보기 버전과 출력 품질, 안전 필터링 또는 기타 동작에서 차이가 있는지 아직 명확히 밝히지 않았습니다. 테스트해 보시고 의견을 공유해 주시기 바랍니다.

🆕 2026년 10월 6일: Nano Banana 2.1 출시(gemini-nano-banana-2.1). Google은 새 프로젝트에 2.1 사용을 권장합니다. 품질, 텍스트 렌더링 및 다중 턴 일관성이 개선되었으며, APIYI에서 요청당 $0.045입니다(10월 13일부터 $0.05에서 인하). Nano Banana 2도 동일한 가격으로 계속 사용할 수 있습니다. Nano Banana 2.1 이미지 생성/편집을 참조하세요.

모든 이미지 API는 동기식입니다 — 폴링할 작업 ID가 없으며, 요청에 대한 과금이 계속되는 동안 클라이언트의 연결이 끊기면 결과가 손실됩니다. 이 모델에는 충분히 긴 타임아웃을 설정하세요. 이미지 API 핵심 사항 및 모범 사례를 참조하세요.

텍스트-이미지 API

텍스트 prompt를 사용해 이미지를 생성합니다. 온라인 테스트를 위한 대화형 플레이그라운드가 포함되어 있습니다.

이미지 편집 API

이미지와 편집 지침을 업로드해 새 이미지를 생성합니다. 대화형 플레이그라운드가 포함되어 있습니다.

AI 에이전트로 연동 진행하기

이 prompt를 복사하여 Codex / Claude Code / Cursor에 붙여넣으세요

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

Integrate / troubleshoot Nano Banana 2 (gemini-3.1-flash-image) text-to-image and image editing in this project.

Read the docs before you touch code: fetch https://docs.apiyi.com/en/api-capabilities/nano-banana-2-image/overview.md for the plain-text version of this page. For finer parameter detail, append …

Timeout: call the Gemini-native format at POST https://api.apiyi.com/v1beta/models/gemini-3.1-flash-image:generateContent and raise the client timeou …

총 7개의 요구사항이 있습니다. 아래 버튼을 사용하여 전체 prompt를 복사하세요.

이 prompt로 방지할 수 있는 문제

요구사항	방지할 수 있는 문제
`parts` 인덱스를 절대 하드코딩하지 않음	길이와 순서가 보장되지 않으므로 고정된 인덱스는 간헐적으로 실패합니다. 이 모델은 추론 텍스트를 반환하여 이미지가 인덱스 1로 밀려나기 쉽습니다. Nano Banana Developer Guide를 참조하세요
마지막 이미지 part 선택	복잡한 편집 작업은 여러 중간 초안을 반환하며, 마지막 초안만 최종본입니다
항상 `imageSize` 전송	종량제 과금 체계에서는 해상도가 단가를 직접 결정하므로 기본값에 의존하면 비용을 예측하기 어렵습니다
`-4k` 접미사가 없는 모델 이름 사용	접미사가 붙은 이름은 채팅 클라이언트용이며, API 호출은 기본 이름일 때 더 안정적입니다
업로드 전 압축	이미지당 최대 한도는 7MB이며 base64 인코딩 시 대략 3분의 1 정도 증가합니다. Image Compression & Output Resolution을 참조하세요
`IMAGE_SAFETY` 발생 시 자동 재시도	검열 차단은 이미지가 없는 200 상태 코드를 반환하며 과금되지 않습니다. 동일한 요청으로 재시도하면 통과하는 경우가 많습니다. Gemini Image Error Handling을 참조하세요

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

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 정가의 28-36%

$0.055/image 호출당 (대비 Google $0.151), 512px는 token 기반으로 $0.025/image부터(대비 $0.045). 충전 보너스와 함께 적용하면 정가의 30.3% 수준까지 내려갑니다.

글로벌 무장벽 접근

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

전체 모델 라인업

동일한 시리즈는 Nano Banana Pro(최고 품질), Nano Banana 2(최고 가성비), 그리고 레거시 Nano Banana를 모두 포함합니다 — 시나리오에 따라 조합해 사용할 수 있습니다.

전문 엔터프라이즈 지원

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

핵심 기능

프로 수준 품질

생생한 조명, 풍부한 질감, 선명한 디테일 - 훨씬 더 빠른 속도로 Nano Banana Pro에 견줄 만한 품질

4K 울트라 HD 출력

512px, 1K, 2K, 4K 해상도를 지원하며, 최대 4096×4096까지 가능합니다

14개 화면 비율

새로 추가된 항목: 1:4, 4:1, 1:8, 8:1 - 총 14개 화면 비율로 더 많은 사용 사례를 포괄합니다

이미지 검색 그라운딩

Nano Banana 2 전용 - Google Image Search에서 시각적 컨텍스트를 가져옵니다

정확한 텍스트 렌더링

다국어 지원이 포함된 이미지 내 선명하고 읽기 쉬운 텍스트 - 포스터와 마케팅 자료에 적합합니다

멀티턴 편집

채팅을 통해 반복적으로 다듬는 대화형 이미지 편집

추론 모드

최소 또는 높은 추론 수준을 설정할 수 있어 더 정밀하게 복잡한 prompt를 처리합니다

주제 일관성

최대 5개 캐릭터와 14개 참조 객체에 걸쳐 유사성을 유지합니다

버전 비교

기능	Nano Banana 2	Nano Banana 2.1	Nano Banana Pro	Nano Banana
모델 ID	`gemini-3.1-flash-image`	`gemini-nano-banana-2.1`	`gemini-3-pro-image`	`gemini-2.5-flash-image`
품질	⭐⭐⭐⭐⭐ Pro급	⭐⭐⭐⭐⭐ 더 우수	⭐⭐⭐⭐⭐ 최고	⭐⭐⭐⭐ 우수
속도	🚀 가장 빠름	🚀 빠름	🐢 더 느림	⚡ 빠름
최대 해상도	4K	4K (512px 미지원)	4K	1K
화면 비율	14	14	10	10
이미지 검색 그라운딩	✅ 독점	✅	❌	❌
APIYI 가격	$0.055/이미지 (호출당)	$0.045/이미지	$0.09/이미지	$0.02/이미지
상태	미리보기	정식 출시	미리보기	정식 출시

선택 가이드:

🔥 가성비 최고 → Nano Banana 2 (token 기반 $0.025/이미지부터, Pro급 품질 + Flash급 속도)
🎨 최고 품질 → Nano Banana Pro ($0.09/이미지, 가장 높은 충실도)
⚡ 최저 비용 → Nano Banana ($0.025/이미지, 빠르고 안정적)

과금

과금 방식 선택: Nano Banana 2는 두 가지 과금 방식을 지원하며, API token을 생성할 때 “과금 모델” 설정에서 선택할 수 있습니다.

종량제 또는 종량제 우선 처리 선택 → token 기반 과금
요청당 과금 또는 요청당 과금 우선 처리 선택 → 호출당 과금(Nano Banana Pro와 동일)
⚠️ 하이브리드 과금은 선택하지 마세요

호출당 과금

모델	APIYI 요금	Google 공식 4K	할인
Nano Banana 2 `gemini-3.1-flash-image`	$0.055/이미지	$0.151/이미지	🔥 약 64% 할인
Nano Banana Pro `gemini-3-pro-image`	$0.09/이미지	$0.24/이미지	약 63% 할인
Nano Banana `gemini-2.5-flash-image`	$0.02/이미지	$0.039/이미지(1K만 해당)	약 50% 할인

엔터프라이즈 고가용성 채널: NanoBananaEnterprise는 표준 Nano Banana Pro 요금의 1.4배($0.126/이미지)로 제공되며, 엔터프라이즈 워크로드를 위한 전용 고가용성 대체 경로를 제공합니다.

token 기반 과금(Nano Banana 2 전용)

과금 항목	Google 공식	APIYI	할인
입력	$0.50/M tokens	$0.18/M tokens	36%
출력(이미지와 텍스트 통합)	이미지 $60/M, 텍스트 $1.5/M	$21.6/M tokens	36%

token 기반 과금 가격 예상치

해상도	Google 공식	APIYI	Fal AI
512px	$0.045	~$0.025	$0.06
1K	$0.067	~$0.035	$0.08
2K	$0.101	~$0.045	$0.12
4K	$0.151	~$0.07	$0.16

💰 token 기반 과금으로 더 많이 절약하세요! token 기반 과금을 이용하면 512px 이미지를 단 $0.025부터 생성할 수 있어 Google 요금의 36%에 불과합니다! 저해상도 사용 사례에서는 호출당 과금($0.055/이미지)보다 훨씬 저렴합니다. 4K에서는 token 기반 요금(~$0.07)이 호출당 과금보다 더 저렴하며, 두 방식 모두 Google 공식 요금인 $0.151/이미지보다 훨씬 낮습니다. 충전 보너스까지 적용하면 실제 비용은 더 낮아집니다.

과금에 영향을 주는 세 가지 파라미터

아래 수치는 2026-08-27에 운영 게이트웨이를 대상으로 한 실측 테스트에서 나온 것입니다(조건당 12–20회 실행, 모두 추정치가 아니라 콘솔에 기록된 실제 과금을 기준으로 함). 귀하의 과금액에 미치는 영향은 두 자릿수 규모로 다르므로, 표시된 순서대로 최적화하십시오.

Parameter	호출당 영향	조정할 가치가 있습니까?
`imageConfig.imageSize`	1K $0.033 → 4K $0.064, +90%	✅ 가장 큰 레버
`thinkingConfig.thinkingLevel`	기본값 $0.033 → `high` $0.052, +54%	✅ 필요할 때만 활성화
`responseModalities`	−2.8%, 통계적으로 유의하지 않음	❌ 절감 효과 없음

thinkingLevel: 기본값도 이미 최소이며, 높음은 비용이 절반 더 듭니다

gemini-3.1-flash-image는 thinking-level 제어를 지원합니다(Pro는 지원하지 않습니다). 동일한 prompt, 각 20회 실행:

설정	평균 output tokens	`thoughtsTokenCount`	호출당 과금	지연 시간 중앙값
생략됨(기본값)	1548.7	필드 없음	$0.0335	13.3s
`minimal`	1546.0	필드 없음	$0.0334	13.6s
`high`	1557.5	중앙값 784.5	$0.0516	20.7s

기본값은 minimal와 동일합니다 — 통계적으로 구분되지 않으므로(p=0.64), minimal를 명시적으로 전달해도 얻는 것이 없습니다.
high에서만 thoughtsTokenCount가 별도 필드로 나타나며, 이는 completion_tokens에 통합되어 이미지 요율로 과금됩니다.
복잡한 prompt는 high가 켜졌을 때만 더 비싸집니다: 기본 수준에서는 3-token prompt와 98-token 추론 prompt 사이에 output tokens 차이가 유의미하지 않았으며(p=0.37), high를 사용하면 추론 prompt가 126% 더 많은 생각 tokens를 사용했고 호출당 비용도 38% 더 높았습니다.

일상적인 생성에서는 이 파라미터를 그대로 두십시오. 구도 로직, 이미지 내 텍스트 배치, 또는 차트 비율 정확도에 대한 엄격한 요구가 있을 때만 high을 활성화하십시오. 그 대가로 지출이 +54%, 지연 시간이 +55% 증가합니다.

Google Search 그라운딩: 작동하지만 검색 쿼리마다 과금됩니다

실시간 정보가 정확해야 하는 이미지(날씨 카드, 시장 차트, 이벤트 포스터)에는 googleSearch 도구를 추가하십시오. 그라운딩은 12/12회 실행에서 발생했습니다.

{
  "contents": [{ "parts": [{ "text": "A weather card poster for Tokyo today" }] }],
  "tools": [{ "googleSearch": {} }]
}

출력 tokens는 거의 영향을 받지 않습니다(검색 수수료를 제외하면 도구 없는 대조군 대비 −2.1%, 유의하지 않음). 전체 비용은 검색 호출 자체에서 발생하며, 각 호출당 $0.014입니다.

조건	그라운딩 발생	검색 쿼리 중앙값	호출당 과금
도구 없음	0/12	0	$0.036
`googleSearch: {}`	12/12	2	$0.062 (+73%)

모델이 몇 번 검색할지 결정하며, 미리 설정할 수 없습니다. 테스트에서는 단일 이미지 요청이 스스로 1–3개의 쿼리를 발생시켰으므로, 이 도구를 켠 상태의 호출당 비용은 고정값이 아니라 $0.050–$0.078 범위입니다. 상한을 기준으로 예산을 잡으십시오.

Image Search 그라운딩: Nano Banana 2 전용이며, 현재는 무료입니다

searchTypes.imageSearch는 모델이 Google Image Search에서 시각적 참조를 가져오게 해 주며, “실제 사진으로 콜라주를 만들어라” 또는 “실제 물체를 그대로 그려라” 같은 작업에 유용합니다.

{
  "tools": [{ "googleSearch": { "searchTypes": { "imageSearch": {} } } }]
}

조건	그라운딩 발생	부과된 검색 수수료	호출당 과금
도구 없음	0/12	0/12	$0.036
`imageSearch`만	7/12	0/12	$0.032

imageSearchQueries가 groundingMetadata에 나타나며 ["current weather in Tokyo"] 같은 값이 확인되었습니다.
현재는 추가 과금이 없습니다 — 호출당 비용이 오히려 도구 없는 대조군보다 약간 낮게 나오기도 했습니다.
12회 중 7회에서 발생했습니다. 검색 여부는 모델이 결정하며, 매번 쿼리하지는 않습니다.
웹 검색과 이미지 검색은 함께 활성화할 수 있지만, 무엇을 사용할지는 모델이 선택하므로 비용은 예측하기 어려워집니다.

searchTypes는 배열이 아니라 객체여야 합니다.✅ {"searchTypes": {"imageSearch": {}}} — 작동함❌ {"searchTypes": ["imageSearch"]} — 오류는 없고, 200을 반환하며, 이미지도 나오지만, 이미지 검색은 한 번도 발생하지 않습니다. 응답 본문 어디에도 그 사실이 드러나지 않습니다. 배열 형식에 대한 상위 오류는 Proto field is not repeating, cannot start list입니다.

responseModalities: 아무것도 절약하지 못하지만 원치 않는 텍스트를 제거합니다

responseModalities: ["IMAGE"]는 이미지뿐 원한다고 선언합니다. 각 20회 실행:

설정	평균 output tokens	호출당 과금
생략됨(기본값)	1548.7	$0.0335
`["IMAGE"]`	1535.0	$0.0332
`["TEXT","IMAGE"]`	1542.8	$0.0333

세 값은 모두 서로 1% 이내이며, ["TEXT","IMAGE"]는 필드를 생략한 것과 정확히 동일합니다(p=0.90).
일반적인 생성 prompt에서는 60/60개의 응답이 이미 단일 이미지 파트만 포함하고 텍스트는 전혀 없었으므로, 모달리티 전환이 작동할 대상이 없습니다. 추론 prompt(인포그래픽, 데이터 차트)만 약 3분의 1 정도의 경우 요약 문단을 붙이는데, 그 경우 ["IMAGE"]가 이를 억제하고 약 **2.8%**를 절감합니다(p=0.09, 유의하지 않음).

절감할 것이 없는 이유: output tokens는 “image + text”가 아니라 이미지용 1120개와 약 400개의 보이지 않는 오버헤드 tokens입니다. 그 오버헤드는 candidatesTokensDetails의 어떤 필드에도 나타나지 않지만, 전체 요율로 과금되며 호출당 과금의 28%를 차지하고, prompt 길이와도 무관합니다. 텍스트 비용은 이에 비하면 미미합니다.따라서 1120 tokens만으로 이미지당 비용을 추정하면 약 28% 과소평가하게 됩니다. 대신 candidatesTokenCount 또는 totalTokenCount와 대조하여 확인하십시오.

그룹 설정

Nano Banana 2는 APIYI에서 두 개의 그룹과 함께 제공됩니다. 대시보드에서 전환 → Token 설정:

그룹	요율	사용 시점
`Default`	1.0x	기본 레인, 가격표와 일치합니다; 권장 기본값
`NanoBananaEnterprise`	1.4x	대체 레인 — 기본 경로가 빡빡하거나 타임아웃이 급증할 때 수동으로 전환합니다, 용량 우선

왜 1.4x입니까? 1.4x여도 가격은 여전히 Google의 정가의 약 50% 수준이며 — 공식 가격보다 훨씬 낮습니다. 이는 더 높은 동시 실행 수 워크로드와 예상치 못한 상위 공급자 위험 제어 이벤트를 위한 대체 레인으로, 엔터프라이즈 고객에게 고가용성 보장을 제공합니다. 기본 그룹이 빡빡할 때는 Token을 NanoBananaEnterprise로 전환하여 급증을 넘기십시오. 권장 과금 모델: Pay-as-you-go Priority을 선택하십시오 — Nano Banana 2의 token 기반 과금과 Nano Banana Pro의 호출당 과금을 모두 지원하며, 시리즈 전체에 Token 하나입니다.

Token 생성 UI: 과금 모델 '종량제 우선'은 NB2 token 기반 + NB Pro 호출당 과금을 지원하며; 기본 그룹 Default + 대체 그룹 NanoBananaEnterprise (1.4x 레인) — Token settings: Billing model = Pay-as-you-go Priority, primary group = Default, fallback group = NanoBananaEnterprise (1.4x)

더 나아가서: Token이 다른 이미지 모델(예: GPT-image-2)도 포괄한다면, 더 안정적인 Default을 기본 그룹으로 유지하고 NanoBananaEnterprise을 대체 슬롯에 넣으십시오 — 기본 그룹의 429는 token 교체 없이 자동으로 엔터프라이즈 그룹으로 장애 조치됩니다.

지원되는 해상도 및 종횡비

출력 해상도

해상도	설명	권장 사용처
512px	저해상도	썸네일, 빠른 미리보기
1K	기본	소셜 미디어, 웹 표시
2K	고화질	HD 디스플레이, 인쇄물
4K	초고화질	전문 디자인, 상업용 포스터

지원되는 종횡비(총 14개)

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

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

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

종횡비	512px	1K	2K	4K
1:1	512×512	1024×1024	2048×2048	4096×4096
1:4	256×1024	512×2048	1024×4096	2048×8192
1:8	192×1536	384×3072	768×6144	1536×12288
2:3	424×632	848×1264	1696×2528	3392×5056
3:2	632×424	1264×848	2528×1696	5056×3392
3:4	448×600	896×1200	1792×2400	3584×4800
4:1	1024×256	2048×512	4096×1024	8192×2048
4:3	600×448	1200×896	2400×1792	4800×3584
4:5	464×576	928×1152	1856×2304	3712×4608
5:4	576×464	1152×928	2304×1856	4608×3712
8:1	1536×192	3072×384	6144×768	12288×1536
9:16	384×688	768×1376	1536×2752	3072×5504
16:9	688×384	1376×768	2752×1536	5504×3072
21:9	792×168	1584×672	3168×1344	6336×2688

Nano Banana Pro의 10개 종횡비와 비교하면, Nano Banana 2는 1:4, 4:1, 1:8, 8:1를 추가합니다. 이는 장형 이미지와 인포그래픽에 이상적인 초세로/초가로 비율입니다. 또한 512px 저해상도 티어를 제공하는 유일한 모델로, 썸네일과 빠른 미리보기에 매우 적합합니다.

FAQ

Nano Banana 2와 Nano Banana Pro의 차이점은 무엇인가요?

Nano Banana 2 (gemini-3.1-flash-image)는 Gemini 3.1 Flash를 기반으로 하고, Nano Banana Pro (gemini-3-pro-image)는 Gemini 3 Pro를 기반으로 합니다. 주요 차이점은 다음과 같습니다.

✅ 속도: Nano Banana 2가 더 빠릅니다(Flash급 속도).
✅ 가격: Nano Banana 2의 token 기반 과금이 더 저렴합니다($0.025부터 시작하며, Nano Banana Pro는 $0.09부터 시작).
✅ 화면 비율: Nano Banana 2는 14가지를 지원합니다(4가지 더 많음).
✅ 이미지 검색 그라운딩: Nano Banana 2 전용 기능입니다.
⚠️ 최고 품질: Nano Banana Pro가 여전히 약간 더 우수합니다.

Nano Banana Pro에서 Nano Banana 2로 전환하는 것이 좋을까요?

권장합니다! Nano Banana 2는 더 빠른 속도와 저렴한 가격으로 Pro에 가까운 품질을 제공합니다. 아주 높은 품질이 필요한 경우가 아니라면 Nano Banana 2가 더 나은 선택입니다.모델 이름을 gemini-3-pro-image에서 gemini-3.1-flash-image로 변경하기만 하면 됩니다.

gemini-3.1-flash-image를 사용해야 하나요, 아니면 -4k 접미사가 붙은 버전을 사용해야 하나요?

코드/API 호출에는 gemini-3.1-flash-image(-4k 접미사 없음) 일반 모델 이름을 사용하는 것을 권장하며, gemini-3.1-flash-image-4k은 사용하지 않는 것이 좋습니다.

공식 이름에는 -4k가 없습니다: Google의 공식 모델 이름은 gemini-3.1-flash-image입니다. 이 이름은 유지 관리를 위해 가장 많은 리소스를 투입하는 일반 채널이기도 하므로, 안정성과 호환성이 가장 뛰어납니다.
-4k의 출처: gemini-3.1-flash-image-4k는 원래 Chatbox와 같은 대화형 클라이언트의 “채팅에서 이미지 생성” 시나리오, 즉 메시지 UI에서 채팅을 통해 이미지를 바로 생성하는 용도로 준비된 설정이었습니다.
코드와 Gemini 기본 형식에는 일반 이름이 적합합니다: Gemini 기본 형식(/v1beta/models/.../generateContent)으로 코드를 통해 호출하는 경우 일반 모델 이름인 gemini-3.1-flash-image이 더 안정적입니다.

4K 출력을 원할 때 -4k 모델 이름을 사용할 필요는 없습니다. 요청 매개변수에서 4K 해상도를 지정하면 됩니다(위의 “지원 해상도 및 화면 비율” 참고).

이미지 검색 그라운딩이란 무엇인가요?

이미지 검색 그라운딩은 Nano Banana 2 전용 기능입니다. Google 이미지 검색에서 시각적 맥락을 가져와 실제 대상과 더 잘 어울리는 이미지를 생성합니다. 예를 들어 실제 랜드마크 이미지를 생성할 때 검색 결과를 참고해 정확도를 높일 수 있습니다.

추론 모드는 어떤 기능인가요?

추론 모드를 사용하면 모델이 이미지를 생성하기 전에 추론하고 분석하여 복잡한 prompt의 정확도를 높일 수 있습니다. high로 설정하면 최상의 결과를 얻을 수 있지만 생성 시간이 약간 늘어납니다. 정밀한 구도, 텍스트 렌더링 또는 복잡한 장면이 필요한 작업에 적합합니다.

이미지를 생성하는 데 얼마나 걸리나요?

생성 시간은 해상도와 추론 모드에 따라 달라집니다.

1K 해상도: 약 5~10초
2K 해상도: 약 10~15초
4K 해상도: 약 15~25초
높은 추론 모드를 활성화하면 몇 초 더 걸립니다.

간헐적인 지연과 혼잡 시간대에 대비해 타임아웃을 더 길게(최소 360초) 설정하는 것을 권장합니다.

동시 실행 수 제한이 있나요? API가 순차적으로 처리되나요? 20명의 사용자가 동시에 호출해야 한다면 어떻게 해야 하나요?

API에는 동시 실행 수 제한이 없으며 요청을 순차적으로 처리하지도 않습니다. 직접 안심하고 요청을 동시에 보낼 수 있습니다. 요청은 대기열에 들어가거나 서로 차단하지 않습니다. 20명의 사용자가 동시에 호출하는 경우, 요청 20개를 동시에 보내면 됩니다. 추가 쿼터 요청이나 속도 제한은 필요하지 않습니다.Google AI Studio와 달리 APIYI 채널에는 엄격한 RPM/RPD 제한이 없으므로 엔터프라이즈 일괄 생성과 최대 트래픽도 선형적으로 확장됩니다.실제로 중요한 것은 timeout입니다: 이미지 생성은(특히 4K이거나 혼잡 시간대인 경우) 요청마다 시간이 걸릴 수 있으므로, 정상적으로 처리 중인 요청이 중단되지 않도록 클라이언트 타임아웃을 360초로 설정하세요.

간혹 429(동시 실행 수가 높아 제한됨) 오류가 발생하면 token에 NanoBananaEnterprise을 대체 그룹으로 추가하세요(위의 “그룹 설정” 참고). 기본 그룹이 포화되면 자동으로 대체 그룹으로 전환되어 동시 실행 수가 높은 상황에서 성공률을 더 높일 수 있습니다.

어떤 입력 이미지 형식을 지원하나요?

image/png 및 image/jpeg 형식을 지원합니다. 인라인 base64로 전달하거나 fileData.fileUri을 통해 공개 이미지 URL을 전달하세요. 플랫폼은 Files API 업로드를 지원하지 않습니다. APIYI는 Files API를 지원하나요?를 참고하세요.

출력 이미지에 워터마크가 있나요?

모든 출력 이미지에는 SynthID 비가시 디지털 워터마크(Google의 AI 생성 콘텐츠 식별 기술)가 포함됩니다. 육안으로는 보이지 않으며 사용에 영향을 주지 않습니다.

connection reset by peer / write_response_body_failed (500) 오류가 발생하는 이유는 무엇인가요?

전체 오류는 다음과 같습니다.

[&{{write tcp ip:port->ip:port: write: connection reset by peer Unknown error shell_api_error  write_response_body_failed} 500 }]

이 오류는 대개 이미지 업로드 크기가 너무 커서 발생합니다. 요청 본문이 너무 커지면 연결이 끊어집니다. 다음 권장 사항을 따르세요.

이미지 개수 제한: 공식 기준( prompt당 최대 14개 이미지)을 지키고 참조 이미지를 너무 많이 넣지 마세요.
이미지당 크기 제한: 각 이미지의 크기를 5MB 미만으로 유지하세요. 공식 이미지당 최대 크기는 7MB이며, base64 인코딩 시 크기가 약 1/3 증가하므로 여유를 두어야 합니다.
업로드 전에 프런트엔드에서 압축: API로 전송하기 전에 프런트엔드(또는 서버 측 릴레이)에서 이미지를 압축하세요. 일반적으로 가장 긴 변의 크기를 제한하고, JPEG/WebP로 변환한 뒤 품질 매개변수를 조정합니다.
URL 입력으로 전환: Gemini 기본 형식은 fileData.fileUri을 통해 이미지 URL을 전달할 수 있으므로, 크기가 너무 큰 base64 요청 본문을 완전히 피할 수 있습니다. Nano Banana 개발자 가이드를 참고하세요.

​개요

텍스트-이미지 API

이미지 편집 API

​AI 에이전트로 연동 진행하기

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

공식 채널 · Gemini와 동일

동시 실행 수 제한 없음

Google 정가의 28-36%

글로벌 무장벽 접근

전체 모델 라인업

전문 엔터프라이즈 지원

​핵심 기능

프로 수준 품질

4K 울트라 HD 출력

14개 화면 비율

이미지 검색 그라운딩

정확한 텍스트 렌더링

멀티턴 편집

추론 모드

주제 일관성

​버전 비교

​과금

​호출당 과금

​token 기반 과금(Nano Banana 2 전용)

​token 기반 과금 가격 예상치

​과금에 영향을 주는 세 가지 파라미터

​thinkingLevel: 기본값도 이미 최소이며, 높음은 비용이 절반 더 듭니다

​Google Search 그라운딩: 작동하지만 검색 쿼리마다 과금됩니다

​Image Search 그라운딩: Nano Banana 2 전용이며, 현재는 무료입니다

​responseModalities: 아무것도 절약하지 못하지만 원치 않는 텍스트를 제거합니다

​그룹 설정

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

​출력 해상도

​지원되는 종횡비(총 14개)

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

​FAQ

​관련 문서

개요

AI 에이전트로 연동 진행하기

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

핵심 기능

버전 비교

과금

호출당 과금

token 기반 과금(Nano Banana 2 전용)

token 기반 과금 가격 예상치

과금에 영향을 주는 세 가지 파라미터

thinkingLevel: 기본값도 이미 최소이며, 높음은 비용이 절반 더 듭니다

Google Search 그라운딩: 작동하지만 검색 쿼리마다 과금됩니다

Image Search 그라운딩: Nano Banana 2 전용이며, 현재는 무료입니다

responseModalities: 아무것도 절약하지 못하지만 원치 않는 텍스트를 제거합니다

그룹 설정

지원되는 해상도 및 종횡비

출력 해상도

지원되는 종횡비(총 14개)

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

FAQ

관련 문서