블로그

튜토리얼

HiAPI API로 nano-banana-2 사용하는 방법: 사용 가능한 curl 및 Python Requests 예제

nano-banana-2를 이미지 생성 파이프라인에 연결하는 개발자 가이드

Nov 12, 2026
미니멀 커버 이미지: 따뜻한 샌드 컬러 배경 위에 테라코타색과 브라운 톤의 가로 계단식 밴드가 수은 기둥 그래프처럼 아래로 어긋나게 배열되어 있습니다.
이 페이지에서

nano-banana-2가 할 수 있는 일과 언제 사용해야 하는가

nano-banana-2는 HTTP API 방식으로 호출하는 이미지 생성 모델입니다. 프롬프트를 보내고 선택적으로 소스 이미지를 첨부하면 생성된 이미지를 돌려받습니다. 이것이 코드를 작성하기 전에 필요한 전부입니다.

채팅 창을 통하지 않고 기존 제품이나 파이프라인에서 프로그래밍 방식으로 이미지를 생성해야 할 때 nano-banana-2를 사용하세요: 마케팅 소재 생성, 썸네일 및 커버 제작, 기준 이미지 기반 반복 수정, 또는 이미지 수량이 자체 데이터에 의해 결정되는 배치 작업 등입니다. 인터페이스가 일반적인 요청/응답형 API이므로 큐 워커, 백엔드 엔드포인트 또는 CLI 도구 뒤에 배치할 수 있으며, 언어별로 새로운 SDK를 도입할 필요가 없습니다.

두 가지 모드로 대부분의 사용 사례를 커버합니다:

  • 텍스트-이미지 — 프롬프트로 원하는 내용을 설명하면 이미지를 얻습니다.
  • 이미지-이미지 — 소스 이미지를 제공하고 변환을 설명하는 프롬프트를 추가하면 수정된 이미지를 돌려받습니다.

두 모드의 요청 형태는 동일하므로, 하나의 클라이언트 래퍼(이 글 뒤에서 구축)가 둘 다 처리할 수 있습니다. 파이프라인이 텍스트에서만 렌더링한다면 image 필드를 완전히 무시해도 됩니다. 기존 소재를 편집하는 파이프라인이라면 이미지-이미지가 진입점입니다.

nano-banana-2가 대신 해주지 않는 것: 재시도, 타임아웃, 저장 또는 멱등성을 관리하지 않습니다. 이는 호출을 둘러싸고 구축하는 부분이며, 바로 이것이 이 튜토리얼 나머지 대부분의 초점입니다. 루프 안에서 순진하게 requests.post를 호출하는 것은 "데모는 되지만 프로덕션은 안 되는" 가장 흔한 원인이기 때문입니다.

첫 번째 요청을 보내기 전에

첫 호출 전에 세 가지를 준비해야 합니다.

1. 플랫폼 자격 증명

HiAPI 플랫폼에서 API 접근 권한과 계정에 할당된 자격 증명을 받아야 합니다. 기밀로 취급하세요: 환경 변수나 비밀 관리자에서 로드하고, 절대 코드 저장소에 커밋하거나 클라이언트 패키지 산출물에 붙여넣지 마세요. 아래의 모든 요청은 환경 변수에서 키를 읽으므로 소스 코드에 민감한 정보가 나타나지 않습니다.

export HIAPI_API_KEY="your-key-here"

2. 클라이언트 환경

curl을 사용하면 curl을 실행할 수 있는 셸만 있으면 됩니다. 예제는 표준 빌드에 포함된 옵션을 사용합니다. Python을 사용하면 Python 3와 requests 라이브러리가 필요합니다:

python3 -m venv .venv
source .venv/bin/activate
pip install requests

3. 출력을 저장할 장소

이미지 생성은 이미지 데이터를 반환합니다. 응답에 인라인으로 포함될지, 나중에 가져올 수 있는 참조로 반환될지는 계정에서 반환되는 응답 형태에 따라 다릅니다. 바이트를 디스크에 저장할지, 객체 스토리지에 업로드할지, 호출자에게 URL을 반환할지 미리 결정하세요. 지금 고려하면 "셸에서는 되는데 파일을 저장할 곳이 없다"는 고전적인 난처한 상황을 피할 수 있습니다.

시작하는 데 할당량이나 가격을 추정할 필요는 없습니다. 첫 통합의 일반 원칙은 최소한의 유효한 요청을 보내고 유효한 응답을 받는지 확인한 후 매개변수를 추가하는 것입니다. 다음 섹션에서 바로 그렇게 합니다.

