블로그

튜토리얼

Nano-Banana-2 API 튜토리얼: hiapi로 정상 작동하는 curl과 Python Requests 사용하기

Nov 10, 2026
플랫 레이 커버 아트: 가장자리가 차콜색인 본 화이트 종이 시트들이 오프셋으로 층층이 쌓여 있고 그중 한 장은 러스트 레드 시트, 16:9.
이 페이지에서

첫 호출 전 준비 작업

Nano-Banana-2에 어떤 요청이든 보내기 전에 네 가지를 먼저 준비하세요. 모두 많은 시간이 걸리지 않으며, 네 가지를 모두 갖추면 첫 요청은 보물찾기가 아니라 복사-붙여넣기 연습이 됩니다.

1. hiapi 계정과 API 키

모든 요청은 hiapi 계정에 연결된 API 키로 인증됩니다. 계정 대시보드에서 키를 생성하고 안전한 곳에 보관하세요——비밀번호 관리자나 머신의 환경 변수를 사용하면 됩니다. 비밀번호처럼 취급하세요: 코드 저장소에 절대 커밋하지 말고, 공유 문서에 붙여넣지도 마세요.

머신에서 셸 세션마다 한 번 내보내면 아래 예제가 아무것도 하드코딩하지 않고도 키를 읽을 수 있습니다:

export HIAPI_API_KEY="your_api_key_here"

2. API 기본 URL

기본 URL은 모든 요청이 구축되는 루트 주소입니다. 엔드포인트를 구성할 때 모델 라우트를 그 뒤에 붙입니다. 기본 URL은 여러 파일에 흩어 놓지 말고 코드의 설정 변수에 두세요——그러면 변경이 생겨도 한 줄만 고치면 됩니다.

3. 요청을 보내는 클라이언트

시작할 때는 다음 중 하나만 있으면 됩니다:

  • curl —— 거의 확실히 이미 설치되어 있습니다. 애플리케이션 코드를 작성하기 전에 키와 요청 본문이 올바른지 확인하는 데 사용하세요.
  • Python 3와 requests 라이브러리(pip install requests). 대부분의 독자는 실제 통합을 구축할 때 이것을 사용합니다.

둘 다 준비해 두면 유용합니다: curl은 요청을 코드와 분리해 주므로 문제가 생겼을 때 API 호출 문제인지 애플리케이션 문제인지 알 수 있습니다.

4. 무엇을 생성할지 명확히 하기

Nano-Banana-2는 텍스트-이미지와 이미지-이미지를 모두 지원합니다. 어떤 모드를 필요한지 미리 결정하세요. 요청 본문 구조가 다르기 때문입니다(뒤에서 자세히 설명). 첫 호출은 변수가 가장 적은 텍스트-이미지로 시작하세요.

키를 내보내고 클라이언트를 설치하고 프롬프트도 생각해 두었다면, 이제 요청 자체를 살펴볼 차례입니다.

Nano-Banana-2 요청의 구성 요소

Nano-Banana-2 호출은 JSON 요청 본문을 가진 POST 요청입니다. 각 필드는 제 역할이 있으며, 따로따로 이해하면 문제가 생겼을 때 한 번에 한 곳만 수정할 수 있습니다.

엔드포인트

요청은 hiapi API 기본 URL에 Nano-Banana-2 모델 라우트를 붙인 주소로 전송됩니다. 메서드는 항상 POST입니다. 리소스를 가져오는 것이 아니라 처리할 페이로드를 보내기 때문입니다.

요청 헤더

중요한 헤더는 두 가지입니다:

  • Content-Type: application/json —— API에 요청 본문을 어떻게 파싱할지 알려줍니다.
  • Authorization —— API 키를 담습니다. 아래 예제는 앞서 내보낸 환경 변수에서 키를 읽습니다.

둘 중 하나라도 빠지거나 형식이 잘못되면 모델이 요청을 보기도 전에 실패합니다. 이것이 혼란스러운 오류의 가장 흔한 단일 원인입니다.

요청 본문 필드

텍스트-이미지 요청은 다음 필드를 가집니다:

  • model —— 실행할 모델이 Nano-Banana-2임을 지정합니다. 기본값이 있더라도 명시적으로 작성하세요. 코드가 스스로를 설명하게 하고, 기본값이 바뀔 때 보호받을 수 있습니다.
  • prompt —— 원하는 이미지를 자연어로 설명합니다. 대부분의 반복 작업이 여기서 일어납니다. 구체적으로 작성하세요: 피사체, 구도, 스타일, 조명. 모호한 프롬프트는 모호한 결과를 낳습니다.
  • 이미지 입력 —— 텍스트-이미지에서는 생략되거나 비어 있습니다. 이미지-이미지에서는 참조 이미지를 담습니다(이미지-이미지 부분에서 더 설명).
  • 출력 및 크기 매개변수 —— 반환 결과의 형태나 비율에 영향을 주는 모델 특유의 필드입니다. 모델 문서에서 지원한다고 명시한 필드만 설정하세요. 엄격한 API에서는 알 수 없는 필드가 조용히 무시되는 대신 요청 거부를 의미하는 경우가 많습니다.

