> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Nano Banana 2.1 API 가격: 이미지 생성·편집

> Google 계정 없이 LaoZhang API 키로 gemini-nano-banana-2.1을 호출합니다. 1K~4K 호출당 $0.045, 종횡비 14종, 참조 이미지 14장, 바로 실행할 수 있는 코드를 제공합니다.

Nano Banana 2.1은 Google이 2026년 10월에 내놓은 Nano Banana 2의 업데이트입니다. 텍스트 렌더링이 더 선명하고, 인포그래픽 레이아웃이 더 정확하며, 멀티턴 편집에서 일관성이 좋아졌고, 가격은 Nano Banana 2보다 낮습니다.

## Nano Banana 2.1 지원 범위

| 항목 | 내용 |
| - | - |
| 모델 ID | `gemini-nano-banana-2.1`(안정 버전), Google Gemini Nano Banana 2.1 |
| 가격 | 1K, 2K, 4K 모두 **호출당 \$0.045**, 생성과 편집 동일 |
| 계정 | Google 계정 불필요, LaoZhang API 키만 있으면 됨 |
| 토큰 | `default` 그룹, 과금 방식은 사용량 우선(권장) 또는 건당 과금 |
| 엔드포인트 | Gemini 네이티브 `generateContent`는 종횡비와 출력 크기를 지정할 수 있고, OpenAI 호환 `/v1/chat/completions`는 1K 이미지를 반환 |
| 동시 요청과 속도 제한 | 플랫폼 차원의 동시 요청 제한과 스로틀링 없음. `429`는 업스트림 용량 때문에 발생하며, [동시 요청과 429](https://docs.laozhang.ai/ko/faq/api-concurrency.md) 참고 |
| 과금 | HTTP 200 응답은 이미지가 없어도 한 번 과금되고, 200이 아닌 응답(400, 429, 5xx)은 과금되지 않음. [과금과 실패 처리](https://docs.laozhang.ai/ko/api-capabilities/image-billing-and-failures.md) 참고 |

공개 가격은 2026년 10월 7일 기준이며 2026년 10월 14일에 확인했습니다. 최신 가격은 [모델 및 가격](https://docs.laozhang.ai/ko/models.md)에서 볼 수 있습니다. 2026년 10월 7일과 14일에 1K, 2K, 4K로 직접 호출해 본 결과 모두 \$0.045로 기록되었습니다. 이 모델은 Google 공식 채널에서 제공되고 건당 과금 경로는 가격이 하나이므로, 2K와 4K 이미지는 Google 표준 가격(2K \$0.0504, 4K \$0.113)보다 저렴합니다. 자세한 내용은 [Nano Banana 개요](https://docs.laozhang.ai/ko/api-capabilities/nano-banana-image.md)의 공식 가격 비교를 참고하세요.

![Nano Banana 2.1로 생성한, 비 온 뒤 해 질 녘 네온 BANANA CAFE 간판이 걸린 길모퉁이 카페](https://mintcdn.com/laozhangai-edd05f2c/YuJHjB7ivlJQODe0/images/samples/nb21-en-generate.jpg?fit=max\&auto=format\&n=YuJHjB7ivlJQODe0\&q=85\&s=776b4b2c0679826afe7f53c233cadd2b)

아래 생성 예제의 출력: 2K, 16:9. 프롬프트: Generate an image of a corner cafe after rain at dusk, warm light on the wet pavement, with a neon sign that reads "BANANA CAFE".

### 파라미터와 제한

| 파라미터 | 값 |
| - | - |
| 출력 크기 `imageSize` | `1K`(기본값), `2K`, `4K`. K를 대문자로 쓴 문자열이며 `512`는 없음 |
| 종횡비 `aspectRatio` | 14종: `1:1`, `1:4`, `1:8`, `2:3`, `3:2`, `3:4`, `4:1`, `4:3`, `4:5`, `5:4`, `8:1`, `9:16`, `16:9`, `21:9`. 생략하면 모델이 선택 |
| 참조 이미지 | 최대 14장: 객체 이미지 최대 10장, 캐릭터 이미지 최대 4장 |
| 요청당 이미지 수 | 1장. 여러 장이 필요하면 요청을 여러 번 보내세요 |
| 사고(thinking) | `minimal`, `medium`(기본값), `high`. 가격은 모두 같음 |
| 출력 형식 `imageOutputOptions` | `image/png`(기본값) 또는 `image/jpeg`(`compressionQuality` 지정 가능). WebP 없음. Gemini 네이티브 요청에서만 사용 가능하며, 아래 자주 묻는 질문의 JPEG 출력 항목 참고 |
| Google 검색 그라운딩 | 웹 검색과 이미지 검색, 검색 1회당 \$0.014 |

다섯 가지 Nano Banana 모델을 모두 비교하려면 [Nano Banana 개요](https://docs.laozhang.ai/ko/api-capabilities/nano-banana-image.md)를 참고하세요.

## Nano Banana 2.1과 Nano Banana 2 중 무엇을 쓸까요?

두 모델은 같은 요청을 받고 같은 형태로 응답하므로, 전환할 때는 모델 ID만 바꾸면 됩니다.

| | Nano Banana 2.1 | Nano Banana 2 |
| - | - | - |
| 모델 ID | `gemini-nano-banana-2.1` | `gemini-3.1-flash-image` |
| LaoZhang API 가격 | 호출당 \$0.045 | 호출당 \$0.055 |
| 출력 크기 | `1K`, `2K`, `4K` | `512`, `1K`, `2K`, `4K` |
| 사고 수준 | `minimal`, `medium`(기본값), `high` | `minimal`(기본값), `high` |
| 종횡비, 참조 이미지, 그라운딩 | 동일 | 동일 |

> [card] 신규 프로젝트: Nano Banana 2.1
>
> 1K\~4K를 더 낮은 호출당 가격에 제공하며, 텍스트와 레이아웃이 더 좋습니다.

> [card] [512px 미리보기: Nano Banana 2](https://docs.laozhang.ai/ko/api-capabilities/nano-banana2-image.md)
>
> Nano Banana 2.1에는 `512` 크기가 없습니다. Nano Banana 2는 같은 가격으로 계속 제공되므로 기존 연동을 옮기지 않아도 됩니다.

이 페이지의 생성 예제를 2026년 10월 14일에 두 모델에 2K, 16:9로 보낸 결과입니다.

![Nano Banana 2.1로 생성한, 비 온 뒤 해 질 녘 노란색과 빨간색 BANANA CAFE 네온 간판과 바나나 아이콘이 있는 길모퉁이 카페](https://mintcdn.com/laozhangai-edd05f2c/nO-3-m3eSAbAbdWF/images/samples/nb21-cmp-en-nb21-2k.jpg?fit=max\&auto=format\&n=nO-3-m3eSAbAbdWF\&q=85\&s=d6d3ef2794d75a7e780d83552f5f9b62)

Nano Banana 2.1, 2K, 16:9: 25초, \$0.045

![Nano Banana 2로 생성한, 비 온 뒤 해 질 녘 한 줄짜리 BANANA CAFE 네온 간판과 옆집 서점이 있는 길모퉁이 카페](https://mintcdn.com/laozhangai-edd05f2c/nO-3-m3eSAbAbdWF/images/samples/nb21-cmp-en-nb2-2k.jpg?fit=max\&auto=format\&n=nO-3-m3eSAbAbdWF\&q=85\&s=91a1d0d70fcc2dd803104227b8122798)

Nano Banana 2, 2K, 16:9: 21초, \$0.055

## 호출 전 준비

**1. API 키 발급**

[토큰 관리](https://api.laozhang.ai/token)에서 `default` 그룹의 키를 만들고 **과금 방식**(计费模式)을 **사용량 우선**(按量优先, 권장) 또는 **건당 과금**(按次计费)으로 설정합니다. 사용량 과금(按量计费) 키는 Nano Banana 2.1 같은 건당 과금 모델을 호출할 수 없습니다.

**2. 키 설정과 의존성 설치**

```bash theme={null}
export LAOZHANG_API_KEY="sk-..."  # LaoZhang API 키로 바꾸세요
python -m pip install openai requests
```

**3. cURL용 저장 함수 추가**

cURL 예제에는 `jq`가 필요합니다. 아래 셸 함수는 Gemini 네이티브 응답에서 사고용이 아닌 마지막 이미지를 `mimeType`에 맞는 확장자로 저장합니다.

```bash theme={null}
save_image() {
  local image='[.candidates[]?.content.parts[]? | select(.inlineData and (.thought | not))][-1].inlineData'
  local ext
  case "$(jq -r "$image.mimeType" "$1")" in
    image/png) ext=png ;;
    image/jpeg) ext=jpg ;;
    image/webp) ext=webp ;;
    *) jq '{error, promptFeedback, finishReasons: [.candidates[]?.finishReason]}' "$1"; return 1 ;;
  esac
  jq -r "$image.data" "$1" | base64 --decode > "$2.$ext" && echo "저장됨: $2.$ext"
}
```

응답에 이미지가 없으면 이 함수는 대신 `error`, `promptFeedback`, `finishReason` 필드를 출력합니다.

요청 하나는 보통 15\~40초가 걸리고 4K는 더 오래 걸립니다. 2026년 10월 7일과 14일에 단일 요청으로 측정한 출력 픽셀과 소요 시간은 다음과 같으며, 모두 \$0.045였습니다.

| `imageSize` | 1:1 출력 | 16:9 출력 | 측정 소요 시간 |
| - | - | - | - |
| `1K` | 1024×1024 | 1376×768 | 19\~21초 |
| `2K` | 2048×2048 | 2752×1536 | 25\~30초 |
| `4K` | 4096×4096 | 5504×3072 | 33\~50초 |

예제는 300초까지 기다리도록 설정했으며, 클라이언트와 중간 프록시에도 같은 여유를 두세요. 가끔 이 제한을 넘기는 요청이 있으므로, 타임아웃이 난 요청을 다시 보내기 전에 [호출 로그](https://docs.laozhang.ai/en/faq/call-logs.md)를 확인하세요.

## 이미지 생성

> [tab] cURL
>
> ```bash theme={null}
> curl --fail-with-body --max-time 300 \
>   "https://api.laozhang.ai/v1beta/models/gemini-nano-banana-2.1:generateContent" \
>   -H "Authorization: Bearer $LAOZHANG_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "contents": [{
>       "role": "user",
>       "parts": [{"text": "Generate an image of a corner cafe after rain at dusk, warm light on the wet pavement, with a neon sign that reads \"BANANA CAFE\"."}]
>     }],
>     "generationConfig": {
>       "responseModalities": ["IMAGE"],
>       "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
>     }
>   }' \
>   -o nb21-response.json
>
> save_image nb21-response.json nb21-cafe
> ```

> [tab] Python
>
> 아래 스크립트를 `nano_banana_21.py`로 저장하세요. 프롬프트로 이미지를 생성하거나, 프롬프트 뒤에 적은 이미지를 편집합니다.
>
> ```python theme={null}
> """Nano Banana 2.1(gemini-nano-banana-2.1)로 이미지를 생성하거나 편집합니다."""
> import argparse
> import base64
> import os
> import sys
> from pathlib import Path
>
> import requests
>
> URL = "https://api.laozhang.ai/v1beta/models/gemini-nano-banana-2.1:generateContent"
> RATIOS = ["1:1", "1:4", "1:8", "2:3", "3:2", "3:4", "4:1", "4:3", "4:5", "5:4", "8:1", "9:16", "16:9", "21:9"]
> SIZES = ["1K", "2K", "4K"]
> MIME_TYPES = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp"}
> EXTENSIONS = {"image/png": "png", "image/jpeg": "jpg", "image/webp": "webp"}
>
> parser = argparse.ArgumentParser(description="이미지를 생성하거나, 전달한 이미지를 편집합니다.")
> parser.add_argument("prompt")
> parser.add_argument("images", nargs="*", help="참조 이미지(PNG, JPEG, WebP) 최대 14장")
> parser.add_argument("--ratio", choices=RATIOS, help="종횡비. 생략하면 모델이 선택합니다")
> parser.add_argument("--size", default="1K", choices=SIZES)
> parser.add_argument("--thinking", choices=["minimal", "medium", "high"], help="생략하면 기본값인 medium")
> parser.add_argument("--out", default="nano-banana-21", help="확장자를 뺀 출력 파일 이름")
> args = parser.parse_args()
> if len(args.images) > 14:
>     sys.exit("참조 이미지는 최대 14장까지 보낼 수 있습니다.")
>
> parts = [{"text": args.prompt}]
> for path in args.images:
>     mime = MIME_TYPES.get(Path(path).suffix.lower())
>     if mime is None:
>         sys.exit(f"PNG, JPEG, WebP 파일을 사용하세요: {path}")
>     data = base64.b64encode(Path(path).read_bytes()).decode("ascii")
>     parts.append({"inlineData": {"mimeType": mime, "data": data}})
>
> config = {"responseModalities": ["IMAGE"], "imageConfig": {"imageSize": args.size}}
> if args.ratio:
>     config["imageConfig"]["aspectRatio"] = args.ratio
> if args.thinking:
>     config["thinkingConfig"] = {"thinkingLevel": args.thinking}
>
> response = requests.post(
>     URL,
>     headers={"Authorization": f"Bearer {os.environ['LAOZHANG_API_KEY']}"},
>     json={"contents": [{"role": "user", "parts": parts}], "generationConfig": config},
>     timeout=300,
> )
> if response.status_code != 200:
>     sys.exit(f"HTTP {response.status_code}: {response.text[:500]}")
>
> result = response.json()
> images = [
>     part["inlineData"]
>     for candidate in result.get("candidates") or []
>     for part in (candidate.get("content") or {}).get("parts") or []
>     if "inlineData" in part and not part.get("thought")
> ]
> if not images:
>     reasons = [candidate.get("finishReason") for candidate in result.get("candidates") or []]
>     sys.exit(f"반환된 이미지가 없습니다: {result.get('promptFeedback') or reasons}")
> for number, image in enumerate(images, start=1):
>     suffix = "" if number == 1 else f"-{number}"
>     output = Path(f"{args.out}{suffix}.{EXTENSIONS.get(image['mimeType'], 'bin')}")
>     output.write_bytes(base64.b64decode(image["data"]))
>     print("저장됨:", output)
> ```
>
> 4K, 16:9 이미지를 생성합니다.
>
> ```bash theme={null}
> python nano_banana_21.py "Generate an image of a corner cafe after rain at dusk, warm light on the wet pavement, with a neon sign that reads \"BANANA CAFE\"." --ratio 16:9 --size 4K --out nb21-cafe
> ```

이미지는 `candidates[0].content.parts[].inlineData.data`에 Base64로 들어 있고, 형식은 `mimeType`으로 알 수 있습니다. 두 예제 모두 이를 디코딩해 형식에 맞는 PNG, JPEG, WebP 파일로 저장합니다.

`aspectRatio`를 생략하면 모델이 프롬프트를 보고 프레임을 정합니다. 1:1과 16:9의 출력 픽셀은 위 호출 전 준비 절의 표에 있고, 다른 종횡비는 Google의 [이미지 생성 가이드](https://ai.google.dev/gemini-api/docs/image-generation)에서 확인하세요.

## 이미지 편집

지시문을 먼저 보내고, 참조 이미지를 `inlineData` 파트로 이어서 보냅니다. 프롬프트에서는 이미지를 순서대로 "첫 번째 이미지", "두 번째 이미지"처럼 가리키세요. Nano Banana 2.1은 참조 이미지를 최대 14장 받으며, 객체 이미지는 최대 10장, 캐릭터 이미지는 최대 4장입니다.

> [tab] cURL
>
> 로컬 파일 두 개를 합성하는 요청입니다. 큰 이미지가 셸 인자 길이 제한을 넘지 않도록 `jq`로 본문을 만들고, 각 `mimeType`이 파일과 일치하는지 확인하세요.
>
> ```bash theme={null}
> base64 < product.png | tr -d '\n' > product.b64
> base64 < scene.jpg | tr -d '\n' > scene.b64
> jq -n --rawfile product product.b64 --rawfile scene scene.b64 '{
>   contents: [{
>     role: "user",
>     parts: [
>       {text: "첫 번째 이미지의 제품을 두 번째 이미지의 테이블 위에 놓아 주세요. 장면의 조명에 맞추고 제품 라벨이 읽히도록 유지하세요."},
>       {inlineData: {mimeType: "image/png", data: $product}},
>       {inlineData: {mimeType: "image/jpeg", data: $scene}}
>     ]
>   }],
>   generationConfig: {
>     responseModalities: ["IMAGE"],
>     imageConfig: {aspectRatio: "3:2", imageSize: "2K"}
>   }
> }' > nb21-edit-request.json
>
> curl --fail-with-body --max-time 300 \
>   "https://api.laozhang.ai/v1beta/models/gemini-nano-banana-2.1:generateContent" \
>   -H "Authorization: Bearer $LAOZHANG_API_KEY" \
>   -H "Content-Type: application/json" \
>   --data-binary @nb21-edit-request.json \
>   -o nb21-edit-response.json
>
> save_image nb21-edit-response.json nb21-product-scene
> ```

> [tab] Python
>
> 위 이미지 생성 절의 `nano_banana_21.py`를 쓰고, 프롬프트 뒤에 파일을 나열하세요.
>
> ```bash theme={null}
> # 이미지 한 장 편집
> python nano_banana_21.py "이 장면을 눈 내린 아침으로 바꿔 주세요. 건물, 간판 글자, 구도는 그대로 유지하세요." nb21-cafe.jpg --ratio 16:9 --size 2K --out nb21-snow
>
> # 참조 이미지 세 장 합성: 제품, 장면, 분위기를 정할 세 번째 이미지
> python nano_banana_21.py "첫 번째 이미지의 제품을 두 번째 이미지의 테이블 위에 놓고, 세 번째 이미지의 화풍으로 그려 주세요." product.png scene.jpg style.jpg --ratio 3:2 --size 2K --out nb21-composite
> ```

바뀌지 않아야 할 부분을 분명히 쓰고, 정밀하게 제어하려면 요청마다 변경 사항을 하나씩만 설명하세요. 연작에서 인물을 일관되게 유지하려면 인물 사진을 캐릭터 참조(최대 4장)로 넘기세요.

### 큰 이미지는 URL로 전달

요청 본문 전체를 20MB 이내로 유지하세요. 참조 이미지가 크거나 이미 CDN에 있다면 내려받아 인코딩하는 대신 `fileData` 파트에 URL을 넣어 전달합니다.

```bash theme={null}
curl --fail-with-body --max-time 300 \
  "https://api.laozhang.ai/v1beta/models/gemini-nano-banana-2.1:generateContent" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [
        {"text": "이 사진을 흑백 연필 스케치로 바꿔 주세요. 인물과 구도는 그대로 유지하세요."},
        {"fileData": {"mimeType": "image/jpeg", "fileUri": "https://cdn.example.com/your-photo.jpg"}}
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "4:3", "imageSize": "2K"}
    }
  }' \
  -o nb21-url-edit-response.json

save_image nb21-url-edit-response.json nb21-url-edit
```

* `https://cdn.example.com/your-photo.jpg`는 실제 이미지 URL로 바꾸고, `mimeType`을 이미지 형식에 맞추세요.
* `fileData` 파트와 `inlineData` 파트는 같은 `parts` 배열에 함께 쓸 수 있으며, 나열한 순서대로 첫 번째, 두 번째 이후의 참조 이미지로 계산됩니다.
* 서버가 이미지를 내려받으므로 URL은 로그인 없이 접근할 수 있어야 합니다. 전체 조건은 [Nano Banana 개요](https://docs.laozhang.ai/ko/api-capabilities/nano-banana-image.md)의 큰 이미지와 이미지 URL 절을 참고하세요.

## Google 검색으로 이미지 그라운딩

이미지가 최신 정보나 실제 랜드마크의 모습에 의존한다면 `googleSearch` 도구를 추가하세요. 아래 요청은 웹 검색과 이미지 검색을 모두 켜고, 모델이 쓴 텍스트도 함께 받도록 `TEXT`를 허용합니다.

```bash theme={null}
curl --fail-with-body --max-time 300 \
  "https://api.laozhang.ai/v1beta/models/gemini-nano-banana-2.1:generateContent" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "현재 세계에서 가장 높은 건물을 수채화 일러스트로 그리고, 아래에 건물 이름을 적어 주세요."}]}],
    "tools": [{"googleSearch": {"searchTypes": {"webSearch": {}, "imageSearch": {}}}}],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {"aspectRatio": "2:3"}
    }
  }' \
  -o nb21-grounded-response.json

save_image nb21-grounded-response.json nb21-tallest-building
jq '.candidates[0].groundingMetadata | {webSearchQueries, imageSearchQueries}' nb21-grounded-response.json
```

* `searchTypes`는 객체여야 합니다. 생략하면 웹 검색만 사용하고, `imageSearch`만 쓰면 이미지 검색만 사용합니다.
* 검색할지, 어떤 유형으로 검색할지는 모델이 정합니다. 실행한 쿼리는 `groundingMetadata`에 나옵니다.
* 이미지 검색은 현재 실제 인물 이미지를 참조로 쓸 수 없습니다.
* 그라운딩 결과를 최종 사용자에게 보여 준다면, Google의 [그라운딩 가이드](https://ai.google.dev/gemini-api/docs/google-search)가 요구하는 대로 검색 제안을 표시하세요.
* 검색 1회마다 호출 가격 \$0.045에 \$0.014가 더해지므로, 검색을 2회 실행한 요청은 \$0.073입니다. 호출 로그에서 검색 횟수를 볼 수 있으며, 자세한 규칙은 [Nano Banana 개요](https://docs.laozhang.ai/ko/api-capabilities/nano-banana-image.md)의 과금 절을 참고하세요.

## OpenAI 호환 경로 사용

앱이 이미 OpenAI SDK를 쓴다면 `base_url`을 `https://api.laozhang.ai/v1`로, `model`을 `gemini-nano-banana-2.1`로 지정하세요. 이 경로에는 종횡비, 크기, 형식 설정이 없습니다. 프롬프트에 따라 모델이 프레임을 정한 1K PNG를 반환하며, 16:9인 경우가 많습니다. 종횡비를 고정하거나 2K·4K, JPEG가 필요하면 Gemini 네이티브 경로를 쓰세요.

이미지는 `message.content` 안에 Base64 데이터 URL로 들어옵니다. 아래 스크립트를 `nano_banana_21_chat.py`로 저장하세요.

```python theme={null}
"""OpenAI 호환 경로로 Nano Banana 2.1 이미지를 생성하거나 편집합니다."""
import argparse
import base64
import os
import re
import sys
from pathlib import Path

from openai import OpenAI

MIME_TYPES = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp"}
EXTENSIONS = {"png": "png", "jpeg": "jpg", "jpg": "jpg", "webp": "webp"}

parser = argparse.ArgumentParser(description="이미지를 생성하거나, 전달한 이미지를 편집합니다.")
parser.add_argument("prompt")
parser.add_argument("images", nargs="*", help="편집할 이미지(PNG, JPEG, WebP)")
parser.add_argument("--out", default="nano-banana-21-chat", help="확장자를 뺀 출력 파일 이름")
args = parser.parse_args()

content = args.prompt
if args.images:  # 편집: 지시문과 로컬 이미지를 데이터 URL로 보냅니다
    content = [{"type": "text", "text": args.prompt}]
    for path in args.images:
        mime = MIME_TYPES.get(Path(path).suffix.lower())
        if mime is None:
            sys.exit(f"PNG, JPEG, WebP 파일을 사용하세요: {path}")
        encoded = base64.b64encode(Path(path).read_bytes()).decode("ascii")
        content.append({"type": "image_url", "image_url": {"url": f"data:{mime};base64,{encoded}"}})

# max_retries=0: 타임아웃 뒤 자동 재시도하면 이미지가 두 번 생성되어 두 번 과금될 수 있습니다
client = OpenAI(api_key=os.environ["LAOZHANG_API_KEY"], base_url="https://api.laozhang.ai/v1", timeout=300, max_retries=0)
reply = client.chat.completions.create(
    model="gemini-nano-banana-2.1",
    messages=[{"role": "user", "content": content}],
)
text = reply.choices[0].message.content or ""

found = re.findall(r"data:image/(png|jpe?g|webp);base64,([A-Za-z0-9+/=]+)", text)
if not found:
    sys.exit(f"반환된 이미지가 없습니다: {text[:300]}")
for number, (kind, encoded) in enumerate(found, start=1):
    suffix = "" if number == 1 else f"-{number}"
    output = Path(f"{args.out}{suffix}.{EXTENSIONS[kind]}")
    output.write_bytes(base64.b64decode(encoded + "=" * (-len(encoded) % 4)))
    print("저장됨:", output)
```

이미지를 생성한 다음 로컬 파일을 편집합니다.

```bash theme={null}
python nano_banana_21_chat.py "나무 테이블 위의 라테 이미지를 생성해 주세요. 고양이 라테아트가 있고 위에서 내려다본 구도로." --out nb21-chat-latte
python nano_banana_21_chat.py "이 사진을 반 고흐 스타일의 유화로 바꿔 주세요. 구도는 유지하세요." photo.jpg --out nb21-chat-painting
```

## 오류와 과금

잘못된 파라미터는 HTTP 400을 반환하며 과금되지 않습니다. 14가지 종횡비에 없는 `aspectRatio`(예: `7:3`)는 오류 메시지가 비어 있을 수 있는 400을 반환하므로, 위 파라미터와 제한 표에서 종횡비를 확인하세요. 요청 본문이 너무 크면 413이 반환됩니다. 큰 이미지는 위 큰 이미지는 URL로 전달 절처럼 URL로 넘기세요.

> [!WARNING]
>
> **`imageSize`를 `512`로 지정해도 거부되지 않고 1K 이미지가 반환되며 과금됩니다.** 2026년 10월 8일 기준 호출 비용은 \$0.045이므로, `1K`를 보내거나 512px이 필요하면 Nano Banana 2를 쓰세요.

* 출력 크기, 사고 수준, 참조 이미지 수, 생성·편집 여부와 관계없이 호출당 \$0.045입니다.
* Google 검색 그라운딩은 검색 1회당 \$0.014가 추가됩니다.
* 프롬프트가 이미지를 요청하지 않았거나 안전 검사가 출력을 차단한 경우처럼, 이미지 없이 HTTP 200이 반환될 수 있습니다. 이때도 한 번 과금됩니다. `finishReason`을 확인하고 프롬프트나 참조 이미지를 바꾼 뒤 다시 보내세요. [Nano Banana 개요](https://docs.laozhang.ai/ko/api-capabilities/nano-banana-image.md)의 빈 응답 과금 피하기 절을 참고하세요.
* 429와 5xx 응답은 백오프를 두고 재시도하고, 타임아웃이 난 요청은 다시 보내기 전에 [호출 로그](https://docs.laozhang.ai/en/faq/call-logs.md)를 확인하세요.

## 자주 묻는 질문

### Nano Banana 2에서 옮기려면 무엇을 바꾸나요?

모델 ID를 `gemini-3.1-flash-image`에서 `gemini-nano-banana-2.1`로 바꾸면 됩니다. 요청과 응답은 그대로입니다. 그다음 두 가지를 확인하세요.

* `"imageSize": "512"`를 쓰던 요청은 `1K`로 바꾸거나 Nano Banana 2에 그대로 두세요. Nano Banana 2.1은 이 요청에 1K 이미지를 반환하고 호출을 과금합니다.
* `thinkingLevel`을 지정하지 않으면 Nano Banana 2.1은 `medium`으로, Nano Banana 2는 기본값인 `minimal`로 사고합니다. 더 빠른 동작을 원하면 `minimal`을 명시하세요.

### 사고 수준은 어떻게 바꾸나요? 가격에 영향이 있나요?

Gemini 네이티브 경로에서 `generationConfig.thinkingConfig.thinkingLevel`을 `minimal`, `medium`, `high` 중 하나로 설정합니다. 수준이 높을수록 레이아웃과 텍스트에 더 많은 노력을 들이고 시간이 더 걸립니다.

```json theme={null}
"thinkingConfig": {"thinkingLevel": "high"}
```

세 수준 모두 호출당 \$0.045로 같습니다. Google은 사고 토큰을 별도로 과금합니다. `"includeThoughts": true`도 함께 설정하면 응답에 `"thought": true`로 표시된 사고 텍스트와 초안 이미지가 추가됩니다. `save_image` 함수와 Python 스크립트는 이를 건너뜁니다.

### 4K가 1K보다 비싼가요?

아니요. 모든 호출이 \$0.045입니다. 2026년 10월 7일과 14일에 1K, 2K, 4K로 직접 호출해 본 결과 모두 이 금액으로 기록되었습니다. Google은 출력 토큰 기준으로 과금하며, [가격 페이지](https://ai.google.dev/gemini-api/docs/pricing)에 따르면 4K 이미지 한 장이 약 \$0.113입니다. 1K 이미지만 필요하다면 [Nano Banana 2 Lite](https://docs.laozhang.ai/ko/api-capabilities/nano-banana-2-lite-api.md)가 호출당 더 저렴합니다.

### Nano Banana 2.1과 Nano Banana Pro 중 무엇을 쓸까요?

호출당 \$0.045인 Nano Banana 2.1로 시작하세요. 이미지가 세계 지식, 다국어 텍스트, 정확한 브랜드 디테일에 의존하거나, 편집에 스타일 참조와 최대 5장의 캐릭터 참조가 필요하다면 [Nano Banana Pro](https://docs.laozhang.ai/ko/api-capabilities/nano-banana-pro-image.md)(`gemini-3-pro-image`, 호출당 \$0.09)로 옮기세요. 두 모델은 같은 요청을 받으므로, 결정하기 전에 직접 쓰는 프롬프트로 두 모델을 모두 시험해 보세요.

2026년 10월 14일에 같은 프롬프트를 2K, 16:9로 실행했을 때 Nano Banana 2.1은 25초, Nano Banana Pro는 69초가 걸렸습니다.

![Nano Banana 2.1로 생성한, 비 온 뒤 해 질 녘 노란색과 빨간색 BANANA CAFE 네온 간판이 있는 길모퉁이 카페](https://mintcdn.com/laozhangai-edd05f2c/nO-3-m3eSAbAbdWF/images/samples/nb21-cmp-en-nb21-2k.jpg?fit=max\&auto=format\&n=nO-3-m3eSAbAbdWF\&q=85\&s=d6d3ef2794d75a7e780d83552f5f9b62)

Nano Banana 2.1, 2K, 16:9: 25초, \$0.045

![Nano Banana Pro로 생성한, 비 온 뒤 해 질 녘 BANANA CAFE 네온 간판과 돌바닥 거리가 있는 벽돌 길모퉁이 카페](https://mintcdn.com/laozhangai-edd05f2c/nO-3-m3eSAbAbdWF/images/samples/nb21-cmp-en-pro-2k.jpg?fit=max\&auto=format\&n=nO-3-m3eSAbAbdWF\&q=85\&s=3fbd606d2b3817f65334e1556ad00f2d)

Nano Banana Pro, 2K, 16:9: 69초, \$0.09

### Google 계정이나 AI Studio 키가 필요한가요?

아니요. `default` 그룹의 LaoZhang API 키면 충분합니다. 이 페이지의 Gemini 네이티브 형식이나 OpenAI 호환 형식으로 `https://api.laozhang.ai`에 요청을 보내면 됩니다.

### 요청이 실패하거나 이미지가 없으면 과금되나요?

잘못된 파라미터로 인한 400이나 생성 전에 발생한 429·5xx처럼 업스트림이 200이 아닌 응답을 반환하면 과금되지 않습니다. HTTP 200은 이미지 유무와 관계없이 한 번 과금됩니다. 위 오류와 과금 절과 [과금과 실패 처리](https://docs.laozhang.ai/ko/api-capabilities/image-billing-and-failures.md)를 참고하세요.

### JPEG로 출력할 수 있나요?

네. Gemini 네이티브 경로에서 `generationConfig.imageConfig`에 `imageOutputOptions`를 추가하세요.

```json theme={null}
"imageConfig": {
  "aspectRatio": "1:1",
  "imageSize": "1K",
  "imageOutputOptions": {"mimeType": "image/jpeg", "compressionQuality": 80}
}
```

* `mimeType`은 `image/png`(기본값)와 `image/jpeg`를 받습니다. `image/webp`는 400을 반환하며 과금되지 않습니다.
* `compressionQuality`는 JPEG에만 적용되며 0\~100 범위입니다. 값이 낮을수록 파일이 작아집니다.
* 응답의 `inlineData.mimeType`이 `image/jpeg`로 바뀝니다. 같은 1K 정사각형 이미지가 PNG로는 약 1.1MB, JPEG로는 40\~60KB이며 가격은 같습니다.
* OpenAI 호환 경로에서는 형식을 지정할 수 없고 항상 PNG를 반환합니다.

### OpenAI 호환 경로가 가로형 이미지를 반환하는 이유는 무엇인가요?

이 경로는 종횡비를 전달할 수 없어서, 모델이 프롬프트를 보고 프레임을 정하며 16:9인 경우가 많습니다. 정사각형이나 세로형이 필요하면 Gemini 네이티브 경로에서 `aspectRatio`를 지정하세요.

## 관련 페이지와 출처

* [Nano Banana 개요](https://docs.laozhang.ai/ko/api-capabilities/nano-banana-image.md) — 5종 모델, 두 프로토콜, 과금 비교
* [Nano Banana 2](https://docs.laozhang.ai/ko/api-capabilities/nano-banana2-image.md) — 512px 출력이 필요할 때
* [Nano Banana 2 Lite](https://docs.laozhang.ai/ko/api-capabilities/nano-banana-2-lite-api.md) — 저비용 1K 이미지
* [Nano Banana Pro](https://docs.laozhang.ai/ko/api-capabilities/nano-banana-pro-image.md) — 복잡한 레이아웃과 브랜드 핵심 에셋
* [Gemini 프로토콜](https://docs.laozhang.ai/ko/api-reference/gemini.md) — 네이티브 요청 구조와 SDK 설정
* [Google: Gemini Nano Banana 2.1](https://ai.google.dev/gemini-api/docs/models/gemini-nano-banana-2.1) — 공식 기능과 제한
* [Google: Nano Banana image generation](https://ai.google.dev/gemini-api/docs/image-generation) — 크기, 종횡비, 참조 이미지 제한
* [호출 로그](https://docs.laozhang.ai/en/faq/call-logs.md) — 요청별 상태와 청구 금액 확인


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.