실행 가능한 최소 curl 요청

다음은 완전한 텍스트-이미지 호출입니다. 엔드포인트, 헤더, 요청 본문만 가변적인 부분입니다: 엔드포인트는 HiAPI 플랫폼의 모델과 작업을 식별하고, 헤더는 자격 증명을 전달하며, JSON 요청 본문은 페이로드를 전달합니다.

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "a minimalist isometric workspace, soft daylight, muted palette",
    "n": 1
  }'

HIAPI_BASE_URL을 HiAPI 계정 대시보드에 표시된 API 기본 주소로 설정하여 호스트 이름을 스크립트에 하드코딩하지 않도록 하세요. 요청 본문에는 세 개의 필드가 있으며 모두 중요합니다:

  • model은 플랫폼에 어떤 모델을 실행할지 알려줍니다. 다른 곳에서 기본값을 사용하더라도 명시적으로 유지하세요. 로그 자체가 설명이 됩니다.
  • prompt는 자연어입니다. 주제, 구도, 스타일을 구체적으로 설명하세요. 모호한 프롬프트는 모호한 이미지를 낳습니다.
  • n은 이 프롬프트에 대해 요청할 이미지 수입니다. 연결이 원활한지 확인할 때는 1부터 시작하세요.

성공적인 응답은 응답 본문에 이미지 데이터를 반환합니다. 파서를 작성하기 전에 확인하세요: 출력을 jq로 파이프하거나 파일로 리디렉션한 후 최상위 키를 살펴보세요. 두 가지를 확인하는 것입니다. 요청이 수락되었는지, 이미지 페이로드가 응답의 어디에 있는지.

첫 호출에서 매개변수를 추가하는 데 조급해하지 마세요. 이해하는 실행 가능한 기준선이 복사해 온 거대한 요청 본문보다 낫습니다. 이 호출이 이미지를 반환하면 이후 모든 섹션은 이 호출의 변형입니다.

같은 요청을 Python으로 작성하기

curl 호출을 Python으로 이식하되 페이로드는 변경하지 마세요. 단일 진실 공급원(하나의 dict)을 유지하면 셸에서 검증한 요청 본문이 실제 배포하는 요청 본문이 됩니다.

import os
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]


def generate_image(prompt: str, model: str = "nano-banana-2", n: int = 1,
                   timeout: float = 60.0) -> dict:
    """텍스트-이미지 요청을 한 번 보내고 파싱된 JSON 응답을 반환합니다."""
    payload = {"model": model, "prompt": prompt, "n": n}
    response = requests.post(
        f"{BASE_URL}/v1/images/generations",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=timeout,
    )
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    result = generate_image(
        "a minimalist isometric workspace, soft daylight, muted palette"
    )
    print(result.keys())

코드 스니펫을 복사할 때 가장 흔히 놓치는 부분이므로 세 가지 세부 사항을 강조할 가치가 있습니다.

항상 timeout을 설정하세요. 설정하지 않으면 멈춘 연결이 워커를 무기한 차단합니다. 위의 값은 시작점일 뿐 절대적인 규칙이 아닙니다. 실제로 관찰된 지연에 따라 조정하세요.

data= 대신 json=을 사용하세요. dict를 json에 전달하면 콘텐츠 유형이 올바르게 설정되고 직렬화됩니다. data에 원시 문자열을 전달하는 것이 모델 오류처럼 보이는 요청 본문 형식 오류를 일으키는 원인입니다.

파싱 전에 raise_for_status()를 호출하세요. 4xx 응답에 대해 .json()으로 이미지 필드를 파싱하려 하면 혼란스러운 다운스트림 오류가 발생합니다. 먼저 HTTP 상태 코드를 노출하세요.

이 함수가 앞서 언급한 재사용 가능한 래퍼입니다. 다음 섹션은 이를 교체하는 것이 아니라 페이로드를 확장합니다.

텍스트-이미지 및 이미지-이미지 페이로드

두 모드의 차이는 한 가지뿐입니다: 요청 본문에 소스 이미지가 포함되는지 여부. 엔드포인트, 인증 헤더, 모델 이름 등 다른 모든 것은 동일하게 유지됩니다.

텍스트-이미지

{
  "model": "nano-banana-2",
  "prompt": "a minimalist isometric workspace, soft daylight",
  "n": 1
}

이미지-이미지

{
  "model": "nano-banana-2",
  "prompt": "same scene, but converted to a warm evening palette",
  "image": "<base64-encoded source image>",
  "n": 1
}