반환 내용

응답은 JSON입니다. 호출 구성에 따라 생성된 이미지 데이터를 직접 받거나 그에 대한 참조를 받습니다. 클라이언트 코드는 반환 본문을 보기 전에 먼저 HTTP 상태를 확인해야 합니다——200 형태의 응답이 반드시 이미지를 포함한다고 검증 없이 가정하지 마세요.

구조는 이게 전부입니다: 몇 개의 명시적 JSON 요청 본문을 가진 인증된 POST 요청. 이 튜토리얼의 나머지는 모두 이 형태의 변형입니다.

작동하는 curl 요청

이것은 보낼 수 있는 최소한의 완전한 호출입니다. API 키를 내보낸 터미널에서 실행하면 몇 초 안에 계정, 키, 네트워크 경로가 모두 정상인지 알 수 있습니다.

curl -X POST "$HIAPI_BASE_URL/nano-banana-2" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "A weathered cabin on a rocky coastline at dawn, low fog, soft warm light, wide composition"
  }'

셸에서 키와 함께 기본 URL을 한 번 설정하세요:

export HIAPI_BASE_URL="https://api.hiapi.ai"

(hiapi 대시보드에 표시된 기본 URL을 사용하세요——그것이 계정의 권위 있는 값입니다.)

출력 읽기

curl은 원시 응답을 stdout에 출력합니다. 호출이 성공하면 생성된 이미지를 포함한 JSON이 보입니다. python -m json.tool로 파이프하면 출력을 보기 좋게 만들고 구조를 확인할 수 있습니다:

curl -s -X POST "$HIAPI_BASE_URL/nano-banana-2" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -d '{"model":"nano-banana-2","prompt":"a red fox in fresh snow, side profile, crisp detail"}' \
  | python -m json.tool

보이는 내용 해석하기

  • 성공 응답 —— 키가 유효하고 엔드포인트가 올바르며 요청 본문이 파싱됨을 확인합니다. 이 작동하는 명령을 저장하세요——이것이 기준선입니다.
  • 오류 응답 —— 세 줄의 요청 헤더나 요청 본문 중 어딘가가 잘못되었음을 의미합니다. 오류 텍스트를 복사하세요. 디버깅 부분에서 흔한 오류를 수정 방법에 매핑합니다.

curl로 시작하는 가치는 격리에 있습니다. 키, 헤더, JSON이 한곳에서 보이므로 실패는 애플리케이션 코드가 아니라 요청 자체를 가리킵니다. 이 명령이 작동하면 Python으로 옮기는 것은 기계적인 작업입니다.

같은 요청을 Python으로 구현하기

다음은 requests로 구현한 동일한 호출입니다. 요청 본문은 curl 요청 본문에서 본 것과 같은 dict입니다——API 자체는 변하지 않고, 보내는 방식만 변합니다.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai")

payload = {
    "model": "nano-banana-2",
    "prompt": "A weathered cabin on a rocky coastline at dawn, low fog, soft warm light, wide composition",
}

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}",
}

response = requests.post(
    f"{BASE_URL}/nano-banana-2",
    json=payload,
    headers=headers,
    timeout=120,
)

response.raise_for_status()
data = response.json()
print(data)

왜 이렇게 작성하는가

  • json=payload는 requests가 dict를 직렬화하고 Content-Type을 설정하게 합니다. 여전히 해당 헤더를 명시적으로 전달할 수 있습니다. 해로울 것도 없고 요청이 스스로를 설명하게 됩니다.
  • timeout=120 —— 이미지 생성은 즉각적이지 않습니다. 넉넉한 타임아웃은 모델이 아직 작업 중인데 클라이언트가 포기하는 것을 방지합니다. 사용 사례에 맞게 이 값을 조정하세요.
  • raise_for_status()는 2xx가 아닌 응답을 예외로 바꾸므로 실패가 결과 처리 코드로 조용히 흘러가는 대신 즉시 드러납니다.
  • 환경 변수는 키를 소스 코드에서 멀리 떨어뜨립니다. 프로덕션에서는 커밋될 수 있는 .env 파일 대신 플랫폼의 키 저장소에서 주입하세요.

이미지 추출하기

응답 본문은 JSON입니다. 먼저 한 번 대화형으로 살펴보고 정확한 구조를 파악한 뒤, 이미지 필드를 명시적으로 꺼내세요:

