Nano Banana 2 Lite API 사용 방법: curl, Python 및 실행 가능한 요청

Nano-Banana-2-Lite는 hiapi의 Nano-Banana 이미지 모델 패밀리 중 경제형 모델입니다. 더 큰 형제 모델들과 동일한 작업 기반 workflow를 사용하면서도 장당 가격이更低(더 저렴)하며, 텍스트→이미지 생성과 참조 이미지 편집을 모두 지원합니다. 이 가이드에서는 작업 생성, 폴링, 결과 다운로드로 이어지는 완전하고 실행 가능한 통합 흐름을 curl과 Python으로 각각演示(시연)하고, Nano-Banana-2 및 Nano-Banana-Pro와 다른 schema 세부 사항을 설명합니다.

무엇을 만들고 무엇을 준비해야 하는가

목표: Nano-Banana-2-Lite에 prompt를 보내고, 이미지 생성을 기다린 뒤 디스크에 저장합니다.

필요한 것은 단 하나, hiapi API key(sk-...)입니다. hiapi dashboard에서 발급받으세요. 장당 비용은 pricing page와 Nano Banana 2 Lite 모델 페이지에 나와 있습니다.

hiapi의 모든 이미지 모델은 통합 async task API로 동작합니다. POST /v1/tasks로 작업을 생성한 뒤, GET /v1/tasks/{id}를 폴링하거나 작업 완료 시 webhook을 받습니다.

최소 실행 가능 요청(curl)

작업 생성:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Nano-Banana-2-Lite",
    "input": {
      "prompt": "A watercolor illustration of a lighthouse at dawn, soft pastel palette",
      "aspect_ratio": "3:2"
    }
  }'

응답의 작업 id는 data.taskId에 있습니다. 폴링하세요:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

data.status가 "success"이면 이미지 URL은 data.output[0].url에 있습니다. 즉시 다운로드하세요. 출력 URL은 서명되어 있고 만료 시간(expireAt)이 있으므로 링크가 아니라 바이트를 저장해야 합니다.

API 자체 검증에서 바로 나오는, 쉽게 빠지는 두 가지 schema 규칙:

• 모델 id는 대소문자를 구분합니다. "model": "nano-banana-2-lite"는 400 MODEL_UNAVAILABLE("model not available via /v1/tasks")을 반환합니다. 정확한 id Nano-Banana-2-Lite를 사용하세요.
• prompt와 aspect_ratio는 모두 필수입니다. 둘 중 하나라도 생략하면 400 INVALID_REQUEST와 missing required field 메시지를 받습니다. 유효한 aspect_ratio 값: auto, 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 1:4, 4:1, 1:8, 8:1.

Python에서의 동일한 흐름

SDK는 필요 없습니다. 작업 API는 HTTPS 기반 순수 JSON입니다:

import os
import time

import requests

API_BASE = "https://api.hiapi.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}

# 1. Create the task
resp = requests.post(
    f"{API_BASE}/tasks",
    headers=HEADERS,
    json={
        "model": "Nano-Banana-2-Lite",
        "input": {
            "prompt": "A watercolor illustration of a lighthouse at dawn, soft pastel palette",
            "aspect_ratio": "3:2",
        },
    },
    timeout=60,
)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task created:", task_id)

# 2. Poll until the task reaches a terminal state
deadline = time.time() + 600
while time.time() < deadline:
    task = requests.get(
        f"{API_BASE}/tasks/{task_id}", headers=HEADERS, timeout=30
    ).json()["data"]
    if task["status"] == "success":
        break
    if task["status"] == "fail":
        err = task.get("error") or {}
        raise RuntimeError(f"task failed: {err.get('code')}: {err.get('message')}")
    time.sleep(3)
else:
    raise TimeoutError(f"task {task_id} did not finish in 10 minutes")

# 3. Download immediately — output URLs are signed and expire
image_url = task["output"][0]["url"]
with open("lighthouse.png", "wb") as f:
    f.write(requests.get(image_url, timeout=120).content)
print("saved lighthouse.png")

참조 이미지로 편집: image_urls이며 image_input이 아님

Nano-Banana-2-Lite는 이미지 편집을 지원하지만, 참조 이미지 필드는 image_urls입니다. 공개 접근 가능한 URL 최대 10개의 배열입니다:

{
  "model": "Nano-Banana-2-Lite",
  "input": {
    "prompt": "Replace the background with a clean white studio backdrop, keep the product unchanged",
    "aspect_ratio": "auto",
    "image_urls": ["https://your-cdn.com/product-photo.jpg"]
  }
}

이 패밀리에서 가장 빠지기 쉬운 함정입니다. Nano-Banana-2와 Nano-Banana-Pro는 같은 목적에 image_input을 사용하지만, Lite는 이 필드를 거부합니다(additional properties 'image_input' not allowed). input_urls, images, reference_images 같은 필드명은 세 모델 모두에서 거부됩니다. 계층 간에 코드를 옮긴다면 보통 필요한 유일한 변경은 이 필드명 하나입니다.

Lite vs. Nano-Banana-2 vs. Pro: 중요한 schema 차이

	Nano-Banana-2-Lite	Nano-Banana-2	Nano-Banana-Pro
