Nano Banana API 가이드: HiAPI에서 nano-banana, nano-banana-2, nano-banana-pro 호출하기

Nano Banana 모델 패밀리가 제공하는 것

이미지 생성은 하나의 설정에 머무는 경우가 거의 없습니다. 프로젝트 초기에는 아이디어를 탐색하기 위해 빠른 초안이 필요하고, 후반에는 납품을 위해 정교한 렌더링이 필요합니다. HiAPI의 Nano Banana 패밀리는 바로 이 현실을 중심으로 구축되었습니다. 하나의 인터페이스, 세 가지 변형, 각각 품질과 속도 곡선의 서로 다른 지점에 맞춰 조정됩니다.

이름은 의도적으로 붙여졌습니다. nano-banana는 기본 옵션으로, 프롬프트나 레이아웃을 다듬는 동안 여전히 빠른 시각적 피드백이 필요할 때 사용합니다. nano-banana-2는 충실도와 프롬프트 준수도에서 한 단계 더 나아가며, 보통 출력이 최종본에 가까우면서도 계속 반복하고 싶을 때의 선택입니다. nano-banana-pro는 패밀리 내에서 충실도가 가장 높은 변형으로, 디테일과 구도가 가장 중요한 최종 렌더링에 적합합니다.

이들이 공유하는 부분은 서로 다른 부분만큼이나 중요합니다. 세 모델 모두 동일한 HiAPI 엔드포인트를 통해 호출됩니다. 한 번만 인증하고 요청을 한 번만 구성하면, 전환 시에는 모델 식별자만 바꾸면 됩니다. 즉, 애플리케이션이 기본 모델로 요청을 시작한 뒤 전송 계층 코드를 건드리지 않고도 더 강력한 변형에서 동일한 프롬프트를 다시 실행할 수 있습니다.

이런 패밀리 구조는 아키텍처도 단순하게 유지합니다. 품질 계층마다 별도 공급자를 연결할 필요 없이 단일 클라이언트, 단일 오류 처리 경로, 단일 사용량 관측 지점만 유지하면 됩니다. 모델 선택은 통합 작업이 아니라 하나의 매개변수가 됩니다.

단일 모델이 아닌 패밀리인 이유

워크플로의 각 단계는 서로 다른 요구를 가집니다. 프롬프트 탐색, 레이아웃 초안, 고객 미리보기는 속도를 중시합니다. 키 비주얼과 마케팅 자료는 충실도를 중시합니다. 모델 선택을 런타임 결정으로 취급하면 파이프라인을 다시 구축하지 않고도 각 단계를 적합한 변형에 매칭할 수 있습니다.

nano-banana, nano-banana-2, nano-banana-pro 중에서 선택하기

두 가지 질문으로 변형을 선택하세요. 이 출력이 최종본에 얼마나 가까운가, 그리고 그것에 도달하기 위해 몇 번의 시도가 필요한가? 나머지는 여기서 결정됩니다.

nano-banana: 배치와 탐색용

이미지가 어떤 모습이어야 하는지 아직 결정 중일 때 기본 모델을 사용하세요. 프롬프트 재작성, 스타일 테스트, 레이아웃 썸네일은 모두 빠른 처리 속도의 이점을 누리며, 대략적인 렌더링이 서술보다 질문에 더 잘 답해주는 경우가 많습니다. 개발 중에는 이를 기본값으로 유지하세요.

nano-banana-2: 최종에 가까운 반복용

구도가 안정되었고 디테일 — 간격, 피사체 충실도, 출력이 프롬프트를 얼마나 긴밀히 따르는지 — 을 정교하게 다듬고 있을 때 nano-banana-2로 전환하세요. 이는 실용적인 중간 선택입니다. 매번 미리보기마다 최고 충실도 경로를 거치지 않고도 준수도가 확실히 더 강해집니다.

nano-banana-pro: 최종 렌더링용

nano-banana-pro는 납품할 출력을 위해 남겨두세요. 키 비주얼, 제품 이미지, 고객이 꼼꼼히 살펴볼 모든 콘텐츠는 더 강력한 변형을 쓸 가치가 있습니다. 이를 기본값으로 설정하지 마세요. 마지막 단계를 위해 남겨두어 탐색적 반복을 저비용으로 유지하세요.

실용적인 라우팅 규칙

간단한 에스컬레이션 전략이 대부분의 팀에 적용됩니다.

• 모든 새 프롬프트는 기본적으로 nano-banana를 사용합니다.
• 구조는 맞지만 품질이 부족할 때 프롬프트를 nano-banana-2로 승격합니다.
• 프롬프트가 확정되면 nano-banana-pro에서 최종 버전을 한 번 실행합니다.

