사용 가이드

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

온라인 체험 4단계, API 연동 4단계, 바로 실행 가능한 curl과 Python, 참고 이미지 편집 예시 및 자주 발생하는 오류 빠른 조회를 제공합니다.

Oct 12, 2026

TL;DR

무엇인가요: Google에서 출시한 Gemini 3 Pro Image로, Nano Banana 시리즈의 플래그십 등급이며 텍스트-이미지 생성과 참고 이미지 편집이 모델 ID nano-banana-pro를 공유합니다. HiAPI에 이미 출시되었으며, 모델 페이지 열기에서 프롬프트를 입력하면 생성할 수 있습니다. 신규 사용자 가입 시 200 크레딧을 증정하며, 일반 가격 기준 2K 이미지 1장을 생성할 수 있습니다.
얼마인가요: 장당 과금, 1K와 2K 동일 가격 $0.057, 4K $0.1, 출력 이미지 1장당 계산되며 Google 공식 표준가 대비 약 57%–58% 저렴하고, 참고 이미지는 추가 요금이 없습니다.
API는 어떻게 호출하나요: POST https://api.hiapi.ai/v1/tasks, model에 nano-banana-pro를 입력하고, taskId를 받은 후 조회하거나 콜백을 기다린 뒤 data.output[0].url을 다운로드합니다.

Google의 입력 토큰 비용은 별도로 부과되며, 위 가격 차이는 출력 이미지 1장당 가격을 비교한 것입니다.

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

2K 추가 요금 없음. 1K, 2K 모두 $0.057 한 장으로, 바로 2K 결과물을 생성합니다. 4K는 $0.1 한 장으로 인쇄 및 대형 화면용입니다.
글자를 화면에 써넣기. 간판, 포스터 제목, 날짜 같은 영문 짧은 문구를 프롬프트에 직접 작성할 수 있습니다. 아래 금박 간판의 두 줄 글자는 한 번에 정확히 생성되었으며 후처리가 전혀 없습니다.
최대 8장 참고 이미지. 프롬프트만 작성하면 텍스트-이미지 생성이고, image_input을 추가하면 편집 또는 다중 이미지 융합이 됩니다. 동일한 모델 ID로 코드를 두 세트로 나눌 필요가 없습니다.
10가지 화면 비율 및 auto. 1:1, 4:5, 3:4, 9:16, 16:9, 21:9 등 일반적인 비율을 모두 지원합니다. 1:4, 8:1 같은 긴 이미지가 필요하거나 참고 이미지를 8장 초과로 한 번에 전송하려면 Nano Banana 2(최대 14장)를 선택하세요.

Nano Banana Pro 원본, 보정 없음, 출력 1536×2752.

A hand-painted gold-leaf sign in a modern specialty coffee shop window, elegant serif lettering reading 'MORNING BREW CO.' with a small script subtitle 'est. 2024' beneath it, warm natural daylight streaming through the glass, soft bokeh reflections of a city street, photorealistic commercial photography, crisp perfectly legible typography with correct spelling, shallow depth of field, editorial lighting

이 프롬프트로 생성하기 →, 화면 비율은 9:16, 해상도는 2K를 선택하세요.

두 가지 시작 방법: 온라인 체험 vs API?

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

온라인 체험(약 1분)

Nano Banana Pro 모델 페이지를 열거나 위 간판 이미지 아래 링크를 직접 클릭하면 프롬프트가 자동으로 입력됩니다.
회원가입 또는 로그인하세요. 신규 계정에는 200 크레딧이 제공됩니다.
화면 비율과 해상도를 선택하세요. 일반 가격 기준 1K, 2K 모두 114 크레딧 한 장입니다.
실행을 클릭하고 만족스러우면 다운로드하세요.

API 연동(약 5분)

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

2K 한 장 $0.057, $10으로 약 175장 생성 가능합니다. 프로그래머의 날 한정 50% 할인은 베이징 시간 2026-11-09 00:00까지이며, 기간 중 1K, 2K 장당 $0.0285로 동일한 $10으로 약 350장 생성 가능합니다. 전체 파라미터는 중국어 문서를 참고하세요.

