> ## Documentation Index
> Fetch the complete documentation index at: https://docs.widerouter.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Nano Banana 시리즈
> WideRouter에서 Google의 이미지 생성 모델을 소개합니다. 어떤 ID가 어떤 인터페이스에서 작동하는지, 각 모델이 허용하는 모든 매개변수와 측정된 지연 시간을 확인할 수 있습니다.
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](/ko/api/async-tasks)에 설명되어 있습니다.
이 다섯 필드가 전체 필드 집합입니다. `input` 내부의 다른 키는 모두 `invalid_params`와 함께 거부되므로, 오타가 무시되지 않고 즉시 오류가 발생합니다.
| 필드 | 유형 | 필수 | 범위 | 기본값 |
| -------------- | ------ | --- | -------------------------- | --------- |
| `prompt` | 문자열 | 예 | 1–32000바이트 | — |
| `n` | 정수 | 아니요 | 1–4 | 1 |
| `aspect_ratio` | 문자열 | 아니요 | [화면 비율](#aspect-ratios) 참조 | 모델 자체 기본값 |
| `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`도 마찬가지입니다.
```json theme={null}
{
"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`을 읽으십시오.
## 다음 단계
이 페이지에서 실제 요청을 전송하고 작업 실행 과정을 확인합니다.
엔벌로프, 폴링 루프, 콜백 및 오류 표를 확인합니다.