이렇게 하면 반복이 빠르고 예측 가능해지며 사용량 패턴도 이해하기 쉬워집니다. 청구는 사용량을 따르며 변형에 따라 다르므로, 어떤 숫자도 코드에 하드코딩하지 말고 실시간 모델 문서에서 현재 요율과 제한을 확인하세요.

모든 변형에 통용되는 프롬프트 패턴

가장 비용이 많이 드는 일은 한 모델에서만 통하는 프롬프트를 작성하는 것입니다. 한 줄만 바꾸면 전환할 수 있는 구조로 만드세요.

네 블록 프롬프트

모든 프롬프트를 다음 순서로 네 개의 라벨이 붙은 부분으로 작성하세요.

1. 피사체 — 이미지에 무엇이 있는지 평이하게 서술.
2. 스타일 — 시각적 처리 방식: 사진, 일러스트, 수채화, 3D 렌더링.
3. 구도 — 프레이밍, 카메라 각도, 위치, 여백.
4. 제약 — 피해야 할 것과 하드 요구사항.

작성 예시:

Subject: a ceramic coffee mug on a wooden desk, steam rising
Style: soft natural light, shallow depth of field, editorial photography
Composition: centered, 50mm equivalent, generous negative space at top
Constraints: no text, no logos, neutral background

블록이 서로 독립적이므로 프롬프트 전체를 다시 쓰지 않고도 스타일을 강화하거나 구도를 완화할 수 있습니다. 또한 동일한 구조를 패밀리의 모든 변형이 쉽게 이해합니다.

프롬프트를 모델 독립적으로 만들기

특정 모델의 특성을 가정한 표현은 피하세요. 특정 모델이 취해야 할 단계가 아니라 원하는 결과를 설명하세요. 변형을 비교해야 할 때는 모델 ID만 바꾸고 프롬프트는 바이트 단위로 동일하게 유지해야 비교가 의미를 가집니다.

프롬프트를 코드처럼 버전 관리하기

프롬프트를 설정 파일이나 작은 프롬프트 라이브러리에 문자열로 저장하고 이름과 버전으로 색인하세요. 어떤 변형이 미세 조정을 통해 더 나은 출력을 낸다면 그 변경을 기록하세요. 이것이 바로 프롬프트가 납품 시점에 nano-banana에서 nano-banana-pro로 예상치 못한 문제 없이 이전되도록 하는 이유입니다.

부정 제약이 중요합니다

어떤 프롬프트가 계속 텍스트, 로고 또는 원치 않는 객체를 생성한다면, 이를 제약 블록에 명시적으로 추가하세요. 변형 간에 명확한 부정 제약이 교묘한 표현보다 더 신뢰할 수 있는 경우가 많습니다.

HiAPI에서 동작하는 요청 구성하기

모든 변형은 동일한 HiAPI 엔드포인트를 통해 호출됩니다. 요청에는 네 가지 가변 부분이 있습니다. 기본 URL, 인증 헤더, 모델 필드, 그리고 페이로드입니다.

요청의 형태

최소한의 이미지 생성 호출은 다음과 같습니다.

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "Subject: a ceramic coffee mug on a wooden desk, steam rising\nStyle: soft natural light, editorial photography\nComposition: centered, negative space at top\nConstraints: no text, no logos",
    "n": 1
  }'

API 키는 환경 변수나 비밀 관리자에 보관하세요. 소스 코드에는 절대 두지 마세요. model 필드는 변형을 바꿀 때 변경할 유일한 내용이며, prompt 필드는 이전 섹션의 네 블록 구조를 담습니다.

Python에서는 동일한 호출이 몇 줄이면 됩니다.

import os, requests

def generate(prompt, model="nano-banana-2"):
    resp = requests.post(
        "https://api.hiapi.ai/v1/images/generations",
        headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
        json={"model": model, "prompt": prompt, "n": 1},
        timeout=60,
    )
    resp.raise_for_status()
    return resp.json()

응답에 포함되는 것

응답은 이미지 결과 — 보통 URL 또는 인코딩된 페이로드 — 와 해당 요청을 처리한 모델을 식별하는 메타데이터를 담습니다. 모델 필드를 다시 읽어 기록하세요. 사후에 어떤 변형이 주어진 자산을 생성했는지 판단하는 가장 저렴한 방법입니다.

납품 전 매개변수 확인

선택적 매개변수의 정확한 집합은 변형에 따라 다르며 시간이 지나면서 진화합니다. model과 prompt 이외의 내용을 하드코딩하기 전에, 실시간 모델 문서에서 현재 필드 이름과 허용 값을 확인하세요. 문서화되지 않은 것은 추측하지 말고 지원되지 않는 것으로 취급하세요.

