> ## Documentation Index > Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt > Use this file to discover all available pages before exploring further. # Nano banana 2.1 이미지 생성 > 텍스트 기반 이미지 생성과 참조 이미지 편집, 1K / 2K / 4K 출력 및 10가지 화면비를 지원하며 공식 버전과 Ext 버전을 제공합니다. ## 모델 선택 | 모델 ID | 과금 방식 | 요청당 이미지 수 | 참조 이미지 크기 | | - | - | - | - | | `gemini-nano-banana-2.1` | 실제 토큰 사용량 기준 | 1–4장 | 이미지당 최대 20MB | | `gemini-nano-banana-2.1-ext` | 해상도 등급별 이미지당 과금 | 1장만 | 이미지당 최대 20MB, 총 50MB | 두 모델의 출력 크기와 화질은 동일합니다. 한 번에 여러 장을 생성하려면 공식 버전을, 이미지당 비용을 예측하려면 Ext 버전을 선택하세요. 실제 요금은 [모델 가격](https://apimart.ai/pricing)을 확인하세요. 이 API는 비동기 방식입니다. 제출에 성공하면 `task_id`를 반환합니다. [작업 조회](/ko/api-reference/tasks/status)로 상태와 이미지를 가져오세요. 3–5초 간격으로 폴링하고 전체 대기 제한 시간을 최소 3분으로 설정하는 것을 권장합니다. ```bash cURL theme={null} curl --request POST \ --url https://api.apimart.ai/v1/images/generations \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "model": "gemini-nano-banana-2.1", "prompt": "나무 테이블에 앉은 주황색 고양이, 옆에 커피 한 잔, 부드러운 아침 햇살, 사실적인 사진", "size": "16:9", "resolution": "2K", "n": 1 }' ``` ```python Python theme={null} import requests response = requests.post( "https://api.apimart.ai/v1/images/generations", headers={"Authorization": "Bearer "}, json={ "model": "gemini-nano-banana-2.1", "prompt": "나무 테이블에 앉은 주황색 고양이, 옆에 커피 한 잔, 부드러운 아침 햇살, 사실적인 사진", "size": "16:9", "resolution": "2K", "n": 1 } ) print(response.json()) ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.apimart.ai/v1/images/generations", { method: "POST", headers: { Authorization: "Bearer ", "Content-Type": "application/json" }, body: JSON.stringify({ model: "gemini-nano-banana-2.1", prompt: "나무 테이블에 앉은 주황색 고양이, 옆에 커피 한 잔, 부드러운 아침 햇살, 사실적인 사진", size: "16:9", resolution: "2K", n: 1 }) }); console.log(await response.json()); ``` ```json 200 theme={null} { "code": 200, "data": [ { "status": "submitted", "task_id": "task_01K..." } ] } ``` ## 요청 헤더 `Bearer ` 형식의 Bearer 인증입니다. ``은 APIMart API Key입니다. ## 요청 매개변수 모델 ID: `gemini-nano-banana-2.1` 또는 `gemini-nano-banana-2.1-ext`. 이미지 생성 또는 편집을 위한 텍스트 설명입니다. 중국어와 영어를 지원합니다. 출력 화면비입니다. `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`를 지원하며 `16x9` 형식도 허용됩니다. 생략하거나 `auto`로 설정하면 모델이 결정합니다. 이미지 기반 생성에서는 참조 이미지의 비율을 따릅니다. `1:4`, `4:1`, `1:8`, `8:1` 등 다른 비율은 지원하지 않습니다. 지원하지 않는 비율을 사용하면 작업이 실패하고 환불됩니다. 출력 해상도 등급: `1K`, `2K` 또는 `4K`. 소문자도 허용되며 과금에도 영향을 줍니다. `0.5K`와 `512`는 지원하지 않으며 제출 시 HTTP 400을 반환합니다. `3K` 등 인식할 수 없는 다른 값은 `1K`로 생성 및 과금됩니다. 위의 지원 값만 사용하세요. 생성할 이미지 수입니다. 공식 버전은 1–4장, Ext 버전은 1장만 지원합니다. 4를 초과하면 제출 즉시 HTTP 400을 반환합니다. Ext 버전에 2–4를 지정하면 실행 단계에서 실패하고 전액 환불됩니다. 여러 장이 필요하면 Ext 작업을 각각 제출하거나 공식 버전을 사용하세요. 참조 이미지 목록입니다. 생략하면 텍스트 기반 생성, 지정하면 이미지 기반 생성 또는 편집을 수행합니다. 각 항목은 다음을 지원합니다. * 공개적으로 접근 가능한 HTTP(S) 이미지 URL. * `data:image/png;base64,...` 형식의 Base64 Data URL. PNG, JPEG 또는 WEBP를 권장합니다. 공식 버전은 이미지당 최대 20MB, Ext 버전은 이미지당 최대 20MB이며 전체 참조 이미지의 합계는 최대 50MB입니다. 플랫폼에 고정된 참조 이미지 개수 제한은 없지만 무제한 업로드를 의미하지는 않습니다. 모델의 지원 범위를 초과하면 작업이 실패하고 환불될 수 있습니다. 참조 이미지가 많을수록 일반적으로 더 오래 걸립니다. `gemini-nano-banana-2.1-ext`에만 적용됩니다. 활성화하면 Ext 버전 실패 시 공식 버전으로 작업 완료를 시도합니다. **실제로 공식 버전을 사용하면 Ext 버전의 이미지당 요금이 아닌 공식 버전의 실제 토큰 사용량으로 과금됩니다.** 작업 종료 시 알림을 받을 콜백 URL입니다. [작업 웹훅](/ko/api-reference/tasks/webhook)을 참고하세요. ## 출력 크기 참고 | 화면비 | 1K | 2K | 4K | | - | - | - | - | | 1:1 | 1024×1024 | 2048×2048 | 4096×4096 | | 2:3 | 848×1264 | 1696×2528 | 3392×5056 | | 3:2 | 1264×848 | 2528×1696 | 5056×3392 | | 3:4 | 896×1200 | 1792×2400 | 3584×4800 | | 4:3 | 1200×896 | 2400×1792 | 4800×3584 | | 4:5 | 928×1152 | 1856×2304 | 3712×4608 | | 5:4 | 1152×928 | 2304×1856 | 4608×3712 | | 9:16 | 768×1376 | 1536×2752 | 3072×5504 | | 16:9 | 1376×768 | 2752×1536 | 5504×3072 | | 21:9 | 1584×672 | 3168×1344 | 6336×2688 | 위 크기에는 실측값과 모델 계열의 참고값이 포함됩니다. 모든 조합을 실측한 것은 아니므로 실제 픽셀 크기는 반환된 이미지를 기준으로 하세요. ## 참조 이미지 편집 ```json theme={null} { "model": "gemini-nano-banana-2.1-ext", "prompt": "이미지 속 고양이에게 빨간 니트 모자를 씌우고 나머지는 그대로 유지해 주세요", "image_urls": ["https://example.com/cat.jpg"], "resolution": "1K" } ``` 예시 URL을 실제 접근 가능한 이미지 URL로 바꾸세요. `size`를 생략하면 참조 이미지의 비율을 따릅니다. ## 일괄 생성(공식 버전만) ```json theme={null} { "model": "gemini-nano-banana-2.1", "prompt": "사이버펑크 스타일의 도시 야경, 네온 조명, 비가 그친 거리", "size": "16:9", "resolution": "2K", "n": 4 } ``` ## 제출 응답 응답 상태 코드입니다. 성공 시 `200`입니다. 작업 제출 결과입니다. `status`는 `submitted`입니다. `task_id`는 작업 상태와 결과 조회에 사용하는 ID이며 최종 이미지 URL이 아닙니다. ## 작업 결과 조회 ```bash theme={null} curl --request GET \ --url https://api.apimart.ai/v1/tasks/task_01K... \ --header 'Authorization: Bearer ' ``` 성공 응답 예시(이미지 URL은 자리표시자입니다): ```json theme={null} { "code": 200, "data": { "id": "task_01K...", "status": "completed", "progress": 100, "result": { "images": [ { "url": ["https://example.com/generated-image.png"], "expires_at": 1791417625 } ] } } } ``` | 작업 상태 | 의미 | | - | - | | `pending` | 대기 중 | | `processing` | 생성 중 | | `completed` | 성공. `data.result.images[0].url`에서 이미지 URL 배열 확인 | | `failed` | 실패. `data.error.message`에서 원인 확인. 전액 환불되며 `data.cost`는 0 | 완성된 이미지 링크는 모두 `data.result.images[0].url` 배열에 포함됩니다. 4장을 생성하면 이 배열에 링크 4개가 들어갑니다. 완성된 이미지만 반환하며 `n=1`은 완성 이미지 1장을 의미합니다. 링크는 작업 완료 후 24시간 동안 유효하며 `expires_at`을 기준으로 합니다. 만료 전에 다운로드하여 저장하세요. 출력은 PNG 또는 JPEG이며 실제 파일 내용을 기준으로 합니다. 조회 결과의 `data.cost`는 최종 청구 금액(USD)입니다. ## 과금 안내 * **공식 버전**: 실제 입력 및 출력 토큰 사용량으로 과금됩니다. 프롬프트와 참조 이미지는 입력 사용량에 포함됩니다. 제출 시 해상도 등급과 `n`을 기준으로 선차감하고 완료 후 실제 사용량에 따라 환불 또는 추가 청구합니다. * **Ext 버전**: 해상도 등급별 단가 × 실제 생성 이미지 수로 과금됩니다. 화면비는 등급에 영향을 주지 않습니다. `official_fallback`을 활성화하고 실제로 공식 버전을 사용하면 공식 버전의 토큰 과금이 적용됩니다. * 단가는 [모델 가격](https://apimart.ai/pricing)을 확인하세요. 제출 단계에서 거부된 요청은 작업을 생성하지 않으며 과금되지 않습니다. 실패한 작업은 전액 환불됩니다. ## 일반적인 오류 | 상황 | 해결 방법 | | - | - | | HTTP 400 | `0.5K` / `512`, 4를 초과하는 `n`, 참조 이미지당 크기 제한 초과 여부 확인 | | HTTP 401 | API Key 확인 | | HTTP 402 | 잔액이 선차감 금액을 충당하는지 확인 | | HTTP 429 | 요청 제한 발생. 대기 간격을 늘려 재시도 | | 작업 실패: 지원하지 않는 화면비 | 지원하는 10가지 `size` 비율 또는 `auto` 사용 | | 작업 실패: Ext에서 여러 장 요청 | `n`을 1로 설정하거나 공식 버전 사용 | | 작업 실패: 콘텐츠 안전 검사 차단 | 프롬프트 또는 참조 이미지를 수정하고 재시도 | | 작업 실패: 참조 이미지 다운로드 실패 | 이미지 URL에 공개적으로 접근할 수 있는지 확인 | Nano banana 2.1과 Gemini 3.1 Flash Image는 서로 다른 모델이며 모델명을 별칭처럼 바꿔 사용할 수 없습니다. 후자에서 이전할 때는 `0.5K` 해상도와 `1:4`, `4:1`, `1:8`, `8:1`의 네 가지 극단적 비율을 변경하세요. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.