튜토리얼
HiAPI API로 Google 가상 피팅 사용하는 방법: curl과 Python 가이드
이 페이지에서
google-virtual-try-on 모델이 기대하는 것
코드를 작성하기 전에 입력 계약을 이해하는 것이 도움이 됩니다. google-virtual-try-on 모델은 두 장의 이미지를 합성하는 작업입니다. 인물/모델 이미지 한 장과 의류 이미지 한 장을 받아, 인물이 해당 의류를 착용한 이미지를 생성합니다.
즉, 준비 단계는 항상 같은 형태입니다:
- 인물 이미지 한 장. 주체가 선명하게 보이고 프레이밍이 적절해야 합니다. 모델이 신체 기하 구조를 이해해야 하므로 전신 또는 상반신 사진이 가장 좋습니다.
- 의류 이미지 한 장. 인물에게 옮기고 싶은 단일 품목을 깨끗하거나 단색인 배경에 담은 것이 가장 좋습니다.
두 입력 모두 요청 본문에 담긴 원시 바이너리 데이터가 아니라 이미지 URL 형태로 제공됩니다. 이렇게 하면 요청 페이로드가 작게 유지되고, S3, GCS, CDN 같은 자체 스토리지 계층이 계속해서 원본 소스 역할을 할 수 있습니다. 따라서 호출 전에 각 URL이 공개적으로 접근 가능한지, 또는 서명되어 충분히 긴 유효 기간을 가지는지 확인하는 것은 여러분의 몫입니다.
미리 계획해야 할 몇 가지 실질적 제약이 있습니다:
- 해상도와 종횡비는 출력 품질에 영향을 줍니다. 매우 작은 썸네일이나 과도하게 잘린 입력은 대체로 좋지 않은 결과를 낳습니다.
- 한 번의 호출은 의류 한 벌만 처리합니다. 상품 페이지에 여러 색상이 있다면 여러 품목을 한 요청에 밀어 넣으려 하지 말고 여러 번 호출하세요.
- 페어링은 여러분의 책임입니다. 모델은 의류가 해당 인물에게 "어울리는지" 검증하지 않습니다. 그저 제공한 내용을 합성할 뿐입니다. 좋은 페어링(전신 사진과 원피스, 상반신 사진과 재킷)은 눈에 띄게 더 나은 출력을 만듭니다.
이 단계를 자산 계약으로 생각하세요. 각 작업마다 두 개의优质 URL을 안정적으로 생성할 수 있다면, 나머지 통합 작업은 곧바로 이어지는 파이프라인 구축일 뿐입니다.
HiAPI 요청 설정
모든 HiAPI 모델 호출은 같은 형태를 따르므로, 하나가 작동하면 나머지는 매개변수만 바꾸면 됩니다. 다음은 google-virtual-try-on에 필요한 내용입니다.
엔드포인트와 메서드
요청은 google-virtual-try-on의 HiAPI 모델 호출 엔드포인트로 POST 전송됩니다. 모든 모델에서 동일한 기본 URL과 동일한 자격 증명을 사용합니다. 이것이 각 제공업체를 하나씩 연결하는 대신 HiAPI를 통해 라우팅하는 주된 이유입니다.
인증
Authorization 헤더에 HiAPI API key를 사용해 표준 bearer token 형식으로 인증합니다:
Authorization: Bearer $HIAPI_API_KEY
키는 서버 측에 보관하세요. 브라우저 번들 산출물이나 모바일 앱에 절대 배포하지 마세요. 자체 백엔드를 통해 프록시하는 것이 더 안전할 뿐 아니라, 속도 제한과 로깅을 추가할 지점을 제공합니다.
콘텐츠 유형
요청 본문은 JSON으로 보냅니다:
Content-Type: application/json
요청 본문
요청 본문에는 모델 식별자와 이전 섹션의 두 이미지 URL(인물 이미지와 의류 이미지), 그리고 모델이 노출하는 선택적 매개변수가 담깁니다. 정확한 매개변수 이름은 모델 옆 문서에 기록된 것을 따르세요. 추측하지 말고 그대로 복사하세요. 필드 이름의 오타는 보통 유용한 안내가 아니라 검증 오류로 나타나기 때문입니다.
구성 저장
기본 URL, 모델 식별자, 키를 환경 변수에 넣으면 같은 스크립트를 수정 없이 스테이징과 프로덕션에서 사용할 수 있습니다:
export HIAPI_API_KEY="your-key-here"
export HIAPI_BASE_URL="https://api.hiapi.ai"
설정은 이게 전부입니다. SDK도, 제공업체별 연결도 필요 없습니다.
작동하는 curl 요청
키와 페이로드가 올바른지 확인하는 가장 빠른 방법은 단일 curl 호출입니다. 다음은 google-virtual-try-on 요청의 해부도입니다:
curl -X POST "$HIAPI_BASE_URL/v1/models/google-virtual-try-on" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "google-virtual-try-on",
"input": {
"model_image": "https://your-cdn.example.com/person-001.jpg",
"garment_image": "https://your-cdn.example.com/jacket-front.jpg"
}
}'
몇 가지 주의할 점:
- 두 이미지 필드는
input객체 안에 있어, 모델별 매개변수가 네임스페이스로 격리되고 라우팅 필드와 분리됩니다. - URL은 노트북이 아니라 서버에서 접근 가능해야 합니다.
localhost또는 VPN으로만 접근 가능한 주소는 실패합니다. - 이 호출에는 파일 업로드 단계가 없습니다. 자산이 아직 CDN에 없다면 먼저 업로드하고 생성된 URL을 사용하세요.
무엇이든 그 위에 구축하기 전에 한 번 실행하고 반환된 원시 JSON을 확인하세요. 출력을 포매터로 파이프하면 읽기更容易:
curl -s -X POST "$HIAPI_BASE_URL/v1/models/google-virtual-try-on" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json | python -m json.tool
요청 본문을 request.json 파일에 저장하면 페이로드가 커진 후 셸 따옴표 오류를 피할 수 있습니다.
같은 요청을 Python으로 구현
일회성 테스트 이상의 모든 상황에서는 Python으로 넘어가세요. 아래 예제는 표준 라이브러리와 requests만 사용하므로 추가 프레임워크 없이 스크립트, Lambda 또는 소규모 서비스에 바로 넣을 수 있습니다.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai")
def try_on(person_url: str, garment_url: str, timeout: int = 120) -> dict:
payload = {
"model": "google-virtual-try-on",
"input": {
"model_image": person_url,
"garment_image": garment_url,
},
}
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
response = requests.post(
f"{BASE_URL}/v1/models/google-virtual-try-on",
json=payload,
headers=headers,
timeout=timeout,
)
response.raise_for_status()
return response.json()
if __name__ == "__main__":
result = try_on(
"https://your-cdn.example.com/person-001.jpg",
"https://your-cdn.example.com/jacket-front.jpg",
)
print(result)
적용에 관한 참고 사항:
- 명시적 타임아웃을 설정하세요. 이미지 생성은 즉시 완료되지 않습니다.
requests의 기본 타임아웃은 이런 호출에 너무 공격적입니다. p99 지연보다 여유 있게 높은 값을 선택하세요. data=json.dumps(payload)대신json=payload를 사용하세요. 콘텐츠 유형을 대신 설정해 주고 이중 인코딩 버그를 피할 수 있습니다.- 응답 객체가 아니라 파싱된 JSON을 반환하세요. 호출자가 실수로 HTTP 내부 세부 사항에 의존하지 않게 됩니다. 지표에 상태 코드가 필요하다면 반환 전에 캡처하세요.
- 클라이언트와 워크플로를 분리하세요. 실제 서비스에서 위 함수는 경량 클라이언트 모듈에 속하고, 큐, 저장소, 재시도는 그 위 계층에 위치합니다.
이미 httpx나 비동기 프레임워크를 사용 중이라면 전환은 기계적입니다. 페이로드와 헤더가 완전히 동일합니다.
응답 읽기
응답은 JSON입니다. 두 가지에 주목하는 작은 봉투로 생각하세요. 작업이 성공했는지, 출력이 어디에 있는지입니다.
대체로 다음을 확인해야 합니다:
- 전송 상태. 2xx는 요청이 접수되어 처리되었음을 의미합니다. 4xx는 요청에 문제가 있음을, 5xx는 서버에 문제가 생겼음을 의미합니다. 매 호출 시 상태 코드를 기록하세요. 이것이 추가할 수 있는 가장 저렴한 관측 수단입니다.
- 응답 본문 필드. 페이로드에는 생성 결과가 담깁니다. 이미지 결과는 생성된 자산을 가리키는 URL 형태로 반환됩니다. 정확한 필드 이름은 모델의 응답 스키마를 따르세요. 단일 문자열이라고 가정하지 말고 방어적으로 파싱하세요.
- 메타데이터. 응답의 사용량이나 소요 시간 필드는 기록할 가치가 있습니다. 과금은 플랫폼이 계량하므로, 요청별 메타데이터를 영속화하면 나중에 자체 로그와 대시보드를 대조할 수 있습니다.
견고한 파싱은 다음과 같습니다:
data = try_on(person_url, garment_url)
outputs = data.get("output") or {}
image_url = outputs.get("image")
if not image_url:
raise RuntimeError(f"No image in response: {data}")
결과 처리 방법
반환된 URL은 생성된 자산이지 영구 자산이 아닙니다. 프런트엔드에 그대로 넘기고 방치하지 마세요. 대신:
- 다운로드하고 다시 호스팅하세요. 즉시 바이트를 가져와 콘텐츠 주소 지정 방식의 키로 자체 버킷에 기록하세요. 이렇게 하면 제품이 생성자의 보존 정책과 분리됩니다.
- 출처를 기록하세요. 입력 URL, 모델 식별자, 타임스탬프를 출력과 함께 저장하세요. 판매자가 왜 특정 피팅 결과가 그렇게 보이는지 물을 때 정확한 작업을 재현해야 합니다.
- 형식을 정규화하세요. 매 페이지 조회마다 처리하지 말고, 수집 시점에 한 번 크기를 조정하고 상점 프런트엔드의 표준 형식으로 변환하세요.
응답을 일시적 인계(파싱, 다운로드, 저장, 폐기)로 취급하는 것이 확장 가능한 패턴입니다.
실패 모드와 재시도 전략
모든 실패가 재시도할 가치가 있는 것은 아닙니다. 무분별한 재시도는 상류의 작은 hiccup을 중복 작업이 가득한 큐와 놀라운 청구서로 바꿉니다.
재시도 전에 분류하세요
재시도하지 말고 요청을 수정하세요:
400계열 검증 오류: 잘못된 JSON 형식, 누락되거나 이름이 틀린 필드, 모델이 기대하는 구조와 맞지 않는 요청 본문.401/403: API key가 잘못되었거나 누락되었거나, key에 해당 모델 접근 권한이 없음. 재시도는 결코 도움이 되지 않습니다.404: 모델 식별자 또는 엔드포인트 경로가 잘못됨.- 접근 불가능한 이미지 URL. 인물 또는 의류 URL이 가져오기 시 404를 반환하거나 타임아웃되면 생성은 계속될 수 없습니다. 제출 전에 URL을 검증하세요.
백오프와 함께 재시도:
429: 속도 제한에 걸렸습니다. 백오프하고 그 신호를 존중하세요.5xx: 일시적 서비스 또는 상류 오류.- 네트워크 수준 장애: 연결 재설정, 읽기 타임아웃.
지터를 적용한 제한된 재시도
시도 횟수를 제한하고(보통 3회가 일반적 상한) 무작위 지터를 적용한 지수 백오프를 사용해 다수의 워커가 동시에 재시도하지 않도록 하세요:
import random, time
def with_retry(fn, attempts=3, base=1.0):
for i in range(attempts):
try:
return fn()
except requests.HTTPError as e:
status = e.response.status_code if e.response is not None else None
if status is not None and 400 <= status < 500 and status != 429:
raise # client error: do not retry
if i == attempts - 1:
raise
time.sleep(base * (2 ** i) + random.uniform(0, 0.5))
프로덕션 보호 조치
- 작업 수준 멱등성. 입력 URL 쌍을 해시해 작업 키로 사용하세요. 같은 키가 이미 실행 중이거나 완료되었다면 다시 제출하지 말고 저장된 결과를 반환하세요.
- 데드 레터 큐. 재시도가 소진되면 작업과 전체 컨텍스트를 조용히 버리지 말고 보관하세요.
- 회로 차단기. 오류율이 임계값을 넘으면 문제를 겪는 서비스를 계속 두드리지 말고 쿨다운 기간 동안 제출을 중단하세요.
- 단순 개수가 아니라 형태로 경보하세요. 배포 직후 4xx가 급증하면 보통 누군가 필드 이름을 바꿨다는 뜻입니다.
입력을 조기에 검증하세요
대부분의 "모델 장애"는 실제로는 잘못된 입력입니다. 저렴한 사전 검사를 하세요. 각 URL에 HEAD 요청을 보내 콘텐츠 유형과 대략적인 크기를 확인하고, 과금되는 호출을 하기 전에 명백히 사용 불가능한 자산을 거부하세요. 이 습관 하나가 재시도 트래픽의 대부분을 없애 줍니다.
실제 파이프라인에 통합하기
성공적인 curl 호출은 데모일 뿐입니다. 신뢰할 수 있는 제품 기능은 그 주위에 약간의 구조가 필요합니다.
흐름을 단계로 구조화하세요
실행 가능한 분해는 다음과 같습니다:
- 수집. 판매자나 내부 사용자가 인물 이미지와 의류 이미지를 제출합니다. 둘 다 객체 스토리지에 저장하고 안정적이고 서명된 URL을 생성하세요.
- 검증. 접근성, 형식, 크기를 확인하세요. 명확한 메시지와 함께 조기에 거부하세요.
- 제출. 클라이언트 모듈을 통해
google-virtual-try-on을 호출하세요. 데이터베이스에 작업 키, 모델 식별자, 입력 URL을 기록하세요. - 구체화. 성공하면 생성된 이미지를 다운로드하고, 표준 형식으로 변환하고, 결정적 키로 CDN에 기록하세요.
- 게시. 작업 기록이 자체 호스팅 자산을 가리키도록 업데이트하고, 상점 프런트엔드는 자체 스토리지에서만 읽도록 하세요.
각 단계는 독립적으로 재시도할 수 있으며, 이것이 전체 시스템을 디버깅 가능하게 만드는 이유입니다. 4단계가 실패하면 생성 작업을 다시 실행할 필요가 없습니다.
클라이언트를 가볍게 유지하세요
HTTP 호출은 작은 모듈에 두고, 정책(재시도, 동시성, 타임아웃, 로깅)은 그 주위에 배치하세요. HiAPI가 모델에 매개변수를 추가하거나, 서로 다른 이미지 생성 경로를 A/B 테스트하고 싶을 때 파일 하나만 수정하면 됩니다.
도입할 가치가 있는 운영 습관
- 기본은 비동기. 생성은 몇 초, 때로는 더 오래 걸립니다. 사용자가 기다리는 요청 핸들러가 아니라 워커에서 제출하세요.
- 적극적으로 캐시하세요. 같은 인물과 의류 쌍은 절대 두 번 생성되어서는 안 됩니다. 출력을 콘텐츠 주소로 지정하고 제출 전에 확인하세요.
- 가시성을 갖고 예산을 관리하세요. 사용량은 플랫폼이 계량하므로 요청별 메타데이터를 기록하고 정기적으로 HiAPI 대시보드와 대조하세요. 폭주하는 재시도 루프를 월말이 아니라 몇 시간 안에 발견하세요.
- 프롬프트와 매개변수를 버전 관리하세요. 매개변수 객체를 각 작업과 함께 저장해 변경 후에도 결과를 재현할 수 있게 하세요.
- 사용자에게 보이게 실패하세요. 영원히 사라지지 않는 로딩 애니메이션은 "이 이미지는 생성할 수 없습니다. 다른 사진으로 시도해 보세요"라는 정직한 메시지보다 나쁩니다.
다음 단계
같은 요청 형태가 다른 HiAPI 이미지 모델에도 적용되므로, 여기서 구축한 클라이언트는 파이프라인 나머지 부분의 템플릿이 될 것입니다. 두 이미지 호출이 안정되면 모델 카탈로그를 둘러보며 워크플로에 맞는 다른 모델이 있는지 확인하세요. 인증, 오류 처리, 스토리지 패턴은 그대로 이어집니다.