HiAPI API로 Nano-Banana-2-Lite를 사용하는 방법: curl, Python 그리고 실제 작동하는 요청

Nano-Banana-2-Lite란 무엇이며 언제 사용하는가

Nano-Banana-2-Lite는 HiAPI의 Nano-Banana 제품군 중 초저비용 티어입니다. 동시성이 높고 비용에 민감한 이미지 생성 시나리오를 위해 설계되었으며, 이러한 시나리오에서는 최고 수준의 충실도보다 예측 가능한 비용과 빠른 반복을 더 중요하게 여깁니다. 기능을 프로토타이핑하거나, 썸네일 또는 변형을 대량 생성하거나, 더 가벼운 모델을 감당할 수 있는 백그라운드 작업을 실행할 때 이 티어가 적합한 출발점입니다.

출력이 더 큰 파이프라인의 일부일 때 사용하세요: 초안 비주얼, 플레이스홀더 이미지, 대량 실험, 또는 저비용으로 많은 후보가 필요한 A/B 테스트 등입니다. 최종 메인 비주얼 소재나 최고 디테일이 필요한 장면에는 더 큰 티어로 업그레이드하세요. API 인터페이스는 동일하게 유지되므로 통합을 다시 작성하지 않고도 모델을 전환할 수 있습니다.

사전 요구 사항 및 요청 구조

Nano-Banana-2-Lite를 호출하기 전에 다음을 준비하세요:

• HiAPI 계정과 API 키. 환경 변수(예: HIAPI_API_KEY)에 저장하세요; 절대 소스 코드 관리에 커밋하지 마세요.
• 첫 테스트용으로 curl이 있는 터미널, 그리고 스크립트 버전용으로 Python 3.8+와 requests 라이브러리.
• 원하는 이미지를 설명하는 프롬프트. 간단하게 시작하고 나중에 참조 입력을 추가할 수 있습니다.

HiAPI에 대한 모든 요청은 동일한 구조를 따릅니다: JSON 본문과 함께 POST를 모델 엔드포인트로 전송합니다. 요청 본문에는 모델 이름, 프롬프트 및 선택적 매개변수가 포함됩니다. 생성은 비동기이므로 제출 호출은 작업 식별자를 반환하고, 그런 다음 해당 작업을 폴링합니다. 응답은 JSON이며, 오류에는 상태 코드와 기록할 수 있는 메시지가 포함됩니다.

페이로드에는 최소한 model을 nano-banana-2-lite로 설정하고 prompt를 제공해야 합니다. reference_images 및 출력 설정과 같은 선택적 필드는 이후 섹션에서 다룹니다.

작동하는 curl 요청

다음은 기본 작업을 제출하기 위한 완전하고 복사해서 바로 호출할 수 있는 예제입니다. 자리 표시자 프롬프트를 자신의 내용으로 바꾸세요.

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-lite",
    "prompt": "A cozy reading nook by a rainy window, warm lamp light, soft focus",
    "aspect_ratio": "1:1"
  }'

응답에는 작업 id와 status 필드가 포함됩니다. 새로 제출된 작업은 일반적으로 queued 또는 processing을 반환합니다. 해당 id를 저장하세요; 폴링 단계에서 사용하게 됩니다. 401이 발생하면 HIAPI_API_KEY가 셸에 내보내졌는지 확인하세요. 422가 발생하면 오류 메시지를 확인하여 문제가 있는 필드를 찾으세요.

Python으로 동일한 요청 보내기

curl 호출을 Python으로 이식하여 스크립트나 서비스에 넣으세요. 이 예제는 requests를 사용하고 환경 변수에서 키를 읽습니다.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/images/generations"