응답, 실패, 재시도 처리하기

이미지 생성은 뒤에 모델이 있는 네트워크 호출이므로 실패하는 부분을 대비해야 합니다.

신뢰하기 전에 검증하기

매 응답 후 세 가지를 확인하세요. HTTP 상태, 이미지 페이로드의 존재 여부, 반환된 모델이 요청한 것과 일치하는지 여부. 불일치가 있으면 잘못된 자산을 다운스트림으로 전달하지 말고 명시적으로 실패시키세요.

재시도할 가치가 있는 실패만 재시도하기

모든 오류가 재시도할 가치가 있는 것은 아닙니다. 형식이 잘못된 프롬프트나 유효하지 않은 모델 이름은 매번 동일하게 실패합니다. 요청을 수정해야 합니다. 타임아웃, 연결 재설정, 속도 제한 응답 같은 일시적 실패는 재시도할 가치가 있습니다.

지터를 포함한 유계 지수 백오프를 사용하세요.

import time, random

def call_with_retry(fn, retries=3):
    for attempt in range(retries):
        try:
            return fn()
        except (TimeoutError, ConnectionError):
            if attempt == retries - 1:
                raise
            time.sleep((2 ** attempt) + random.random())

총 시도 횟수를 제한하여 손상된 요청이 무한 루프에 빠지지 않게 하고, 각 시도의 모델과 프롬프트 해시를 기록하여 특정 변형이 불안정한지 확인하세요.

의도적으로 폴백하기

어떤 변형이 계속 실패한다면 패밀리의 다른 구성원으로 폴백하면 파이프라인이 살아있게 유지됩니다. 세 모델이 요청 형태를 공유하므로 폴백은 재시도 시 다른 model 값을 사용하는 것에 불과합니다. 순서를 미리 정하세요. 예를 들어 고충실도 호출이 반복 실패할 때 nano-banana-pro에서 nano-banana-2로 폴백하고, 언제 폴백이 발생했는지 기록하여 패턴을 알아차리세요.

실패를 가시화하기

반환된 페이로드를 저장하기 전에 먼저 검증하고, 재시도와 폴백에 대해 지표를 내보내세요. 오류율이 상승할 때 일련의 작업이 조용히 빈 결과를 내기 전에 미리 알고 싶을 것입니다.

납품 전 강화 점검

이미지 생성을 사용자에게 노출하기 전에 이 체크리스트를 훑어보세요.

ID와 매개변수 확인

모델 식별자는 변합니다. Nano Banana 패밀리의 현재 모델 이름을 다시 확인하고, 각 선택적 매개변수를 실시간 문서와 대조하여 확인하세요. 오래된 예시에만 존재하는 값을 납품하지 마세요.

설정 중앙화

모델 ID, 프롬프트 템플릿, 재시도 제한을 하나의 설정 모듈에 두세요. 프롬프트를 nano-banana에서 nano-banana-pro로 승격할 때 이것은 여러 파일에 분산된 코드 변경이 아니라 하나의 설정 변경이어야 합니다.

중요 정보 기록

매 호출마다 모델, 프롬프트 버전, 응답 상태, 지연 시간, 재시도 또는 폴백이 발생했는지 여부를 기록하세요. 긴 프롬프트는 해시처리하여 로그를 읽기 쉽게 유지하세요. 이것이 바로 “왜 어제 이 이미지가 다르게 보였나?”라는 질문에 답할 수 있게 하는 이유입니다.

확장 시 사용량 모니터링

청구가 사용량을 따르므로 호출 횟수와 변형 구성을 주시하세요. 매 요청이 조용히 nano-banana-pro로 승격되면 탐색 도구가 비용 문제로 바뀔 수 있습니다. 반복에는 저렴한 변형, 최종 출력에는 더 강력한 변형을 쓰도록 의식적으로 라우팅하세요.

엔드포인트 테스트

고정 프롬프트로 각 변형을 한 번씩 호출하고 응답이 유효한지 검증하는 작은 스모크 테스트를 작성하세요. 매 릴리스 전에 현재 문서에 대해 실행하면 모델 변경이 프로덕션 환경에서 발목을 잡는 일이 없습니다.

단일 클라이언트, 공유 프롬프트 라이브러리, 의식적인 라우팅 전략으로 납품한다면, HiAPI의 Nano Banana 패밀리는 초안에서 최종 렌더링으로 통합을 다시 작성하지 않고 확장할 수 있는 유일한 의존성이 될 것입니다.