Nano Banana 2 API 어떻게 사용하나요? 5분 만에 첫 이미지 생성하기

TL;DR

• 무엇인가: Google이 만든 Nano Banana 2는 텍스트→이미지 생성과 참조 이미지 편집이 하나의 모델 ID nano-banana-2를 공유하며, 한 번에 최대 14장의 참조 이미지를 전송할 수 있습니다. HiAPI에 출시되어 모델 페이지 열기에서 프롬프트를 입력하면 바로 생성되며, 신규 가입 시 200 크레딧을 드립니다.
• 얼마인가: 장당 과금으로 1K $0.036, 2K $0.057, 4K $0.086이며, 참조 이미지는 추가 요금이 없고 실패 시 자동 환불됩니다.
• API 호출 방법: POST https://api.hiapi.ai/v1/tasks, model에 nano-banana-2를 쓰고, taskId를 받은 뒤 조회하거나 콜백을 기다렸다가 data.output[0].url을 다운로드합니다.

Nano Banana 2는 무엇을 할 수 있나요?

• 하나의 모델, 두 가지 용도. 프롬프트만 주면 텍스트→이미지, image_input을 더하면 참조 이미지 편집이 되며, 인터페이스나 모드를 바꿀 필요가 없습니다.
• 한 번에 최대 14장의 참조 이미지. 제품 다각도 이미지, 모델 이미지, 장면 이미지를 함께 넣어 동일 제품의 배경 교체, 의상 교체, 브랜드 세트 이미지 제작에 적합합니다.
• 14가지 고정 화면 비율과 auto. 흔한 1:1, 4:5, 16:9, 21:9 외에도 1:4, 4:1, 1:8, 8:1이 있으며, 확신이 없을 때는 기본값 auto를 사용합니다.
• 1K, 2K, 4K 세 단계. 1K는 프롬프트 시험용, 2K와 4K는 최종 결과물용이며, 기본 출력은 PNG입니다.

아래는 Nano Banana 2 모델 페이지의 예시 이미지로, 4:3, 1K로 생성했습니다:

A mystical tropical rainforest at night with hundreds of glowing fireflies, warm golden lights floating among dark green ferns and moss, soft mist, dreamy bokeh, cinematic fantasy photography, 4:3

이 프롬프트로 생성하기 →

두 가지 시작 경로: 온라인 체험인가 API인가?

효과를 먼저 보려면 온라인 체험, 제품에 연동하려면 API를 선택하세요. 두 경로는 같은 모델, 같은 가격 체계입니다.

온라인 체험 (약 1분)

1. Nano Banana 2 모델 페이지를 열거나 위 이미지 아래 링크를 클릭하면 프롬프트가 자동으로 채워집니다.
2. 가입하거나 로그인하세요. 신규 계정에는 200 크레딧이 제공됩니다.
3. 화면 비율과 해상도를 선택하세요. 일반 가격은 1K 한 장에 72 크레딧입니다.
4. 생성을 클릭하고 만족스러우면 다운로드하세요.

API 연동 (약 5분)

1. HiAPI 콘솔에서 API Key(sk-...)를 생성합니다.
2. POST /v1/tasks로 작업을 생성하고 응답에서 data.taskId를 받습니다.
3. GET /v1/tasks/{id}로 조회하거나, 요청 본문에 callback.url을 넣어 알림을 기다립니다.
4. data.status가 success가 되면 data.output[0].url에서 이미지를 다운로드합니다.

1K 한 장에 $0.036이므로 $10이면 약 277장을 생성할 수 있어 프롬프트를 조정하기에 충분합니다. 전체 파라미터는 중국어 문서를 참고하세요.

첫 이미지: curl 버전

작업 생성:

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "input": {
      "prompt": "A mystical tropical rainforest at night with hundreds of glowing fireflies, warm golden lights floating among dark green ferns and moss, soft mist, dreamy bokeh, cinematic fantasy photography",
      "aspect_ratio": "4:3",
      "resolution": "1K",
      "output_format": "png"
    }
  }'

반환된 작업 ID는 data.taskId에 있습니다:

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

결과 조회:

curl --fail-with-body -sS https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

필수는 prompt뿐입니다. aspect_ratio는 기본 auto, resolution은 기본 1K, output_format은 기본 png(선택 jpg)입니다.

첫 이미지: Python 버전

먼저 requests를 설치하고(python3 -m pip install requests), 터미널에서 HIAPI_API_KEY를 설정하세요(export HIAPI_API_KEY="sk-YOUR_KEY"). 아래 예제는 작업을 생성하고 최대 10분간 폴링한 뒤 이미지를 다운로드합니다. 시간 초과 시 taskId를 보관해 계속 조회하세요:

import os
import time
import uuid
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}
HEADERS["Idempotency-Key"] = str(uuid.uuid4())  # Save with this business task before submitting.

payload = {
    "model": "nano-banana-2",
    "input": {
        "prompt": "A mystical tropical rainforest at night with hundreds of glowing fireflies, warm golden lights floating among dark green ferns and moss, soft mist, dreamy bokeh, cinematic fantasy photography",
        "aspect_ratio": "4:3",
        "resolution": "1K",
        "output_format": "png",
    },
}