payload = {
    "model": "nano-banana-2-lite",
    "prompt": "A cozy reading nook by a rainy window, warm lamp light, soft focus",
    "aspect_ratio": "1:1",
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()
job = response.json()
print(job["id"], job["status"])

요청 본문을 딕셔너리에 보관하여 호출을 다시 작성하지 않고도 선택적 필드로 확장할 수 있습니다. 무거운 작업은 비동기로 수행되므로 제출 단계에서는 30초 타임아웃이 합리적입니다.

선택적 참조 입력 추가하기

참조 입력을 사용하면 시각적 컨텍스트로 생성을 유도할 수 있습니다. HiAPI에서는 동일한 JSON 본문의 reference_images 배열로 첨부합니다. 각 항목은 공개적으로 접근 가능한 URL 또는 base64 데이터 URI입니다. 구도를 유지하거나, 스타일을 맞추거나, 제품 이미지를 여러 변형 간에 일관되게 유지하고 싶을 때 참조 이미지를 사용하세요.

{
  "model": "nano-banana-2-lite",
  "prompt": "Same layout, but in a warm sunset palette",
  "reference_images": [
    "https://example.com/reference/layout.png"
  ]
}

참조 이미지가 유효한 신호를 제공할 때만 포함하세요. 각 참조 이미지는 전송해야 하는 추가 데이터이며 단순한 프롬프트를 희석시킬 수 있습니다. 순수한 텍스트-이미지 작업의 경우 필드를 완전히 생략하세요. 참조 이미지를 실제로 사용할 때는 관련성 있고 적게 유지하세요; 신중하게 선택한 한두 장의 이미지가 큰 세트보다 일반적으로 더 우수합니다.

비동기 결과 폴링하기

이미지 생성은 비동기입니다: 작업을 제출한 다음 상태가 최종 상태가 될 때까지 작업 엔드포인트를 폴링합니다. curl과 Python 모두에서 패턴은 동일합니다.

curl을 사용할 때 작업 id로 작업을 확인합니다:

curl https://api.hiapi.ai/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Python에서는 API를 너무 자주 요청하지 않도록 지연이 있는 루프로 폴링을 감싸세요:

import time

def wait_for_job(job_id, interval=2, max_attempts=30):
    url = f"https://api.hiapi.ai/v1/jobs/{job_id}"
    headers = {"Authorization": f"Bearer {API_KEY}"}
    for _ in range(max_attempts):
        r = requests.get(url, headers=headers, timeout=30)
        r.raise_for_status()
        data = r.json()
        if data["status"] in ("succeeded", "failed"):
            return data
        time.sleep(interval)
    raise TimeoutError("Job did not finish in time")

짧은 간격으로 시작하고, 많은 작업을 폴링하는 경우 점진적으로 백오프하세요. 항상 최대 시도 횟수를 설정하여 멈춘 작업이 워커 프로세스를 영구적으로 차단하지 않도록 하세요. failed를 최종 상태로 간주하고 오류 메시지를 기록하세요.

출력 다운로드 및 검증하기

작업이 성공하면 응답에는 하나 이상의 출력 URL이 포함됩니다. 파일을 가져와 로컬에 저장한 다음 받은 내용을 검증하세요.

result = wait_for_job(job["id"])
if result["status"] == "succeeded":
    image_url = result["output"]["url"]
    img = requests.get(image_url, timeout=60)
    img.raise_for_status()
    with open("output.png", "wb") as f:
        f.write(img.content)

다운로드한 내용에 대해 기본 검사를 수행하세요: 콘텐츠 유형이 이미지인지 확인하고, 파일 크기가 0이 아니고 합리적인지 확인하며, 한 번 열어 프롬프트와 일치하는지 확인하세요. 작업 id를 로컬 파일 이름과 함께 기록하여 모든 소재를 해당 요청으로 추적할 수 있도록 하세요.

프로덕션 배포 전 비용 및 장애 체크리스트

Nano-Banana-2-Lite는 초저비용 티어로 책정되며, 과금은 플랫폼의 표준 이미지 생성 계량을 따릅니다. 가정을 하드코딩하지 말고 정확한 요금은 웹사이트의 현재 가격 패널을 확인하세요.

배포 전에 다음 습관을 들이세요:

• 백오프를 동반한 재시도. 일시적 오류(타임아웃, 5xx)는 지연을 늘리며 소수만 재시도하고, 4xx 검증 오류는 재시도하지 마세요.
• 폴링 제한. 고정 간격과 최대 시도 횟수를 사용하세요. 최종 상태와 소요 시간을 기록하세요.
• 작업 id와 프롬프트 기록. 작업 id, 프롬프트, 모델 및 모든 참조 입력을 각 출력과 함께 저장하여 실행을 재현하거나 감사할 수 있도록 하세요.
• 입력을 조기에 검증. 제출 전에 프롬프트 길이와 참조 URL을 확인하여 작업을 낭비하지 않도록 하세요.

이러한 검사를 갖추면 Nano-Banana-2-Lite는 배치 및 백그라운드 생성을 위한 예측 가능한 저비용 주력 도구입니다. 최신 매개변수 및 요금 세부 정보는 HiAPI의 모델 페이지를 살펴보세요.