튜토리얼

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

온라인 체험 4단계, API 연동 4단계, 바로 실행 가능한 curl과 Python, 참조 이미지 편집 예제와 주요 오류 빠른 조회를 담았습니다.

Oct 10, 2026

TL;DR

무엇인가: Google이 만든 Nano Banana 시리즈의 최신 버전으로, 텍스트 투 이미지와 참조 이미지 편집이 하나의 모델 ID를 공유합니다. HiAPI에 출시되어 모델 페이지를 열고 프롬프트를 입력하면 생성할 수 있으며, 신규 가입 시 200 크레딧을 지급해 약 4장의 1K 이미지를 만들 수 있습니다.
가격: 장당 과금으로 1K $0.022, 2K $0.036, 4K $0.058이며, Nano Banana 2보다 약 33%–39% 저렴하고 참조 이미지는 추가 요금이 없습니다.
API 호출 방법: POST https://api.hiapi.ai/v1/tasks에 model을 gemini-nano-banana-2.1로 지정하고, taskId를 받은 뒤 조회하거나 콜백을 기다려 data.output[0].url에서 다운로드합니다.

막 출시된 Nano Banana 2.1에 대해 가장 많이 받는 질문은 두 가지입니다. 무엇을 할 수 있는지, 그리고 얼마나 빨리 자체 프로젝트에 연동할 수 있는지. 전자는 아래 5가지 포인트를 보면 되고, 후자는 5분이면 충분합니다.

Nano Banana 2.1로 무엇을 할 수 있나요?

NB 2보다 30~40% 저렴합니다. 동일 해상도에서 장당 약 33%–39% 저렴하며, 1K는 $0.022에 불과하고 파라미터 작성법은 NB 2와 같습니다.
참조 이미지를 한 번에 10장까지 넣을 수 있습니다. 모델, 의상, 장면, 제품 이미지를 함께 업로드해 하나로 합성할 수 있어 의상 교체와 브랜드 비주얼 제안에 적합합니다.
15가지 화면 비율, 최대 1:8 및 8:1까지. 흔한 1:1, 4:5, 16:9, 21:9 외에도 1:4, 4:1, 1:8, 8:1 같은 긴 이미지를 생성할 수 있어 상세 페이지 롱 이미지와 배너를 한 번에 만들 수 있습니다.
1K, 2K, 4K 세 가지 해상도. 1K는 프롬프트 테스트용, 2K와 4K는 최종 결과물용입니다.
텍스트 투 이미지와 편집이 같은 모델 ID입니다. 프롬프트만 주면 텍스트 투 이미지, 참조 이미지를 더하면 편집이 되어 코드를 두 벌로 나눌 필요가 없습니다.

Nano Banana 2.1 패션 화보, 2K / 16:9, 출력 2752×1536.

이 프롬프트로 생성하기 →

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

먼저 결과를 보고 싶으면 온라인 체험, 제품에 연동하려면 API를 선택하세요. 두 경로 모두 같은 모델과 같은 가격을 사용합니다.

온라인 체험 (약 1분)

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

API 연동 (약 5분)

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

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

첫 이미지: curl 버전

작업 생성:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": {
      "prompt": "A fashion editorial photograph of a model in an ivory linen blazer on a sunlit white-stucco terrace above the Mediterranean, 50mm lens, soft directional light, cinematic color grade",
      "aspect_ratio": "4:5",
      "resolution": "2K",
      "output_format": "png"
    }
  }'

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

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

결과 조회:

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

필수 항목은 prompt뿐입니다. aspect_ratio는 기본값 auto, resolution은 기본값 1K, output_format은 jpg 또는 png를 선택할 수 있습니다.

첫 이미지: Python 버전

생성, 폴링, 다운로드를 한 번에 작성했으니 복사한 뒤 자신의 Key로 바꾸면 바로 실행됩니다:

import requests, time

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

payload = {
    "model": "gemini-nano-banana-2.1",
    "input": {
        "prompt": "A fashion editorial photograph of a model in an ivory linen blazer on a sunlit white-stucco terrace above the Mediterranean, 50mm lens, soft directional light, cinematic color grade",
        "aspect_ratio": "4:5",
        "resolution": "2K",
        "output_format": "png",
    },
}

resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
task_id = resp.json()["data"]["taskId"]

while True:
    status = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if status["status"] in ("success", "fail"):
        break
    time.sleep(2)

