튜토리얼
HiAPI API로 Nano-Banana를 사용하는 방법: curl, Python 및 실행 가능한 요청
이 페이지에서
Nano-Banana가 API로서 개발자에게 제공하는 것
Nano-Banana는 HiAPI API를 통해 외부에 제공되는 이미지 생성 모델입니다. 프롬프트를 보내고—필요하다면 하나 이상의 참조 이미지를 첨부하고—생성된 이미지를 받습니다. 전체적인 사고 모델은 이렇게 간단합니다. 로컬에서 모델을 호스팅할 필요도, GPU를 준비할 필요도, 별도의 SDK를 배울 필요도 없습니다. 다른 HiAPI 모델을 사용할 때 적용했던 인증 방식, 요청 래핑, 비동기 작업 메커니즘이 여기에도 그대로 적용됩니다.
코드를 작성하기 전에 이미지 생성 엔드포인트가 무엇이고 무엇이 아닌지 명확히 하는 것이 도움이 됩니다. 이것은 창의적 엔드포인트입니다. 동일한 프롬프트가 여러 실행에서 다른 결과를 낼 수 있으므로, 파이프라인이 이를 견딜 수 있도록 설계해야 합니다. 크기 조정이나 형식 변환처럼 결정론적인 변환이 아닙니다. 픽셀 단위로 정확한 재현성이 필요하다면, 재생성이 동일한 결과를 낼 것이라고 가정하지 말고 검수를 통과한 출력을 캐시하세요.
일반적인 통합은 세 단계로 나뉩니다:
- 프롬프트와 선택적 입력을 포함하여 생성 요청을 제출합니다.
- 이미지 생성은 단순한 텍스트 완성보다 오래 걸리므로 생성된 작업이 완료되기를 기다립니다.
- 출력을 가져와 저장하고, 이를 수용할지 아니면 프롬프트를 조정하여 재시도할지 결정합니다.
처음부터 결정해야 할 두 가지가 있는데, 이는 다른 모든 것에 영향을 미치기 때문입니다. 프롬프트가 순수 텍스트인지 아니면 참조 이미지를 사용하는지(이것이 요청 페이로드를 바꿉니다), 그리고 여러 생성에서 캐릭터 일관성을 유지해야 하는지(이는 거의 항상 참조 이미지를 사용해야 함을 의미합니다)입니다. 다음 섹션들은 요청 구조에서부터 바깥으로 확장되며, 예시를 보면서 조정할 수 있습니다.
Nano-Banana 요청의 구조 분석
HiAPI를 통해 Nano-Banana를 호출하는 모든 요청은 뼈대가 동일합니다. 달라지는 것은 페이로드뿐입니다.
엔드포인트와 인증
요청은 HiAPI의 기본 URL로 전송되며, 구체적인 모델은 직접 조합한 업스트림 URL이 아니라 요청 페이로드에서 지정됩니다. Authorization 헤더에 API 키를 담아 인증합니다. 키는 환경 변수에 보관하세요—절대 소스 코드에 인라인으로 넣거나 저장소에 커밋하지 마세요.
모델 이름
모델 식별자는 JSON 요청 본문의 필드입니다. 직접 조합한 것이 아니라 모델 목록에서 그대로 복사해야 하는 문자열로 취급하세요. 그래야 이름 변경이 코드를 조용히 망가뜨리지 않습니다.
프롬프트 페이로드
최소한 목표 이미지를 설명하는 텍스트 프롬프트를 보내야 합니다. 여기서 프롬프트 품질이 출력 품질에 미치는 영향은 다른 어떤 필드보다 큽니다. 피사체, 구도, 조명, 스타일을 구체적으로 설명하세요. 모호한 프롬프트는 모호한 이미지를 생성하며, 어떤 파라미터 설정도 정말로 원하는 것을 제대로 말하지 않은 프롬프트를 구제하지 못합니다.
선택적 참조 이미지
참조 이미지를 포함하는 경우, 이들은 동일한 요청 본문에 속합니다—일반적으로 모델이 허용하는 형식에 따라 이미지 URL 또는 인코딩된 이미지 데이터로 제공됩니다. 참조 이미지는 캐릭터의 얼굴, 의상, 전체 예술 스타일 등을 고정할 수 있습니다. 순수 텍스트-이미지 생성 시에는 생략하고, 출력이 특정 대상과 유사해야 할 때 포함하세요.
출력 관련 필드
일부 필드는 내용이 아니라 결과 형식에 영향을 줍니다. 예를 들어 요청된 출력 크기나 종횡비가 그렇습니다. 이들을 보장된 값이 아니라 요청 값으로 보는 것이 좋습니다—모델이 반환하는 크기는 약간 다를 수 있습니다. 다운스트림 코드는 요청한 값이 곧 받은 값이라고 가정하지 말고 실제 반환된 크기를 읽어야 합니다.
다음은 개념적인 구조로, 자리 표시자 값을 사용했습니다:
{
"model": "<nano-banana-model-id>",
"prompt": "금빛 시간대의 키 큰 풀밭에 앉아 있는 붉은 여우, 얕은 심도",
"reference_images": [],
"size": "1024x1024"
}
정확히 허용되는 필드 이름과 형식은 해당 모델의 파라미터 문서를 참고하세요—위 구조는 일반적인 패턴일 뿐이며 규격 문서를 대체하지 않습니다.
실행 가능한 curl 요청
키가 작동하고 페이로드가 유효한지 확인하는 가장 빠른 방법은 curl 호출을 한 번 실행하는 것입니다. 먼저 환경을 설정하세요:
export HIAPI_API_KEY="your-api-key-here"
그런 다음 생성 요청을 제출하세요:
curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<nano-banana-model-id>",
"prompt": "금빛 시간대의 키 큰 풀밭에 앉아 있는 붉은 여우, 얕은 심도",
"size": "1024x1024"
}'
각 부분의 역할:
- URL — HiAPI의 이미지 생성 경로입니다. 하나의 기본 URL이 모든 모델을 서비스하며, 모델은 요청 본문에서 지정됩니다.
Authorization— 환경에서 읽은 키로, 셸 기록이나 소스 관리에 남지 않게 합니다.Content-Type— 반드시application/json이어야 합니다. 흔한 초보자 실수는 이를 설정하는 것을 잊어 파싱 오류를 얻는 것입니다.- 요청 본문 — 이전 섹션의 JSON 페이로드로, 실제로 원하는 프롬프트를 포함합니다.
응답 해석
응답은 무슨 일이 일어났는지 알려줍니다. 주목할 두 가지 결과가 있습니다:
- 동기 결과 — 일부 호출은 이미지 데이터나 이미지 URL을 직접 반환합니다. URL이 보이면 장기적인 가용성에 의존하지 말고 가능한 한 빨리 가져와 저장하세요.
- 작업 핸들 — 생성이 비동기인 경우, 응답에는 상태를 폴링할 식별자가 포함됩니다. 이것이 아래 비동기 섹션의 주제입니다.
응답 본문 외에 HTTP 상태 줄과 헤더도 함께 보고 싶다면 curl 명령에 -i를 추가하세요—오류 발생 시 인증 문제인지 페이로드 문제인지 구분하는 데 매우 유용합니다.
Python에서의 동일한 호출
일회성 스크립트가 아니라면 Python을 사용하세요. requests 라이브러리는 예제의 의존성을 가볍게 유지하고 HTTP 계층을 명시적으로 보이게 합니다.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"
payload = {
"model": "<nano-banana-model-id>",
"prompt": "금빛 시간대의 키 큰 풀밭에 앉아 있는 붉은 여우, 얕은 심도",
"size": "1024x1024",
}
response = requests.post(
f"{BASE_URL}/images/generations",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)
처음부터 길러야 할 몇 가지 습관:
- 타임아웃을 설정하세요. 이미지 생성은 느립니다. 타임아웃이 없으면 워커 프로세스가 무기한 멈출 수 있습니다. 동기 호출의 경우 넉넉한 타임아웃이 합리적인 출발점이지만, 워크로드에 맞게 조정하세요.
raise_for_status()를 사용하세요. 4xx 및 5xx 응답을 잡을 수 있는 예외로 변환하여, 오류 응답 본문을 결과로 조용히 파싱하는 일을 막습니다.- 함수로 감싸세요. 위 코드 조각은 스크립트입니다. 서비스에서는 프롬프트를 받아 이미지 데이터나 작업 핸들을 반환하는 함수가 필요하며, 그래야 다른 코드가 HTTP 세부 사항을 신경 쓰지 않아도 됩니다.
응답에 이미지 URL이 포함되어 있으면 즉시 다운로드하여 저장하세요:
for item in data.get("data", []):
url = item.get("url")
if url:
img = requests.get(url, timeout=60)
img.raise_for_status()
with open("output.png", "wb") as f:
f.write(img.content)
애플리케이션의 실제 데이터 소스는 자체 스토리지여야 합니다—일시적인 원격 URL이 아닙니다.
비동기 작업 처리
이미지 생성은 일반적으로 단일 HTTP 왕복이 연결을 유지해야 하는 시간보다 오래 걸립니다. 이러한 방식을 채택한 HiAPI 모델은 제출 시 작업 식별자를 반환하고, 이후 작업 상태 엔드포인트를 폴링하여 작업이 완료될 때까지 기다립니다. 이 패턴은 플랫폼의 모든 비동기 모델에 적용되므로 한 번만 배우면 됩니다.
먼저 제출하고, 그다음 폴링
최초의 POST는 작업 ID와 유사한 것을 반환합니다. 그런 다음 해당 ID로 상태 엔드포인트를 폴링합니다. 필요한 로직은 다음과 같습니다:
import time
def poll_task(task_id, api_key, interval=2, max_wait=300):
headers = {"Authorization": f"Bearer {api_key}"}
deadline = time.time() + max_wait
while time.time() < deadline:
r = requests.get(
f"https://api.hiapi.ai/v1/tasks/{task_id}",
headers=headers,
timeout=30,
)
r.raise_for_status()
body = r.json()
status = body.get("status")
if status in ("succeeded", "completed", "failed", "error"):
return body
time.sleep(interval)
raise TimeoutError(f"작업 {task_id}이(가) {max_wait}초 내에 완료되지 않았습니다")
실수를 줄여주는 세 가지 규칙
- 항상 총 대기 시간을 제한하세요. 끝나지 않는 작업이 워커 프로세스를 붙잡고 있게 해서는 안 됩니다. 위의
max_wait가 탈출 경로입니다. - 백오프하세요. 고정된 짧은 간격은 대화형 사용에는 괜찮습니다. 배치 작업의 경우 대기 시간이 길어질수록 간격을 늘려 상태 엔드포인트를 자주 때리지 않도록 하세요.
- 종료 상태를 확인하세요.
succeeded는 출력을 읽을 수 있음을 의미합니다.failed는 무작정 재시도하지 말고 오류 페이로드를 읽어야 함을 의미합니다. 형식이 잘못된 페이로드를 재시도하는 것은 시간 낭비일 뿐입니다.
작업 ID를 자체 작업 기록과 함께 영속화하세요. 프로세스가 폴링 중간에 재시작되면 다시 제출하여 중복 생성 비용을 지불하지 않고 폴링을 계속할 수 있습니다.
참조 이미지와 캐릭터 일관성
순수 텍스트 프롬프트는 일회성 이미지에는 문제없지만, 열 가지 다른 장면에서 동일한 캐릭터가 필요할 때는 역부족입니다. 얼굴을 글로 설명한 뒤 모델이 안정적으로 재현해 주기를 기대하는 것은 거의 통하지 않습니다—표현의 미세한 변화가 다른 사람을 생성합니다.
참조 이미지가 이 문제를 해결합니다. 요청에 텍스트 프롬프트와 함께 하나 이상의 이미지를 포함하면 모델이 이를 시각적 앵커로 사용합니다. 캐릭터 일관성이 핵심 사용 사례입니다:
- 캐릭터 설정 시트 — 깔끔한 참조 이미지 하나, 여러 장면 프롬프트, 일관된 얼굴과 의상.
- 스타일 고정 — 참조 이미지가 시각 언어를 설정하고, 프롬프트가 내용을 이끕니다.
- 제품 사진 — 객체의 참조 이미지가 다양한 배경에서도 디자인을 안정적으로 유지합니다.
요청에서는 빈 값을 보내는 대신 참조 이미지 필드를 채워야 합니다. 모델 파라미터 명세가 지원하는 형식에 따라 URL 또는 인코딩된 데이터로 이미지를 제공하고, 참조 이미지를 깔끔하게 유지하세요. 명확한 피사체 하나가 어수선한 장면보다 낫습니다. 모델은 당신이 관심 있는 부분만이 아니라 화면의 모든 것을 붙잡기 때문입니다.
파이프라인의 실용적인 패턴:
- 상세한 텍스트 프롬프트로 캐릭터를 한 번 생성합니다.
- 검토하고, 만족할 때까지 수용하거나 재생성합니다.
- 검수를 통과한 이미지를 이후 모든 장면의 참조 이미지로 사용합니다.
이것이 nano banana API python 워크플로의 축약입니다. 먼저 캐릭터를 한 번 고정한 다음, 프롬프트의 장면 부분만 바꾸세요. 반복을 예상하세요—참조 이미지는 일관성을 높이지만 완벽할 수는 없으므로 모든 출력이 사용 가능하다고 가정하지 말고 검토 단계를 구축하세요.
출력 해상도와 실제 제약
해상도는 가정으로 인해 문제가 생기기 가장 쉬운 부분이므로 신중하게 다루어야 합니다.
요청 크기와 실제 크기
출력 크기를 요청할 수 있지만, 이는 힌트로 취급해야 합니다. 모델이 반환하는 크기는 요청한 것과 다를 수 있습니다—특히 흔하지 않은 종횡비의 경우 더욱 그렇습니다. 견고한 방법은 실제로 받은 이미지 크기를 읽어 범용적으로 처리하는 것입니다. 스토리지, 썸네일, 레이아웃 모두 요청 값이 아니라 실제 파일을 기준으로 해야 합니다.
품질을 결정하는 것
출력 품질은 주로 프롬프트에 의해 결정되며, 사용하는 경우 참조 이미지에 의해서도 결정됩니다. 구도가 좋고 피사체와 조명이 명확한 프롬프트가 모호하지만 더 큰 크기를 요청한 프롬프트보다 더 나은 이미지를 만들어냅니다. 해상도로 불충분한 설명을 보상하려 하지 마세요.
제약을 고려한 계획
- 크기를 하드코딩하지 마세요 다운스트림 코드에. 반환된 이미지에서 읽으세요.
- 저장 전에 검증하세요. 애플리케이션이 최소 크기를 요구한다면 생성 후 실제 크기를 확인하고, 부족하면 재생성하세요—요청이 이미 해당 요구를 강제했다고 가정하지 마세요.
- 파일 크기에 주의하세요. 고해상도 출력은 더 큰 페이로드를 의미합니다. 루프에서 모든 것을 메모리에 올리지 말고 스트리밍하거나 버퍼링하여 다운로드하세요.
- 배치 처리를 신중하게 하세요. 동시성 제한은 계정 단위로 적용됩니다. 대량의 이미지를 생성하려면 무제한 루프에서 요청을 퍼붓지 말고 백오프 재시도를 갖춘 작은 워커 풀을 추가하세요.
Nano-Banana의 권위 있는 기능과 허용 값은 이 문서의 예시 페이로드가 아니라 해당 모델의 문서를 참고하세요. 과금은 플랫폼의 일반적인 사용량 기반 과금 방식을 따르며, 현재 요금은 이 튜토리얼이 아닌 가격 패널에서 확인하세요.
일반적인 오류 문제 해결
대부분의 첫 통합 실패는 몇 가지 범주에 속합니다. 다음은 각 범주의 점검 사항입니다.
401 / 403 — 인증
키가 없거나, 형식이 잘못되었거나, 전송되지 않았습니다. Authorization 헤더가 존재하고 Bearer 접두사가 붙어 있는지, 환경 변수가 실제로 코드를 실행하는 셸이나 프로세스에 내보내졌는지 확인하세요. 키를 복사할 때 끝에 추가된 줄바꿈 문자가 이 문제를 일으키는 빈도가 예상보다 높습니다.
400 — 페이로드 형식 오류
일반적으로 다음 중 하나입니다: 유효하지 않은 JSON(불필요한 따옴표나 후행 쉼표), 잘못된 Content-Type, 필수 필드 누락(prompt 또는 model 등), 또는 모델이 허용하지 않는 형식으로 참조 이미지 필드를 보낸 경우입니다. 실제로 전송한 정확한 요청 본문을 출력하여 파라미터 명세와 필드별로 비교하세요.
404 — 경로 또는 모델 오류
엔드포인트 경로가 잘못되었거나 모델 식별자가 플랫폼의 어떤 모델과도 일치하지 않습니다. 기억에 의존해 입력하지 말고 목록에서 모델 이름을 그대로 복사하세요.
타임아웃과 폴링 정체
동기 호출의 경우 너무 짧은 타임아웃은 성공할 수 있었던 작업을 중단시킵니다. 비동기 작업의 경우 폴링 정체는 보통 폴링 로직이 일찍 종료되었거나 종료 상태 확인이 API가 실제로 반환하는 상태 문자열과 일치하지 않음을 의미합니다—원시 상태 값을 기록하여 확인하세요. 항상 최대 대기 시간을 두어 멈춘 작업이 매달리지 않고 크게 실패하도록 하세요.
빈 결과
200을 반환했지만 이미지가 없는 경우는 거의 항상 버그가 아니라 콘텐츠 문제입니다: 프롬프트가 너무 모호했거나 필터링되었을 수 있습니다. API 오류로 단정하기 전에 응답 본문의 오류 또는 사유 필드를 확인한 다음 프롬프트를 더 명확하고 구체적으로 다듬으세요.
재시도 시 실패
동일한 페이로드가 때때로 성공하고 때때로 실패한다면, 속도 제한에 걸렸거나 일시적인 서버 오류를 만난 것일 가능성이 높습니다. 제출과 폴링 주변에 지수 백오프를 추가하고, 400은 재시도하지 마세요—페이로드를 수정해야 합니다.
의문이 들 때 가장 빠른 진단 방법은 간단한 프롬프트로 최소한의 curl 호출을 실행하는 것입니다. 그것이 작동한다면 문제는 자격 증명이 아니라 페이로드나 코드에 있습니다.