def task_data(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        raise RuntimeError(f"HiAPI request failed: {body}")
    return body["data"]


task_id = task_data(requests.post(API, headers=HEADERS, json=payload, timeout=30))["taskId"]
print(f"taskId: {task_id}", flush=True)  # Save this ID for later queries.

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    task = task_data(requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30))
    if task["status"] == "success":
        image_url = task["output"][0]["url"]
        image = requests.get(image_url, timeout=60)
        image.raise_for_status()
        with open("nano-banana-2.png", "wb") as f:
            f.write(image.content)
        break
    if task["status"] == "fail":
        raise RuntimeError(f"task {task_id} failed: {task}")
    time.sleep(3)
else:
    raise TimeoutError(f"task {task_id} is still pending; query this ID instead of submitting again")

참조 이미지 편집: image_input 하나만 더하면 됩니다

input에 image_input을 더하면 같은 요청이 편집이 됩니다. 아래는 흰 배경의 세럼 병 제품 이미지를 욕실 대리석 위에 놓는 예입니다:

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "input": {
      "prompt": "Place this exact serum bottle, unchanged, on a white marble bathroom counter next to a folded beige linen towel, soft warm morning window light",
      "image_input": ["https://static.hiapi.ai/blog/nano-banana-ecommerce-product-images-hiapi/shot-1-listing.jpg"],
      "aspect_ratio": "4:3",
      "resolution": "1K"
    }
  }'

image_input은 URL 배열로 최대 14장까지 가능하며, 공용 인터넷에서 직접 열 수 있는 이미지 링크여야 하고 SVG는 지원하지 않습니다. 프롬프트에 "무엇을 유지할지"(this exact serum bottle, unchanged)를 명확히 쓰면 제품 라벨과 병 형태가 더 안정적입니다. 이 동일 제품 배경 교체의 전체 프롬프트와 결과 이미지는 Nano Banana 2 프롬프트 대전에서 확인하세요.

출시 전 주의할 3가지

1. 서버에서는 콜백을 사용하세요. 요청 본문 최상위에 "callback": {"url": "https://yourapp.com/webhook", "when": "final"}를 넣으면 작업 종료 시 자동으로 알림을 받습니다. 성공과 실패 모두 콜백되므로 taskId로 중복을 제거하세요.
2. 재시도에는 멱등 키를 사용하세요. POST /v1/tasks는 기본적으로 매번 새 작업을 생성하고 별도로 과금합니다. 요청 헤더에 Idempotency-Key를 넣고 동일 비즈니스 작업에 대해 하나의 키를 생성해 저장한 뒤, 네트워크 시간 초과 시 같은 계정, 같은 키, 완전히 동일한 요청 본문으로 재시도하면 작업이 한 번만 생성됩니다.
3. 결과를 받으면 먼저 다운로드하세요. 출력 링크에는 유효 기간이 있으므로 먼저 이미지를 자체 저장소에 저장한 뒤 후속 처리를 하세요.

자주 나는 오류, 한 줄에 하나씩

• 400 additional properties ... not allowed → 필드명 오타이거나 다른 모델의 필드를 사용함(예: Nano Banana 2 Lite의 image_urls, size로 작성) → image_input, resolution으로 변경하세요.
• 400, aspect_ratio 값이 잘못됨 → 목록에 없는 화면 비율을 전송함 → 15개의 유효 값 중 하나를 선택하세요.
• 401 permission_denied → Key가 없거나 잘못되었거나 폐기됨 → Authorization: Bearer sk-... 요청 헤더를 확인하고 필요하면 콘솔에서 재생성하세요.
• 402 → 잔액 부족으로 작업이 생성되지 않았고 과금도 없음 → 충전 후 재시도하세요.
• 작업 status가 fail → 반환된 error에 따라 요청을 수정하고 그대로 재시도하지 마세요. 선차감 금액은 자동으로 전액 환불됩니다.

자주 묻는 질문

모델 ID는 어떻게 쓰나요? nano-banana-2로 쓰세요. 파라미터 이름은 Nano Banana 2.1과 완전히 같으며, gemini-nano-banana-2.1로 바꾸면 2.1로 전환됩니다.

참조 이미지에 추가 요금이 있나요? 없습니다. 가격은 출력 해상도에만 따르며, 참조 이미지를 1장 보내든 14장 보내든 같습니다.

한 번에 몇 장을 생성할 수 있나요? 한 작업에 한 장입니다. 여러 장이 필요하면 여러 작업을 동시에 생성하면 되며, 장당 과금됩니다.

한정 프로모션 가격은 어떻게 받나요? 코드를 바꿀 필요가 없습니다. 프로그래머 데이 50% 할인은 베이징 시간 2026-11-09 00:00까지이며, API와 온라인 체험 모두 자동으로 50% 할인이 적용되어 1K 한 장에 $0.018입니다.

Nano Banana 2 시리즈 글

• Nano Banana 2 모델 페이지: 온라인 생성, 가입 시 200 크레딧 증정
• Nano Banana 2 API 얼마인가: 1K/2K/4K 단가와 월 예산
• GPT Image 2.5 vs Nano Banana 2: 동일 프롬프트 9장 이미지 비교
• Nano Banana 2 프롬프트 대전: 5개 장면 바로 복사해 생성
• Nano Banana 2.1 API 가격: NB 2보다 얼마나 저렴한가
• Nano Banana Pro API 가격: 장당 얼마인가
• Nano Banana 2 중국어 연동 문서: 전체 파라미터

지금 바로 시도해 보세요: 위 열대 우림 이미지 아래의 이 프롬프트로 생성하기 →를 클릭하세요. 프롬프트가 이미 채워져 있고, 비율 4:3, 해상도 1K를 선택한 뒤 실행하여 결과를 다운로드하면 일반 가격 장당 $0.036입니다.