내면화해야 할 개념: 이미지-이미지 모드에서 프롬프트는 완성된 장면을 처음부터 설명하는 것이 아니라 변환을 설명합니다. "따뜻한 저녁 팔레트로 변환"이 전체 이미지를 다시 설명하는 것보다 나은데, 소스 이미지가 이미 콘텐츠를 제공하기 때문입니다.

image 필드에 대한 두 가지 실용적인 참고 사항:

  • API가 해당 필드에 대해 문서화한 형식에 따라 소스 이미지를 인코딩하고, 인코딩된 페이로드를 요청 크기 예산보다 훨씬 작게 유지하세요. 너무 큰 입력은 요청이 거부되는 주요 원인 중 하나입니다.
  • 사용자 업로드를 받을 계획이라면 인코딩 전에 크기와 형식을 검증하세요. 여러분 쪽에서 빠르게 실패하는 것이 4xx로 끝나는 왕복보다 훨씬 저렴합니다.

Python 래퍼에 선택적 image 매개변수를 추가하면 하나의 함수로 두 모드를 모두 지원할 수 있습니다:

def generate_image(prompt: str, image: str | None = None, **kwargs) -> dict:
    payload = {"model": "nano-banana-2", "prompt": prompt, **kwargs}
    if image is not None:
        payload["image"] = image
    # ... 이전과 동일한 요청 호출

분기가 if 하나뿐이므로 호출 코드가 모드를 결정하고 전송 계층은 변경되지 않습니다. 이것이 단일 래퍼를 유지하는 보상입니다.

비동기 작업 및 재시도 처리

이미지 생성은 일반적인 JSON API 호출보다 오래 걸릴 수 있습니다. 일부 응답은 완성된 이미지를 즉시 반환하고, 다른 응답은 결과를 얻기 위해 폴링해야 하는 작업을 반환합니다. 첫 성공적인 호출이 즉시 반환되더라도 폴링 시나리오를 위해 설계하세요. 그렇지 않으면 특정 생성이 너무 오래 걸릴 때 파이프라인이 중단됩니다.

견고한 패턴은 세 부분으로 구성됩니다: 백오프가 있는 폴링 루프, 하드 데드라인, 그리고 "아직 준비 안 됨"과 "실패"를 구분하는 재시도 정책.

import time
import requests


def poll_job(job_id: str, base_url: str, api_key: str,
             initial_wait: float = 2.0, max_wait: float = 30.0,
             deadline: float = 300.0) -> dict:
    start = time.monotonic()
    wait = initial_wait
    while True:
        if time.monotonic() - start > deadline:
            raise TimeoutError(f"job {job_id} exceeded deadline")

        response = requests.get(
            f"{base_url}/v1/jobs/{job_id}",
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=30.0,
        )
        response.raise_for_status()
        body = response.json()

        status = body.get("status")
        if status == "succeeded":
            return body
        if status == "failed":
            raise RuntimeError(f"job {job_id} failed: {body}")

        time.sleep(wait)
        wait = min(wait * 2, max_wait)

작업 경로와 상태 어휘는 HiAPI 계정 API 참조에 명시된 것과 일치해야 합니다. 위의 키를 해당 형태에 맞게 조정하되 구조는 유지하세요.

프로덕션 환경에서 건강하게 유지하는 규칙:

  • 상한이 있는 지수 백오프. 200밀리초마다 폴링하면 할당량을 낭비하고 엔드포인트에 부담을 줍니다. 대기 시간을 두 배로 늘리고 상한을 설정하면 실제 완료 시간 근처에서 안정됩니다.
  • 총 시도 횟수와 총 시간 제한. deadline은 협상 불가입니다. 무한 루프는 느린 날의 장애를 기다리는 것입니다.
  • 재시도 가능한 오류만 재시도하세요. 일시적 네트워크 오류와 5xx 응답은 지터를 더해 한 번 더 시도할 가치가 있습니다. 4xx 응답은 그렇지 않습니다. 형식이 잘못된 페이로드를 다시 보내는 것은 시간 낭비입니다. 작은 유한 재시도 횟수(두세 번)를 사용하고 매번 기록하세요.
  • 재시도를 안전하게 만드세요. 작업 생성 엔드포인트가 멱등성 키를 허용한다면 각 논리적 요청에 안정적인 키를 보내 재시도 제출이 중복 생성을 일으키지 않도록 하세요.

데드라인, 백오프, 유한 재시도 횟수를 갖추면 느린 생성이 매달린 워커가 아니라 기록되고 처리되는 이벤트가 됩니다.

실제로 마주치는 오류 디버깅