if status["status"] == "success":
    image_url = status["output"][0]["url"]
    with open("nano-banana-2-1.png", "wb") as f:
        f.write(requests.get(image_url, timeout=60).content)
else:
    print(status.get("error"))

참조 이미지 편집: 필드 하나만 추가하면 됩니다

input에 image_input을 추가하면 같은 요청이 편집으로 바뀝니다. 아래에서는 위의 패션 화보를 참조 이미지로 사용해 재킷 색상만 바꿔보겠습니다:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": {
      "prompt": "Change the model'\''s blazer to deep burgundy silk while keeping her pose, the terrace, and the lighting unchanged",
      "image_input": ["https://static.hiapi.ai/model-examples/gemini-nano-banana-2.1/2026/10/08/1791466473082-3e77d5c2a1ef0ef6-coastal-fashion-2k.webp"],
      "resolution": "2K"
    }
  }'

image_input에는 공개 URL을 최대 10개까지 넣을 수 있고, JPEG, PNG, WebP를 지원하며 장당 30MB를 넘지 않아야 합니다. 프롬프트에서 "무엇을 바꿀지"와 "무엇을 유지할지"를 나눠 쓰고, 유지 항목을 구체적으로 적을수록 원본 이미지가 안정적으로 유지됩니다.

출시 전 주의할 3가지

서버에서는 콜백을 사용하세요. 요청 본문에 "callback": {"url": "https://yourapp.com/webhook", "when": "final"}를 추가하면 작업 종료 시 자동으로 알림을 받아 폴링을 생략할 수 있습니다.
타임아웃 시 POST를 반복하지 마세요. POST /v1/tasks를 호출할 때마다 새 작업이 생성되고 별도로 과금됩니다. 먼저 taskId를 저장하고, 재시도 전에 자체 시스템에서 중복을 제거하세요.
모든 요청에 resolution을 명시하세요. 해상도가 곧 단가를 결정하므로 요청에 고정해 두어야 청구서를 예측할 수 있습니다.

주요 오류, 한 줄씩

400 additional properties '<field>' not allowed → 필드명 오타이거나 다른 모델의 필드(예: image_urls)를 사용한 경우 → 문서를 대조해 image_input 등 올바른 필드명으로 수정하세요.
400, aspect_ratio 값이 잘못되었다는 안내 → 목록에 없는 화면 비율을 전달한 경우 → 오류에 나열된 15개 유효 값 중 하나를 선택하세요.
401 permission_denied → Key가 없거나 잘못되었거나 폐기된 경우 → Authorization: Bearer sk-... 요청 헤더를 확인하고 필요하면 콘솔에서 Key를 재생성하세요.
생성은 성공했지만 작업 상태가 fail / INVALID_REQUEST → 참조 이미지 URL에 접근할 수 없거나 이미지가 아닌 경우 → 공개적으로 바로 접근 가능한 JPEG, PNG 또는 WebP로 교체하세요.
이미지 링크가 며칠 후 열리지 않음 → 출력 링크에 유효 기간이 있는 경우 → 결과를 받은 즉시 다운로드해 파일 자체를 저장하세요.

실패한 작업의 사전 차감 금액은 자동으로 전액 환불됩니다.

자주 묻는 질문

Nano Banana 2.1로 NB 2를 바로 대체할 수 있나요? 가능합니다. 파라미터 이름이 완전히 같아 model을 gemini-nano-banana-2.1로 바꾸면 전환되며, 동일 해상도에서 장당 약 33%–39% 저렴합니다. 유일하게 주의할 점은 2.1의 기본 출력이 JPG이므로 PNG가 필요하면 "output_format": "png"를 명시해야 한다는 것입니다.

참조 이미지에 추가 요금이 부과되나요? 아니요. 가격은 출력 해상도만 따르며, 참조 이미지를 1장 넣든 10장 넣든 같습니다.

투명 배경을 생성할 수 있나요? 출력 형식은 jpg 또는 png이며, 투명 배경素材가 필요하면 GPT Image 2.5를 선택하세요. 이 모델은 1K에서 background: transparent를 지원합니다.

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

Nano Banana 2.1 시리즈 글

지금 바로 체험하세요. 위 패션 화보 아래의 이 프롬프트로 생성하기 →를 클릭하세요. 프롬프트가 이미 채워져 있으니 2K, 16:9를 선택하고 클릭 한 번이면 같은 결과를 얻을 수 있습니다.

태그이미지 생성 튜토리얼 API 연동 튜토리얼

모든 아티클 보기 →