image_url = data["image_url"]  # confirm the key name against a real response

응답이 URL이 아니라 base64 데이터를 담고 있다면 디코딩해서 작성하세요:

import base64

with open("output.png", "wb") as f:
    f.write(base64.b64decode(data["image_base64"]))

필드 이름을 추측하지 마세요——첫 성공 호출에서 원시 응답을 출력하고 실제로 존재하는 내용을 기준으로 값을 꺼내세요. 이 습관 하나가 대부분의 통합 결함을 예방합니다.

텍스트-이미지 vs 참조 이미지를 사용한 이미지-이미지

지금까지는 텍스트-이미지였습니다: 프롬프트를 입력하고 이미지를 출력합니다. Nano-Banana-2는 이미지-이미지도 지원하며, 참조 이미지를 제공하면 모델이 이를 지침으로 사용합니다. 언제 모드를 전환해야 하는지, 요청 본문이 어떻게 달라지는지 아는 것이 성공과 거부 사이의 차이입니다.

각 모드를 언제 사용할지

  • 텍스트-이미지 —— 텍스트로 표현한 아이디어가 있고 시작 이미지가 없을 때. 탐색, 일러스트레이션, 그리고 처음부터 생성하는 모든 콘텐츠에 가장 적합합니다.
  • 이미지-이미지 —— 가지고 있는 이미지에 변형, 재스타일링, 또는 구조나 피사체를 유지한 편집을 원할 때. 반복 디자인, 시각 스타일 맞추기, 사진 변환에 사용하는 모드입니다.

프롬프트가 "이걸 ~처럼 보이게 만들어줘" 또는 "레이아웃은 유지하되…"라면 이미지-이미지가 필요합니다.

참조 이미지가 요청을 어떻게 바꾸는지

엔드포인트와 요청 헤더는 그대로입니다. 변하는 것은 요청 본문입니다: 프롬프트 옆에 참조 이미지 필드를 추가합니다. 이미지 제공 방식에 따라 이 필드는 URL이나 인코딩된 이미지 데이터를 담습니다. 다음 규칙을 기억하세요:

  • 링크를 전달할 때는 공개적으로 직접 접근 가능한 URL을 사용하세요. 로그인이나 인증 리다이렉트를 거치는 페이지는 실패합니다——API는 바이트를 직접 가져와야 합니다.
  • 예상 형식을 맞추세요. PNG, JPEG 같은 일반적인 형식은 안전합니다. 비정상적이거나 손상된 파일은 요청 거부의 흔한 원인입니다.
  • 업로드 전에 크기 제한을 확인하세요. 큰 이미지는 요청 본문 오류의 빈번한 원인입니다.
  • 프롬프트를 집중시키세요. 참조 이미지가 있을 때는 참조 이미지를 다시 설명하지 말고 원하는 변환을 설명하세요.

示意적인 이미지-이미지 요청 본문은 다음과 같습니다:

payload = {
    "model": "nano-banana-2",
    "prompt": "Same subject, restyled as a graphite sketch with light crosshatching",
    "image_url": "https://example.com/your-reference.jpg",
}

늘 그렇듯이 첫 성공 응답으로 정확한 필드 이름을 확인하세요. 원칙은 간단합니다: 텍스트-이미지는 프롬프트만 있고, 이미지-이미지는 같은 요청 형태에 검증된 참조 이미지를 더합니다. 먼저 텍스트-이미지로 흐름이 작동함을 증명한 다음 참조 이미지를 얹으세요.

오류 처리 및 실패한 요청 디버깅

Nano-Banana-2 호출 실패는 세 가지 범주로 귀결됩니다. 각각을 식별하는 법을 배우면 대부분의 문제를 1분 안에 고칠 수 있습니다.

인증 오류

인증 오류가 보이면 키가 API에 올바르게 도달하지 않은 것입니다. 순서대로 확인하세요:

  • HIAPI_API_KEY가 요청을 실행하는 셸이나 환경에 실제로 내보내졌습니까? echo $HIAPI_API_KEY를 실행해 확인하세요.
  • Authorization 헤더가 존재하고 형식이 올바릅니까? 스킴과 키 모두 중요합니다.
  • 키가 대시보드에서 취소되었거나 교체되었습니까?
  • 계정의 올바른 기본 URL에 접근하고 있습니까?

401 또는 403은 거의 항상 이 네 가지 중 하나를 의미합니다. 키 자체가 문제인 경우는 드물고, 그 주변의 파이프라인이 보통 문제입니다.

요청 본문 형식 오류