호출이 실패하면 모델 매개변수를 건드리기 전에 먼저 원시 상태 코드와 전체 응답 본문을 읽으세요. 응답 본문은 보통 문제를 지적합니다. 추측하는 것이 로깅보다 느립니다.

인증 실패

401 또는 403은 거의 항상 다음 중 하나를 의미합니다: 환경 변수에 키가 없음, 헤더 형식 오류, 또는 이 환경에서 자격 증명이 활성화되지 않음. 실제로 보내는 헤더의 리터럴 값을 확인하세요. Bearer 접두사가 없거나 복사한 키에 추가 개행 문자가 포함된 것은 흔한 원인입니다.

페이로드 오류

요청 본문에 대한 메시지와 함께 오는 400은 JSON 자체에 문제가 있음을 의미합니다: prompt 누락, 불필요한 쉼표, Python에서 json= 대신 data= 사용, 또는 image 필드 인코딩 오류. 보내는 정확한 바이트를 한 번 출력하여 확인한 후 출력을 제거하세요.

입력 거부

검증을 통과하지 못한 이미지-이미지 요청은 보통 입력 이미지와 관련이 있습니다: 너무 큼, 형식 오류, 또는 디코딩 불가. 전송 전에 여러분 쪽에서 크기와 인코딩을 검증하고, 이미지를 제공한 사람에게 재시도 대신 명확한 오류를 반환하세요.

타임아웃 및 5xx

이는 재시도 가능 범주에 속합니다. 로그에서 연결 타임아웃과 서버 오류를 구분하고 재시도에 상한이 있는지 확인하세요. 그렇지 않으면 지속적인 5xx가 무한 루프가 됩니다.

효과적인 문제 해결 순서

  1. 모든 실패에 대해 HTTP 상태 코드와 원시 응답 텍스트를 기록하세요.
  2. 다른 무엇보다 먼저 자격 증명 경로를 검증하세요.
  3. 실패한 페이로드를 curl로 재생하여 클라이언트 코드를 방정식에서 제거하세요.
  4. 그 후에야 prompt, image 또는 기타 모델 매개변수를 조정하세요.

네 단계 후에도 실패가 지속되면 응답에서 요청 ID(또는 동등한 상관 필드)를 캡처하여 지원팀에 문의할 때 첨부하세요. 모호한 보고서를 추적 가능한 것으로 바꿀 수 있습니다.

프로덕션 준비 완료하기

출시 전에 이 체크리스트를 확인하세요.

  • 기밀: API 키는 환경 변수 또는 비밀 관리자에서 로드되며 로그, 오류 메시지, 클라이언트 패키지 산출물에 나타나지 않습니다.
  • 타임아웃: 모든 HTTP 호출(생성, 폴링, 결과 이미지 가져오기)에 명시적 타임아웃이 있습니다.
  • 경계: 폴링에는 데드라인이 있고 재시도에는 최대 시도 횟수가 있으며 코드에서 재시도 가능/불가능 실패를 구분합니다.
  • 관측 가능성: 모든 호출에 대해 요청 형태(프롬프트에 사용자 데이터가 포함될 수 있는 경우 생략 또는 해시), 상태 코드, 지연 시간, 상관 ID를 기록하세요.
  • 비용 인식: 과금은 HiAPI 계정에 정의된 차원을 따르므로 요청당 몇 번의 생성과 출력이 발생하는지 추적하고 자체 사용량 카운터에 계측을 추가하여 무한 루프가 청구서보다 먼저 보이도록 하세요.
  • 저장: 생성된 이미지는 컨테이너와 함께 사라지는 임시 디렉터리가 아니라 객체 스토리지나 데이터베이스 등 영구 위치에 기록하세요.

이 항목 중 nano-banana-2에 특화된 것은 없습니다. 그것이 핵심입니다: 모델 호출은 쉬운 부분이고, 그 주변의 모든 것은 평범한 분산 시스템 위생입니다. 래퍼를 한 번 구축하고 페이로드를 하나의 dict에 보관하면 텍스트-이미지와 이미지-이미지 모두 무료로 얻을 수 있습니다.

curl 호출로 시작하여 Python 래퍼로 이식하고, 폴링 루프를 추가한 후 체크리스트를 실행하세요. 모델 세부 정보와 최신 API 참조는 HiAPI 플랫폼의 nano-banana-2 문서를 참고하세요.

영구 AI 아티팩트로 빌드 시작하기

API 키를 받아 태스크 기반의 하나의 API로 이미지, 비디오, 오디오 모델을 호출하세요.

API 문서 보기