첫 이미지: 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-pro",
    "input": {
      "prompt": "Minimalist studio product photography, matte-black earbuds case on a warm gradient backdrop, three-point studio lighting",
      "aspect_ratio": "16:9",
      "resolution": "2K",
      "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도 선택할 수 있습니다. 1K와 2K는 동일 가격이므로 모든 요청에 "resolution": "2K"를 작성하는 것을 권장합니다.

첫 이미지: Python 버전

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

import os
import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

payload = {
    "model": "nano-banana-pro",
    "input": {
        "prompt": "Minimalist studio product photography, matte-black earbuds case on a warm gradient backdrop, three-point studio lighting",
        "aspect_ratio": "16:9",
        "resolution": "2K",
        "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-pro.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")

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

input에 image_input을 추가하면 동일한 요청이 편집으로 바뀝니다. 아래는 Nano Banana Pro로 생성한 과학관 포스터를 참고 이미지로 사용하여 날짜 줄만 변경하는 예시입니다:

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-pro",
    "input": {
      "prompt": "Keep this exact poster: layout, planet, observatory, visitor, colors and headline. Change only the date line to SAT 24 OCT in the same typography and color. No other words.",
      "image_input": ["https://static.hiapi.ai/blog/gpt-image-2-vs-nano-banana-pro/0dba86ff979d-nano-pro-science.png"],
      "aspect_ratio": "1:1",
      "resolution": "2K"
    }
  }'

image_input에는 최대 8개의 공개 URL을 넣을 수 있으며, JPEG, PNG, WebP를 지원합니다. 프롬프트에 "무엇을 변경할지"와 "무엇을 유지할지"를 구분하여 작성하고, 유지 항목이 구체적일수록 원본 이미지가 안정적으로 유지됩니다.

출시 전 주의할 3가지

서버에서는 콜백을 사용하세요. 요청 본문 최상위에 "callback": {"url": "https://yourapp.com/webhook", "when": "final"}을 추가하면 작업 종료 시 자동으로 알림을 받아 폴링을 생략할 수 있습니다. 콜백이 중복 도착할 수 있으므로 taskId로 중복 제거하세요.
타임아웃 시 POST를 반복하지 마세요. POST /v1/tasks를 호출할 때마다 새 작업이 생성되고 별도로 과금됩니다. 먼저 taskId를 저장하고, 재시도 전에 자체 시스템에서 중복 제거하세요.
모든 요청에 resolution을 명시하세요. 기본값은 1K이며 2K 가격이 동일하므로 최종 확정 시 2K를 직접 선택할 수 있습니다. 4K는 단가가 더 높으므로 배포 단계에서만 사용하세요.

자주 발생하는 오류, 한 줄씩

400, 필드가 허용되지 않는다는 메시지 → 필드명 오타 또는 다른 모델의 필드 사용(예: image_urls) → image_input으로 변경하세요.
400, aspect_ratio 값이 잘못되었다는 메시지 → 목록에 없는 화면 비율(예: 8:1) 사용 → 10가지 화면 비율과 auto 중에서 선택하고, 긴 이미지는 Nano Banana 2로 변경하세요.
401 → Key 누락, 오타 또는 폐기됨 → Authorization: Bearer sk-... 요청 헤더를 확인하고 필요 시 콘솔에서 Key를 재생성하세요.
생성 성공했지만 작업이 fail → 작업에서 반환된 오류를 확인하세요. 참고 이미지를 열 수 없거나 지원되지 않는 형식인 경우 공개 접근 가능한 JPEG, PNG 또는 WebP로 교체한 후 다시 제출하세요.
이미지 링크가 만료되어 열 수 없음 → 출력 링크에 유효기간이 있음 → 결과를 받은 즉시 다운로드하여 파일 자체를 저장하세요.

실패한 작업은 과금되지 않습니다.

자주 묻는 질문

Nano Banana Pro와 Nano Banana 2 중 어떻게 선택하나요? 2K 생성 시 둘 다 동일 가격으로 $0.057 한 장입니다. 긴 화면 비율이나 8장 초과 참고 이미지가 필요하면 Nano Banana 2, Nano Banana 시리즈의 플래그십 등급으로 브랜드 메인 비주얼을 생성하려면 Pro를 선택하세요.

참고 이미지에 추가 요금이 부과되나요? 아니요. 가격은 출력 해상도만 기준으로 하며, 참고 이미지를 1장 전송하든 8장 전송하든 동일합니다.

Nano Banana 2에서 바로 전환할 수 있나요? 가능합니다. 필드명이 동일하며(prompt, image_input, aspect_ratio, resolution, output_format), model을 nano-banana-pro로 변경하면 됩니다. 화면 비율은 Pro가 지원하는 10가지 이내여야 합니다.

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

Nano Banana Pro 시리즈 글

지금 바로 시도해 보세요: 위 간판 이미지 아래의 이 프롬프트로 생성하기 →를 클릭하세요. 프롬프트가 이미 입력되어 있으며, 9:16, 2K를 선택하고 따옴표 안의 텍스트를 자신의 가게 이름으로 바꾼 후 실행하세요.

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

모든 아티클 보기 →