필수 입력	prompt, aspect_ratio	prompt	prompt
참조 이미지	image_urls(≤10)	image_input	image_input
resolution 제어	지원 안 함	지원	지원

Lite는 인터페이스를 극도로 단순하게 유지합니다. prompt, 종횡비, 선택적 참조 이미지뿐입니다. resolution, seed, n, negative_prompt는 없습니다. 이 중 하나라도 보내면 additional properties ... not allowed 검증 오류가 납니다. 명시적 해상도 제어(1K/2K/4K)나 더 높은 충실도 계층이 필요하면 Nano-Banana-2 또는 Nano-Banana-Pro로 업그레이드하세요. 대량 생성(썸네일, 초안, 반복 루프, 대량 변형)이라면 Lite의 더 낮은 장당 비용이 바로 존재 이유입니다.

프로덕션 환경 강화

가능하면 폴링 대신 webhook을 사용하세요. 작업 생성 시 callback 블록을 추가하면 hiapi가 최종 결과를 당신의 endpoint로 POST합니다:

{
  "model": "Nano-Banana-2-Lite",
  "input": { "prompt": "...", "aspect_ratio": "1:1" },
  "callback": { "url": "https://your-app.com/webhooks/hiapi", "when": "final" }
}

when은 "final"만 허용합니다. 성공이든 실패든 callback은 한 번만 받습니다. 폴링은 스크립트와 notebook에 적합하고, callbacks는 폴링 루프와 타임아웃을 관리할 필요가 없으므로 서버에 더 적합합니다. 정말 폴링한다면 2–5초 간격과 확실한 마감 시간(Python 예시처럼)이면 충분합니다.

두 계층의 오류를 처리하세요. 요청 수준 실패는 HTTP 오류로 반환됩니다. 무효 또는 미인증 key는 401과 {"error": {"code": "permission_denied", "type": "hiapi_error", ...}}를 반환하고, schema 오류는 400 INVALID_REQUEST와 정확한 검증 메시지를 반환합니다. 작업 수준 실패는 status: "fail"과 작업 자체의 error 객체로 도착합니다. 코드에서 두 경로 모두 처리하세요.

재시도를 멱등하게 만드세요. 작업 생성은 멱등이 아닙니다. 타임아웃된 생성 요청을 재시도하면 작업이 두 개 생길 수 있습니다(요금도 두 번). taskId를 받는 즉시 영속화하고, 재시작 후에는 무작정 다시 생성하지 말고 기존 id를 계속 폴링하세요.

URL이 아니라 바이트를 저장하세요. 출력 URL은 만료됩니다. 이미지에 다른 어떤 작업을 하기 전에 먼저 다운로드해 당신의 스토리지에 넣으세요.

관련 읽을거리

• Nano Banana 2 Lite 모델 페이지 — 파라미터, 실시간 가격, playground
• GPT Image 2 vs Nano Banana 2: 동일한 prompt로 나란히 비교
• hiapi에서 Nano-Banana로 캐릭터 일관성 유지하기
• hiapi 문서 및 가격

FAQ

왜 "model not available via /v1/tasks"가 나오나요? 모델 id는 대소문자를 구분합니다. Nano-Banana-2-Lite를 정확히 사용하세요. 소문자 변형은 400 MODEL_UNAVAILABLE과 함께 거부됩니다.

Nano-Banana-2-Lite는 이미지→이미지 편집을 지원하나요? 지원합니다. 참조 이미지를 image_urls 배열에 전달하세요(URL 최대 10개). 배경 교체, 스타일 전이, prompt 기반 지시 편집 워크플로를 처리할 수 있습니다.

왜 내 Nano-Banana-2 코드가 Lite에서 "additional properties 'image_input' not allowed"로 실패하나요? 계층마다 참조 이미지 필드명이 다릅니다. Lite는 image_urls를 기대하고, Nano-Banana-2와 Pro는 image_input을 기대합니다. 계층을 바꿀 때 필드명을 바꾸세요.

resolution, seed 또는 이미지 개수를 설정할 수 있나요? Lite에서는 안 됩니다. 입력 schema가 prompt, aspect_ratio, image_urls만 허용합니다. 1K/2K/4K resolution 제어가 필요하면 Nano-Banana-2 또는 Nano-Banana-Pro를 사용하세요.

출력 이미지 URL의 유효 기간은 얼마인가요? 만료 타임스탬프가 있는 서명 URL입니다(출력 객체의 expireAt). 즉시 바이트를 다운로드해 당신의 스토리지에 저장하세요. 작업 출력을 핫링크하지 마세요.

401 permission_denied는 무슨 뜻인가요? API key가 무효이거나 이 모델 사용이 허용되지 않은 것입니다. dashboard에서 key를 확인하고, Authorization: Bearer sk-... 형식으로 보내고 있는지 확인하세요.

Nano-Banana-2-Lite는 장당 얼마인가요? 사용량 기반, 이미지당 과금이며 Nano-Banana 패밀리에서 가장 낮은 비용 계층으로 포지셔닝되어 있습니다. 현재 요율은 pricing page를 보세요.