400 계열 오류는 보통 API가 요청 본문을 파싱하거나 검증할 수 없음을 의미합니다:

  • 유효하지 않은 JSON —— 중복 쉼표, 큰따옴표 대신 작은따옴표, 또는 이스케이프되지 않은 문자. curl 출력을 python -m json.tool로 파이프하고, 코드에서 요청 본문을 수작업이 아니라 생성하면 도움이 됩니다.
  • 필수 필드 누락 —— model과 prompt를 가장 자주 잊습니다. 매번 둘 다 명시적으로 보내세요.
  • 알 수 없거나 지원되지 않는 필드 —— 엄격한 API는 인식하지 못하는 필드를 거부합니다. 요청이 통과할 때까지 모든 군더더기를 제거한 뒤 한 번에 하나씩 다시 추가하세요.
  • 잘못된 값 유형 —— 숫자를 문자열로 보내거나, 단일 값을 기대하는 곳에 배열을 전달하는 경우. 문서의 유형과 엄격히 일치시키세요.

잘못된 이미지 입력

이미지-이미지에만 관련되지만 발생하면 가장 답답한 문제입니다: 인증이 필요한 이미지 URL, 리다이렉트 뒤에 있는 URL, 이미지 대신 HTML을 반환하는 URL, 너무 큰 크기, 또는 지원되지 않는 형식. URL이 로그인 없이 브라우저에서 직접 로드되는지 확인하고, 보내기 전에 제한에 비추어 파일 유형과 크기를 점검하세요.

효과적인 디버깅 순서

  1. 오류 메시지와 상태 코드를 문자 그대로 읽으세요——보통 문제를 지목합니다.
  2. 최소한의 필드로 curl에서 실패한 요청을 재현한 뒤, 복잡성을 단계적으로 다시 추가하세요.
  3. 처리하기 전에 전체 응답 본문을 출력하세요. 구조에 대한 가정에 의존하지 마세요.

최소화된 curl 호출은 성공하는데 애플리케이션이 실패한다면 결함은 API가 아니라 코드에 있습니다. 이것이 가장 빠른 진단 분기점입니다.

애플리케이션에 연결하기

작동하는 요청은 좋은 시작이지만, 신뢰할 수 있는 통합에는 주변에 몇 가지가 더 필요합니다. 일회성 호출에서 의존할 수 있는 것으로 넘어가는 방법입니다.

호출을 함수로 캡슐화하기

요청을 함수 하나에 격리하고, 프롬프트(선택적으로 참조 이미지)를 받아 결과를 반환하게 하세요. 요청 헤더, 기본 URL, 요청 본문 구성은 함수 내부에 두어 코드베이스의 다른 부분이 절대 건드리지 않게 하세요. API가 변하면 한 곳만 편집하면 됩니다.

의도적으로 재시도 처리하기

생성은 요청 본문과 무관한 이유로 일시적으로 실패할 수 있습니다. 지수 백오프로 재시도하되 재시도 가능한 실패——타임아웃 및 일부 서버 측 오류——에만 적용하세요. 인증이나 요청 본문 검증 오류는 절대 재시도하지 마세요. 매번 같은 방식으로 실패하며 부하만 늘립니다. 시도 횟수를 제한해 지속적인 문제가 계속 매달리지 않고 드러나게 하세요.

타임아웃과 동시성

생성에 충분히 넉넉하되 상한이 있는 타임아웃을 설정하고, 실제 응답 시간을 측정한 뒤 조정하세요. 많은 요청을 보낼 경우 한꺼번에 모두 보내지 말고 합리적인 동시성 제한을 지키세요——작업 풀이 있는 큐가 무제한 병렬 호출보다 예측 가능합니다.

생성한 콘텐츠 저장하기

응답은 생성된 이미지를 줍니다. 반환된 URL이 무기한 유효하다고 의존하지 말고 적시에 자신의 저장소로 복사하세요. 파일 이름을 결정론적으로 정하고 각 출력 옆에 프롬프트와 매개변수를 기록하세요——나중에 프롬프트를 반복할 때 이 출처 정보가 필요합니다.

키를 코드에서 멀리 두기

각 환경에서 환경 변수나 키 관리자로 API 키를 읽으세요. 정기적으로 키를 교체하세요. 키가 있어서는 안 될 곳에 나타나면 대시보드에서 취소하세요.

작게 시작하고 확장하기

하나의 프롬프트를 curl에서 작동시키고, Python으로 옮기고, 이전 섹션의 오류 처리를 추가한 다음에 주변의 큐와 저장소를 구축하세요. 각 단계가 이전 단계를 증명합니다.

검증된 curl 호출, 일치하는 Python 클라이언트, 그리고 처리된 세 가지 오류 범주를 갖추면 첫 요청부터 프로덕션 통합까지의 전체 경로를 갖게 됩니다.

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

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

API 문서 보기