Nano Banana 시리즈 - WideRouter Docs

Nano Banana는 Google의 이 이미지 모델 세대 시리즈명입니다. WideRouter에서 모델 ID는 공식 ID입니다 — 플랫폼별 별칭은 없으며, -preview 접미사가 붙은 이름은 허용되지 않습니다. 시리즈의 모든 모델은 동일한 요청 형식을 사용하므로, 모델 간 전환은 model을 한 단어만 변경하면 됩니다.

시리즈 한눈에 보기

	Nano Banana Pro	Nano Banana 2	Nano Banana
모델 ID	`gemini-3-pro-image`	`gemini-3.1-flash-image`	`gemini-2.5-flash-image`
비동기 작업 API	지원	지원	아직 사용 불가
동기 API	지원	지원	아직 사용 불가
해상도 등급	`1K` `2K` `4K`	`1K` `2K` `4K`	—
호출당 이미지 수(`n`)	1–4	1–4	—
참조 이미지	최대 14개	최대 14개	—
비동기, 1K, 평균	약 29초	약 20초	—
동기 왕복 시간, 1K	약 17초	약 13초	—

현재 gemini-2.5-flash-image는 어느 인터페이스에서도 라우팅되지 않습니다. 비동기 API는 제출 시 model_not_supported을 반환하며, 동기 엔드포인트는 과금 구성 오류를 반환합니다. 공식 ID를 조회했을 때 아무런 결과가 나오지 않는 대신 답을 확인할 수 있도록 여기에 나열했습니다. 플랫폼 측 문제가 해결되면 활성화될 예정입니다.

기본적으로 Nano Banana 2를 사용하십시오. 모든 해상도에서 의미 있게 더 빠르고 동일한 매개변수를 사용하므로 통합 과정에서 변경할 사항이 없습니다. 이미지당 약 10초를 더 기다릴 가치가 있을 만큼 추가 품질이 중요한 경우 Nano Banana Pro로 전환하십시오.

매개변수

모든 내용은 input 안에 들어갑니다. 이를 감싸는 엔벌로프인 model, input, callback_url에 대해서는 비동기 작업 API에 설명되어 있습니다. 이 다섯 필드가 전체 필드 집합입니다. input 내부의 다른 키는 모두 invalid_params와 함께 거부되므로, 오타가 무시되지 않고 즉시 오류가 발생합니다.

필드	유형	필수	범위	기본값
`prompt`	문자열	예	1–32000바이트	—
`n`	정수	아니요	1–4	1
`aspect_ratio`	문자열	아니요	화면 비율 참조	모델 자체 기본값
`image_size`	문자열[]	아니요	`1K` `2K` `4K`	`1K`
`images`	문자열[]	아니요	최대 14개 항목	없음

image_size은 대소문자를 구분합니다. 1K은 허용되지만 1k은 허용되지 않습니다. 비동기 API에는 512 등급이 없으며, 자유 형식 1024x1024 형식도 없습니다.

해상도 등급

image_size는 한쪽 가장자리를 고정하는 대신 전체 프레임의 크기를 조정하므로, 4K에서 와이드 이미지의 긴 가장자리는 4096픽셀을 훨씬 넘습니다. 측정 결과, 사용 가능한 두 모델에서 모두 동일했습니다.

`image_size`	`1:1`	`21:9`	대략적인 픽셀 수
`1K`	1024 × 1024	1584 × 672	1 MP
`2K`	2048 × 2048	—	4 MP
`4K`	4096 × 4096	6336 × 2688	17 MP

파일 크기도 이에 따라 1K에서는 약 0.4–0.7MB, 2K에서는 2.4–3.0MB, 4K에서는 7.5–8.2MB입니다. 출력은 항상 C2PA 콘텐츠 자격 증명 manifest를 포함하는 JPEG 형식입니다.

가로세로 비율

10개의 값을 사용할 수 있습니다. gemini-3-pro-image에서 1K을 기준으로 측정한 픽셀:

비율	픽셀	비율	픽셀
`1:1`	1024 × 1024	`4:5`	928 × 1152
`3:2`	1264 × 848	`5:4`	1152 × 928
`2:3`	848 × 1264	`9:16`	768 × 1376
`4:3`	1200 × 896	`16:9`	1376 × 768
`3:4`	896 × 1200	`21:9`	1584 × 672

