> ## 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 Lite API 가격과 사용법: 1K 이미지

> Google 계정 없이 LaoZhang API 키로 gemini-3.1-flash-lite-image를 호출해 1K 이미지를 생성·편집합니다. 호출당 $0.025, 종횡비 10종과 예제 코드를 제공합니다.

Nano Banana 2 Lite는 Google이 가장 빠르고 저렴하다고 소개하는 Gemini 이미지 모델로, 1K 이미지, 간단한 편집, 대량 작업에 맞춰져 있습니다.

## Lite 지원 범위

| 항목 | 내용 |
| - | - |
| 모델 ID | `gemini-3.1-flash-lite-image`(안정 버전) |
| 가격 | 생성과 편집 모두 **호출당 \$0.025**, Google 표준 가격(이미지당 \$0.0336)보다 낮음(2026년 9월 24일 기준 공개 가격, [AI 모델 API 가격표](https://docs.laozhang.ai/ko/models.md) 참고) |
| 계정 | Google 계정 불필요, LaoZhang API 키만 있으면 됨 |
| 동시 요청과 속도 제한 | 플랫폼 차원의 동시 요청 제한과 스로틀링 없음. `429`는 업스트림 용량 때문에 발생하며, [동시 요청과 429](https://docs.laozhang.ai/ko/faq/api-concurrency.md) 참고 |
| 과금 | HTTP 200 응답은 이미지가 없어도 한 번 과금되고, 200이 아닌 응답은 과금되지 않음. [Nano Banana 개요](https://docs.laozhang.ai/ko/api-capabilities/nano-banana-image.md)의 과금 절 참고 |
| 엔드포인트 | Gemini 네이티브 `generateContent` 또는 OpenAI 호환 chat completions |
| 출력 크기 | 1K만 지원 |
| 종횡비 | Gemini 네이티브 경로에서 10종: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
| 입력 | 텍스트와 객체 이미지 최대 14장 |
| 출력 | 응답에 Base64 이미지로 포함 |
| Google 검색 그라운딩 | 지원 안 함 |

OpenAI 호환 경로에는 종횡비 설정이 없으며, 텍스트만 보낸 프롬프트는 1:1 이미지를 반환합니다.

![Nano Banana 2 Lite로 생성한, 짙은 회색 배경에 청록색 강조가 들어간 현대적인 물류 대시보드](https://mintcdn.com/laozhangai-edd05f2c/YuJHjB7ivlJQODe0/images/samples/lite-en-generate.jpg?fit=max\&auto=format\&n=YuJHjB7ivlJQODe0\&q=85\&s=1a0b918a99dd6f11e7339d4c487c9cdd)

아래 생성 예제의 출력: 1K, 16:9. 프롬프트: Generate an image of a modern logistics dashboard on a dark gray background with cyan highlights.

Google은 Lite가 많은 참조 이미지나 멀티턴 편집에 최적화되어 있지 않다고 설명합니다. 이런 작업이나 2K·4K 출력, Google 검색 그라운딩이 필요하면 [Nano Banana 2.1](https://docs.laozhang.ai/ko/api-capabilities/nano-banana-2-1-image.md) 또는 [Nano Banana 2](https://docs.laozhang.ai/ko/api-capabilities/nano-banana2-image.md)를, 가장 까다로운 레이아웃에는 [Nano Banana Pro](https://docs.laozhang.ai/ko/api-capabilities/nano-banana-pro-image.md)를 쓰세요. 다섯 가지 모델 전체 비교는 [Nano Banana 개요](https://docs.laozhang.ai/ko/api-capabilities/nano-banana-image.md)에 있습니다.

## 호출 전 준비

**1. API 키 발급**

[토큰 관리](https://api.laozhang.ai/token)에서 토큰 생성(创建令牌) 창을 열고, **과금 방식**(计费模式)을 **사용량 우선**(按量优先, 권장) 또는 **건당 과금**(按次计费)으로 설정한 뒤 **생성**(创建)을 클릭합니다. Lite에는 호출당 가격만 있어 사용량 과금(按量计费) 키로는 호출할 수 없습니다. 요청이 언제 과금되는지는 [Nano Banana 개요](https://docs.laozhang.ai/ko/api-capabilities/nano-banana-image.md)의 과금 절에서 설명합니다.

**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` 필드를 출력합니다.

## 이미지 생성

> [tab] cURL
>
> ```bash theme={null}
> curl --fail-with-body --max-time 300 \
>   "https://api.laozhang.ai/v1beta/models/gemini-3.1-flash-lite-image:generateContent" \
>   -H "Authorization: Bearer $LAOZHANG_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "contents": [{
>       "role": "user",
>       "parts": [{"text": "Generate an image of a modern logistics dashboard on a dark gray background with cyan highlights."}]
>     }],
>     "generationConfig": {
>       "responseModalities": ["IMAGE"],
>       "imageConfig": {"aspectRatio": "16:9", "imageSize": "1K"}
>     }
>   }' \
>   -o lite-response.json
>
> save_image lite-response.json lite-dashboard
> ```

> [tab] Python
>
> 아래 스크립트를 `nano_banana_lite.py`로 저장하세요. 프롬프트로 이미지를 생성하거나, 프롬프트 뒤에 적은 이미지를 편집합니다.
>
> ```python theme={null}
> """Nano Banana 2 Lite(gemini-3.1-flash-lite-image)로 1K 이미지를 생성하거나 편집합니다."""
> import argparse
> import base64
> import os
> import sys
> from pathlib import Path
>
> import requests
>
> URL = "https://api.laozhang.ai/v1beta/models/gemini-3.1-flash-lite-image:generateContent"
> RATIOS = ["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9"]
> 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="종횡비. 생략하면 1:1이거나 입력 이미지를 따릅니다")
> parser.add_argument("--out", default="nano-banana-lite", 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}})
>
> image_config = {"imageSize": "1K"}
> if args.ratio:
>     image_config["aspectRatio"] = args.ratio
>
> response = requests.post(
>     URL,
>     headers={"Authorization": f"Bearer {os.environ['LAOZHANG_API_KEY']}"},
>     json={
>         "contents": [{"role": "user", "parts": parts}],
>         "generationConfig": {"responseModalities": ["IMAGE"], "imageConfig": image_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)
> ```
>
> 16:9 이미지를 생성합니다.
>
> ```bash theme={null}
> python nano_banana_lite.py "Generate an image of a modern logistics dashboard on a dark gray background with cyan highlights." --ratio 16:9 --out lite-dashboard
> ```

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

## 이미지 편집

`parts`에 지시문을 먼저, 이미지를 그 뒤에 넣습니다. 로컬 파일은 파일 형식과 일치하는 `mimeType`을 붙여 Base64 `inlineData`로 보냅니다.

> [tab] cURL
>
> 큰 이미지가 셸 인자 길이 제한을 넘지 않도록 `jq`로 요청 본문을 만듭니다.
>
> ```bash theme={null}
> base64 < product.jpg | tr -d '\n' > product.b64
> jq -n --rawfile image product.b64 '{
>   contents: [{
>     role: "user",
>     parts: [
>       {text: "제품은 그대로 두고 배경만 밝은 회색 스튜디오 벽으로 바꿔 주세요."},
>       {inlineData: {mimeType: "image/jpeg", data: $image}}
>     ]
>   }],
>   generationConfig: {
>     responseModalities: ["IMAGE"],
>     imageConfig: {aspectRatio: "4:5", imageSize: "1K"}
>   }
> }' > lite-edit-request.json
>
> curl --fail-with-body --max-time 300 \
>   "https://api.laozhang.ai/v1beta/models/gemini-3.1-flash-lite-image:generateContent" \
>   -H "Authorization: Bearer $LAOZHANG_API_KEY" \
>   -H "Content-Type: application/json" \
>   --data-binary @lite-edit-request.json \
>   -o lite-edit-response.json
>
> save_image lite-edit-response.json lite-product
> ```

> [tab] Python
>
> 위 이미지 생성 절의 `nano_banana_lite.py`를 쓰고, 프롬프트 뒤에 파일을 넘기세요.
>
> ```bash theme={null}
> python nano_banana_lite.py "제품은 그대로 두고 배경만 밝은 회색 스튜디오 벽으로 바꿔 주세요." product.jpg --ratio 4:5 --out lite-product
> ```

Lite로 많이 하는 편집은 배경 교체, 색상 변경, 스티커 추가, 간단한 변형입니다. 바뀌지 않아야 할 부분을 지시문에 분명히 쓰세요. 참조 이미지 여러 장으로 합성하려면 Nano Banana 2.1이나 Nano Banana 2를 쓰세요.

## OpenAI 호환 경로 사용

앱이 이미 OpenAI SDK를 쓴다면 chat completions로 Lite를 호출할 수 있습니다. 이 경로에는 종횡비와 크기 설정이 없어서, 텍스트만 보낸 프롬프트는 1K 1:1 이미지를 반환합니다. 이미지는 `message.content` 안에 Base64 데이터 URL로 들어옵니다.

아래 스크립트를 `nano_banana_lite_chat.py`로 저장하세요.

```python theme={null}
"""OpenAI 호환 경로로 Nano Banana 2 Lite 이미지를 생성하거나 편집합니다."""
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-lite-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-3.1-flash-lite-image",
    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_lite_chat.py "모바일 랜딩 페이지에 쓸 깔끔한 파란색 SaaS 일러스트를 생성해 주세요." --out lite-chat-illustration
python nano_banana_lite_chat.py "이 사진을 플랫 벡터 일러스트로 바꿔 주세요. 구도는 유지하세요." photo.jpg --out lite-chat-vector
```

## 대량 호출 운영

Lite는 초안, 미리보기, 이미지를 많이 만드는 인터랙티브 앱에 잘 맞습니다. 플랫폼은 동시 요청을 제한하지 않으며, 가끔 나오는 `429`는 업스트림 용량 때문입니다([동시 요청과 429](https://docs.laozhang.ai/ko/faq/api-concurrency.md) 참고). 운영 트래픽에서는 다음을 지키세요.

1. 이미지마다 클라이언트를 새로 만들지 말고 HTTP 연결을 재사용합니다.
2. 429, 5xx, 네트워크 오류는 지터를 넣은 지수 백오프로 재시도합니다.
3. 업무 기준 타임아웃을 두고, 타임아웃이 난 요청은 재시도 전에 [호출 로그](https://api.laozhang.ai/log)를 확인해 두 번 과금되지 않게 합니다.
4. 이미지 없는 HTTP 200 응답은 재시도하지 않습니다. 이미 과금되었고, 같은 내용을 다시 보내도 대개 또 아무것도 반환되지 않습니다.
5. 호출마다 모델, 상태 코드, 지연 시간, 요청 시각을 기록합니다.
6. 본격적으로 출시하기 전에 예상 최대 동시 요청 수, 일일 호출량, 입력 이미지 크기를 [hi@laozhang.ai](mailto:hi@laozhang.ai)로 보내 용량을 확인합니다.

## 오류와 과금

* Lite는 `1K`만 지원합니다. `512`, `2K`, `4K`는 보내지 말고, 다른 크기가 필요하면 Nano Banana 2.1, Nano Banana 2, Pro를 쓰세요.
* 크기는 K를 대문자로 쓰세요. Google은 `1k`처럼 소문자로 쓴 값을 거부합니다.
* 프롬프트가 이미지를 요청하지 않았거나 안전 검사가 출력을 차단한 경우처럼, 이미지 없이 HTTP 200이 반환될 수 있습니다. 이때도 한 번 과금되므로 프롬프트나 이미지를 바꾼 뒤 다시 보내세요. [Nano Banana 개요](https://docs.laozhang.ai/ko/api-capabilities/nano-banana-image.md)의 빈 응답 과금 피하기 절을 참고하세요.
* HTTP 401은 키나 `Authorization: Bearer` 헤더가 잘못되었다는 뜻입니다. 429와 5xx는 백오프를 두고 재시도하세요.

## 자주 묻는 질문

### Lite로 2K·4K 이미지를 받거나 Google 검색 그라운딩을 쓸 수 있나요?

둘 다 안 됩니다. Lite는 1K만 출력하고 그라운딩을 지원하지 않습니다. 필요에 따라 다음 모델을 쓰세요. 세 모델 모두 같은 요청을 받으므로 모델 ID만 바꾸면 됩니다.

* `gemini-nano-banana-2.1`(Nano Banana 2.1, 호출당 \$0.045): 1K\~4K
* `gemini-3.1-flash-image`(Nano Banana 2): 512px, 종횡비 14종, 웹·이미지 검색 그라운딩까지 필요할 때
* `gemini-3-pro-image`(Nano Banana Pro): 복잡한 레이아웃을 1K\~4K와 웹 검색 그라운딩으로 만들 때

### Lite는 여러 이미지 합성이나 캐릭터 일관성에 적합한가요?

그다지 적합하지 않습니다. Lite는 객체 이미지를 최대 14장 받지만, Google의 참조 이미지 표에는 Lite의 캐릭터·스타일 참조 항목이 없습니다. Google은 또 Lite가 여러 참조 입력이나 멀티턴 순차 편집에 최적화되어 있지 않다고 설명합니다.

Lite는 색상 변경이나 배경 조정 같은 단일 이미지 부분 편집에 맞습니다. 여러 이미지를 하나로 합치거나 연작에서 같은 인물을 유지하려면, 객체 이미지 최대 10장과 캐릭터 이미지 최대 4장을 받는 Nano Banana 2.1이나 Nano Banana 2를 쓰세요.

### `gemini-3.1-flash-lite-image`는 안정 버전 모델 ID인가요?

네. Google 모델 페이지에 `-preview` 접미사 없는 안정 버전으로 올라 있습니다. 적힌 그대로 사용하세요.

### Lite를 높은 동시성으로 돌릴 수 있나요?

네. 플랫폼은 동시 요청을 제한하지 않습니다. 출시 전에 위 대량 호출 운영 절에 따라 재시도와 타임아웃을 설정하고, 업스트림 용량을 확인할 수 있도록 예상 최대 부하를 고객 지원에 알려 주세요.

## 관련 페이지와 출처

* [Nano Banana 개요](https://docs.laozhang.ai/ko/api-capabilities/nano-banana-image.md) — 5종 모델, 두 프로토콜, 과금 비교
* [Nano Banana 2.1](https://docs.laozhang.ai/ko/api-capabilities/nano-banana-2-1-image.md) — 더 낮은 가격으로 1K\~4K 출력, 종횡비 14종, 검색 그라운딩
* [Nano Banana 2](https://docs.laozhang.ai/ko/api-capabilities/nano-banana2-image.md) — 512px\~4K 출력, 종횡비 14종, 검색 그라운딩
* [Nano Banana Pro](https://docs.laozhang.ai/ko/api-capabilities/nano-banana-pro-image.md) — 복잡한 레이아웃과 브랜드 핵심 에셋
* [Standard 편집](https://docs.laozhang.ai/ko/api-capabilities/nano-banana-image-edit.md) — `gemini-2.5-flash-image` 편집을 옮길 때 Lite와 Nano Banana 2 중 고르기
* [Google: Nano Banana image generation](https://ai.google.dev/gemini-api/docs/image-generation) — Gemini 3.1 Flash Lite Image의 크기, 종횡비, 참조 이미지 제한
* [Google: Gemini 3.1 Flash Lite Image 모델 페이지](https://ai.google.dev/gemini-api/docs/models/gemini-3.1-flash-lite-image) — 안정 모델 ID와 지원 기능
* [호출 로그](https://docs.laozhang.ai/en/faq/call-logs.md) — 요청별 상태와 청구 금액 확인


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