Nano Banana
Nano Banana Pro와 Flash의 제한, 네 가지 극단 화면 비율, 그리고 무료 relax 통로.
Nano Banana는 ListenHub에서 쓰는 Google의 이미지 모델 시리즈입니다. 디테일을 위한
gemini-3-pro-image(Nano Banana Pro)와 속도를 위한 gemini-3.1-flash-image(Nano Banana Flash)가
있습니다. 둘 다 공유 이미지 엔드포인트에서 동작합니다. 엔드포인트, 요청 스키마, 비동기 흐름, 에러
코드는 이미지 생성 개요를 참고하세요. 이
페이지는 Nano Banana 전용 내용만 다룹니다.
모델
| 모델 | 표시 이름 | 적합한 용도 |
|---|---|---|
gemini-3-pro-image | Nano Banana Pro | 전체 모델 목록 중 가장 세밀한 출력 |
gemini-3.1-flash-image | Nano Banana Flash | 더 빠르고 저렴한 생성, Nano Banana 중 극단 비율을 받는 유일한 등급 |
둘 다 provider: "google"을 사용합니다. 프리뷰 ID인 gemini-3-pro-image-preview와
gemini-3.1-flash-image-preview도 계속 받으며, 위의 GA ID로 정규화됩니다.
제한
| 제한 항목 | gemini-3-pro-image | gemini-3.1-flash-image |
|---|---|---|
| 이미지 크기 | 1K, 2K, 4K | 1K, 2K, 4K |
| 화면 비율 | 표준 10종 비율 | 네 가지 극단 비율을 포함한 14종 전부 |
| 기본 화면 비율 | 1:1(스키마 기본값) | 1:1(스키마 기본값) |
| 참조 이미지 | 최대 14장 | 최대 14장 |
quality | 무시됨 | 무시됨 |
이 시리즈 안에서 1:4, 4:1, 1:8, 8:1은 Flash 전용입니다 — gemini-3-pro-image로 보내면
code: 29003과 함께 400이 반환됩니다. Nano Banana에서 비율이 거부될 때는 항상 29003이며,
GPT-Image와 Wan 2.7이 쓰는 26019가 아닙니다.
두 모델 모두 시리즈 수준의 참조 이미지 상한을 선언하지 않으므로, 스키마 전체 상한인 14개가 실질적인 상한이 됩니다 — 전체 모델 목록 중 가장 높은 값입니다.
극단 비율
표준 비율 집합으로는 표현할 수 없는 배너, 세로 스트립, 파노라마를 위해 네 가지 비율이 있습니다.
| 비율 | 형태 | 대표 용도 |
|---|---|---|
1:4 | 좁은 세로 | 사이드바 이미지, 세로 스트립 |
4:1 | 넓은 가로 | 페이지 배너, 헤더 |
1:8 | 극단적 세로 | 세로로 긴 스크롤 패널 |
8:1 | 파노라마 | 와이드 파노라마, 푸터 스트립 |
Nano Banana 안에서는 Flash 전용입니다. 이 시리즈 밖에서는 seedream-5-0-pro도 이 비율들을 받는데,
비율이 아니라 크기로 검증하기 때문입니다.
무료 할당량
두 모델 모두 각자의 무료 할당량 리소스가 있으며, 1K와 2K에서만 사용할 수 있습니다 — 4K 요청은
항상 크레딧으로 과금됩니다. 할당량을 적립하고 잔액을 조회하는 방법은
개요에 있습니다.
| 모델 | 무료 할당량 리소스 |
|---|---|
gemini-3-pro-image | gemini-3-pro-image-relax-1k-2k |
gemini-3.1-flash-image | gemini-3.1-flash-image |
relax 통로
gemini-3-pro-image는 전체 모델 목록 중 무료 할당량이 별도 실행 통로에서 돌아가는 유일한
모델입니다. 어떻게 실행되는지는 계정 유형에 따라 달라집니다.
- 한 번이라도 결제한 적 있는 계정(활성 구독, 충전, 크레딧 팩 구매)은 무료 할당량을 쓰는 중에도 온전한 우선순위, 정상 용량, 정상 폴백을 유지합니다 — 무료 할당량은 과금만 바꿀 뿐, 실행되는 통로를 바꾸지 않습니다.
- 순수 무료 계정(한 번도 결제한 적 없음)은 고정 처리량 상한이 걸린 최저 우선순위 무료 통로에서 실행됩니다. 피크 시간대에는 요청이 대기열에 들어가거나 재시도 가능한 busy/timeout 응답과 함께 거부될 수 있습니다. 그럴 때는 크레딧도 소비되지 않고 무료 할당량도 소모되지 않으므로 나중에 다시 시도하세요.
순수 무료 relax 실패는 현지화된 텍스트를 파싱하지 않고도 감지할 수 있도록 기계 판독 가능한 메타데이터를 반환합니다.
failReason은free_relax_busy또는free_relax_timeout입니다.retryable은true입니다.- 무료 할당량이 환불되면
freeUsageRolledBack이true가 됩니다. userMessage에는 친절하고 현지화 가능한 문구가 담기며, 이는 동기 오류 응답 본문에 나타납니다. 비동기 작업 객체는 같은 문구를failUserMessage로 노출합니다. 두 표면은 필드 이름이 다르므로, 두 경로를 모두 처리한다면 둘 다 읽으세요.
동기 요청에서는 오류 응답 본문에, 비동기 요청에서는 실패한 작업 상세(및 작업 목록)에 나타납니다. 두 사유 모두 "나중에 재시도, 아무것도 과금되지 않음"으로 처리하세요.
요금
두 모델 모두 이미지 크기별 고정 크레딧 비용으로 과금되며(pricing.mode는 fixed), 둘 다
requiresSubscription을 설정하지 않습니다. 4K는 2K보다, 2K는 1K보다 비쌉니다. 값을
하드코딩하지 말고 모델과 크기를 넣어
POST /v1/images/generation/estimate-credits를
호출해 정확한 수치를 확인하세요.
예시
curl -X POST "https://api.marswave.ai/openapi/v1/images/generation/async" \
-H "Authorization: Bearer $LISTENHUB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"provider": "google",
"model": "gemini-3.1-flash-image",
"prompt": "A panoramic mountain range at dawn, layered mist, muted palette",
"imageConfig": { "imageSize": "2K", "aspectRatio": "8:1" }
}'전체 파라미터 목록과 참조 이미지를 포함한 요청 구조는 이미지 생성 개요를 참고하세요.