모든 비율은 명목값의 1% 이내에 해당했습니다. aspect_ratio을 생략하면 텍스트 prompt는 1024 × 1024를 제공하며, images을 전달하면 출력이 대신 원본 이미지의 형태를 따릅니다.

편집 및 합성

images에 참조 이미지를 전달하여 편집하거나 해당 이미지를 기반으로 합성합니다. 각 항목은 https URL 또는 base64 데이터 URI 중 하나입니다. data-URI 접두사가 없는 일반 base64 문자열은 거부되며, 일반 http도 마찬가지입니다.

{
  "model": "gemini-3-pro-image",
  "input": {
    "prompt": "place the leaf from the second image leaning against the mug from the first",
    "images": [
      "https://your-bucket.example/mug.jpg",
      "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
    ]
  }
}

두 형식은 하나의 호출에서 자유롭게 혼합할 수 있으며, aspect_ratio, image_size 및 n도 모두 여전히 적용됩니다. 즉, 4K에서 편집해도 실제로 4096 × 4096 크기의 결과가 반환됩니다. URL은 작업이 수락된 후 서버 측에서 가져오므로, 잘못된 참조는 failed 작업을 생성하며 400이 생성되는 것이 아닙니다. 두 실패 코드는 어느 계층에서 처리가 중단되었는지 알려줍니다.

전달한 항목	`error.code`	실패까지 걸리는 시간
확인할 수 없는 호스트, 404 또는 인증이 필요한 URL	`input_fetch_error`	1초 미만
연결할 수 있지만 이미지가 아님(HTML, JSON)	`upstream_error`	약 4초

두 경우 모두 모델 작업이 시작되기 전에 실패하므로 빠르고 저렴하게 재시도할 수 있습니다.

지연 시간

비동기 수치는 동시 실행 수 12에서 30개 작업을 기준으로 하며, 동기 수치는 단일 호출을 기준으로 합니다. 이 수치는 서비스 수준의 보장이 아니라 대략적인 규모로 간주해야 합니다.

	Nano Banana Pro	Nano Banana 2
비동기 제출 호출	약 0.9초	약 0.9초
비동기 종단 간 처리, 1K	평균 약 29초	평균 약 20초
비동기 종단 간 처리, 4K	약 36–40초	약 41초
동기 왕복 시간, 1K	약 17초	약 13초

비동기 방식은 추가 왕복 시간으로 약 0.9초가 소요되지만, 나머지 20–40초 동안 연결을 유지하지 않아도 됩니다. 부하가 있는 상황에서 대기 시간은 0–11초였으며, 종단 간 처리 시간에 이미 포함되어 있습니다.

동기식 표면

사용 가능한 두 모델 모두에서 세 가지 동기식 형태를 사용할 수 있으며, 세 형태 모두 이미지를 URL이 아닌 인라인으로 반환합니다:

엔드포인트	이미지 위치
`POST /v1/images/generations`	`data[0].b64_json` 또는 `response_format`를 `url`으로 설정한 `data[0].url`입니다. `n`은 무시되며 호출당 이미지 하나만 반환됩니다.
`POST /v1/chat/completions`	메시지 콘텐츠 내부에 데이터 URI가 포함된 마크다운 이미지
`POST /v1beta/models/{model}:generateContent`	`inlineData` 부분의 `candidates[0].content.parts[]`

Gemini 네이티브 형태에서는 위치를 기준으로 parts의 인덱스를 지정하지 마십시오. 이는 길이와 순서가 보장되지 않는 이기종 배열입니다. 텍스트 부분이 먼저 올 수 있으며, 복잡한 편집에서는 여러 초안 이미지가 반환됩니다. inlineData을 포함하는 항목을 필터링하여 마지막 항목을 선택하고, 파일 확장자를 가정하는 대신 응답에서 mimeType을 읽으십시오.

다음 단계

플레이그라운드

이 페이지에서 실제 요청을 전송하고 작업 실행 과정을 확인합니다.

비동기 작업 API

엔벌로프, 폴링 루프, 콜백 및 오류 표를 확인합니다.

​시리즈 한눈에 보기

​매개변수

​해상도 등급

​가로세로 비율

​편집 및 합성

​지연 시간

​동기식 표면

​다음 단계

플레이그라운드

비동기 작업 API

시리즈 한눈에 보기

매개변수

해상도 등급

가로세로 비율

편집 및 합성

지연 시간

동기식 표면

다음 단계