Google Virtual Try-On API 연동: 인물 이미지와 의류 이미지

두 이미지를 각각 올바른 필드에 넣으면 연동이 명확한 출발점을 갖게 됩니다. 인물 사진은 person_image_url에, 의류 이미지는 product_image_url에 넣습니다. 인물 사진을 의류 필드에 넣으면 작업의 입력 의미가 달라집니다.

TL;DR

Google Virtual Try-On은 장당 $0.1075입니다. 가격과 예산 확인. HiAPI /v1/tasks 인터페이스를 사용합니다. 작업을 제출해 taskId를 받고, 결과를 조회합니다. 프롬프트가 필요 없습니다.

입력 준비와 필드

한 사람이 정면을 바라보는 사진을 고르고 신체 윤곽이 최대한 명확하게 보이도록 합니다. 의류는 배경이 깔끔하고 가장자리가 온전한 평면 배치 이미지나 걸이 이미지를 사용합니다. 아래 예시의 두 영구 이미지 주소는 각각 인물 A와 빨간색과 흰색 줄무늬 티셔츠에 해당하며, 자신의 공개 이미지 주소로 바꿀 수 있습니다.

필드	입력 방식
person_image_url	필수; 인물 사진의 공개 HTTP(S) URL
product_image_url	필수; 의류 상품 이미지의 공개 HTTP(S) URL
num_images	정수; 명시적으로 1을 입력하며 현재 한 장만 지원

업무 조합을 요청에 매핑하기

같은 인물에게 다양한 의류를 입혀 볼 때는 person_image_url을 고정하고 product_image_url을 하나씩 교체합니다. 같은 의류를 다양한 인물에게 보여 줄 때는 상품 이미지를 고정하고 인물 이미지를 교체합니다. 같은 입력 조합으로 여러 후보를 만들 때는 두 입력을 유지한 채 각각 제출하고, 매번 여전히 num_images: 1을 입력합니다. 자체 작업 기록에 상품 번호와 인물 이미지 버전을 저장하는 것이 좋으며, 결과 파일명만으로 대응 관계를 추측해서는 안 됩니다.

인물과 의류 모두 공개적으로 읽을 수 있는 HTTP(S) 이미지 주소를 제공해야 하며, 로컬 디스크 경로나 data URI를 이미지 URL로 사용하는 것은 지원되지 않습니다. 브라우저에 로그인한 상태에서 이미지가 보인다고 해서 다른 서비스가 읽을 수 있는 것은 아닙니다. 제출 전에 로그인 세션에 의존하지 않는 조건에서 링크를 확인해야 합니다. 반환되는 것이 앨범 페이지나 권한 안내 페이지가 아니라 이미지 자체인지 확인하고, 작업이 이미지를 읽는 동안 접근 가능한 상태로 유지되도록 합니다.

인물 사진이 옷자락을 가리거나 손과 옷이 크게 겹친다면 먼저 경계가 더 명확한 사진으로 바꾸는 것을 고려합니다. 의류 이미지는 단일 품목이면서 가장자리가 온전한 평면 또는 걸이 촬영 이미지를 우선하고, 인물 착용 결과를 다시 독립 상품 이미지로 잘못 사용하지 않도록 합니다. 공개 필드에는 국소 보호, 소매 조정, 신발 고정 설정이 제공되지 않으므로 사용자 정의 필드를 추가해 이런 요구를 표현할 수 없습니다.

명확한 이미지를 고르는 것은 작업 방법이며, 인터페이스가 이미지를 받아들이는지와 상품 표현이 정확한지는 따로 확인해야 합니다. 이 글은 Try-On에 근거 없는 파일 크기, 픽셀 상한 또는 출력 크기 약속을 추가하지 않으며, 다른 이미지 모델의 입력 제한을 그대로 적용할 수도 없습니다.

작업 제출: cURL

아래는 Bash/cURL 예시입니다. 먼저 실행 환경에 HIAPI_API_KEY를 설정합니다. 요청의 이미지 URL은 교체할 수 있으며, 키는 서버 환경에 보관합니다.

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "google-virtual-try-on",
  "input": {
    "person_image_url": "https://static.hiapi.ai/gallery/2026/10/9f656c8b6ecf94d5.webp",
    "product_image_url": "https://static.hiapi.ai/model-covers/2026/10/22/1792660602486-b5b70d2cfdd8dc95-1792152569828-b5b70d2cfdd8dc95-t-g1-0.webp",
    "num_images": 1
  }
}'

제출에 성공하면 data.taskId가 반환됩니다. 이후 조회에 사용할 수 있도록 이 값을 저장합니다.

작업 조회와 결과 저장

작업 번호를 TASK_ID에 넣고 조회합니다:

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

작업의 data.status=success일 때 data.output[0].url에서 이미지를 가져와 저장합니다. 지속적으로 운영되는 업무에서는 제출 요청의 최상위에 callback.url과 callback.when: "final"을 설정해 종료 알림을 받고, taskId 기준으로 중복을 제거할 수 있습니다. 성공과 실패 모두 알림이 발생할 수 있습니다. 조회 방식은 디버깅과 사후 확인에 적합합니다.

폴링, 콜백, 타임아웃 처리

제출과 조회는 별개의 작업입니다. data.taskId를 받은 후 이 값과 이번 입력을 함께 기록하고, GET /v1/tasks/:id로 조회합니다. 종료 상태에 도달하지 않았다면 계속 기다리며, 조회 동작을 다시 POST로 바꾸지 않습니다. 폴링 간격과 업무 대기 상한은 애플리케이션에서 정하며, 이 글은 약속할 근거가 되는 평균 소요 시간이나 고정 완료 기한을 제시하지 않습니다. 예시의 네트워크 타임아웃도 서비스 소요 시간 보장을 의미하지 않습니다.

조회 요청이 타임아웃되면 이번 읽기가 제때 완료되지 않았다는 것만 의미합니다. 작업 번호를 보관하고 나중에 같은 작업을 다시 조회합니다. 제출 요청 자체가 타임아웃되어 번호를 받지 못했다면 서버가 이미 접수했는지 불확실합니다. 제출 시각과 요청 내용을 보관하고 먼저 작업 기록을 확인한 후 재제출 여부를 결정합니다. 클라이언트의 예외를 곧바로 작업 실패로 해석하지 말고, 중복 요청이 자동으로 병합된다고 약속하지도 않습니다.

콜백 설정은 요청 본문 최상위에 두며 model, input과 같은 레벨입니다. 모델 입력 안에 넣을 수 없습니다. callback.url을 설정할 때 callback.when: "final"도 함께 사용합니다. 종료 알림은 성공에 대응할 수도 있고 실패에 대응할 수도 있으므로 알림을 받은 후에도 상태를 확인해야 합니다. 조회와 콜백이 같은 작업을 처리할 수 있으므로 업무 측에서 taskId 기준으로 중복을 제거해 반복 다운로드나 후속 작업의 중복 실행을 피합니다. 여기서 설명하는 것은 애플리케이션 처리 방법이며, 콜백이 반드시 특정 시간 안에 도착한다고 가정하지 않습니다.

data.status=success 이후 data.output에 실제로 읽을 수 있는 결과 주소가 있는지 확인한 다음 이미지를 다운로드합니다. fail이 반환되면 오류 정보를 저장하고 내용에 따라 요청을 수정합니다. 상태 하나만 보고 이미지가 너무 크다거나 네트워크 장애라거나 다른 구체적 원인을 추측하지 않습니다. 예상치 못한 상태이거나 출력이 없으면 응답을 보관하고 추가 조회하며, 빈 결과를 성공적인 전달로 취급하지 않습니다.

다운로드 실패와 생성 실패도 구분해야 합니다. 작업은 성공했는데 파일이 제대로 저장되지 않았다면 먼저 기존 결과를 다시 읽거나 다운로드하여 이미지를 곧바로 다시 만들지 않도록 합니다. 보관 시 작업 번호, 입력 대응 관계, 최종 파일 위치를 남겨야 이후에 특정 이미지가 어느 요청에서 왔는지 정확히 찾을 수 있습니다. 사용자에게 표시하는 "대기 시간 초과"는 현재 화면이 대기를 멈췄다는 의미여야 하며, 서버 작업이 취소되었다고 임의로 선언해서는 안 됩니다.

Python 제출 예시

환경에 requests가 설치되어 있어야 합니다. 여기서 timeout=60은 클라이언트 네트워크 요청 대기 상한이며 이미지 생성 소요 시간이 아닙니다.

import os
import requests

payload = {'model': 'google-virtual-try-on', 'input': {'person_image_url': 'https://static.hiapi.ai/gallery/2026/10/9f656c8b6ecf94d5.webp', 'product_image_url': 'https://static.hiapi.ai/model-covers/2026/10/22/1792660602486-b5b70d2cfdd8dc95-1792152569828-b5b70d2cfdd8dc95-t-g1-0.webp', 'num_images': 1}}
response = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json=payload,
    timeout=60,
)
response.raise_for_status()
result = response.json()
task_id = result["data"]["taskId"]
print(task_id)

제출 전과 결과 확인

인터페이스에는 prompt가 필요하지 않습니다. num_images에 2나 4를 입력하지 말고, 후보 이미지가 필요하면 각각 요청을 보냅니다. 먼저 두 이미지가 공개적으로 읽을 수 있는지, 필드가 뒤바뀌지 않았는지 확인한 후 제출합니다. 실패 상태를 받으면 반환 정보를 읽고 입력을 수정하며, 그대로 반복 제출하지 않습니다.

상품 용도에 따라 반환 이미지 검수하기

먼저 결과를 인물 이미지와 나란히 보고 얼굴, 헤어스타일, 자세, 배경, 그리고 바뀌면 안 되는 바지와 신발을 확인합니다. 그다음 의류 이미지와 대조해 색상, 칼라 모양, 소매 길이, 패턴, 밑단을 확인합니다. 줄무늬 티셔츠는 가슴과 소매 부분에서 가로 줄무늬가 이어지는지, 원피스는 스트랩, 드레이프 넥라인, 손 주변의 주름을, 셔츠는 소매가 말렸는지 밑단이 바지 허리 안으로 들어갔는지 봅니다. 이러한 확인은 사례에서 볼 수 있는 변화에 근거한 것이며 다른 입력에서도 이 변화만 나타난다고 보장하지 않습니다.

"파일이 다운로드됨"과 "이미지를 상품 페이지에 사용할 수 있음"은 따로 기록해야 합니다. 결과가 성공적으로 반환된 후에도 옷 이외의 변화가 나타날 수 있으며, 인터페이스 상태가 자동으로 사람의 검수를 대신할 수 없습니다. 결함이 입력 가림에서 비롯되었다면 먼저 입력을 바꾼 후 다시 시도합니다. 상품이 특정 소매 길이나 고정 액세서리를 반드시 보여 줘야 한다면 현재 결과가 그 제약을 충족하는지 먼저 판단하며, 전체 착장이 자연스럽다는 이유로 상품 세부 사항을 무시해서는 안 됩니다.

같은 입력 조합에 후보를 추가할 때는 이전 결과를 비교용으로 보관하고 새 파일로 덮어쓰지 않습니다. 선택할 때 수용 또는 거부 이유를 적어 두면 이후 유사 상품 처리에 도움이 됩니다. 이미지는 외관 관찰에만 사용하며, 실제 치수와 착용감은 의류 치수 및 실제 착용 정보가 추가로 필요합니다.

자주 묻는 질문

인물 사진과 의류 이미지가 하나의 필드를 공유할 수 있나요?

아니요. 인물 사진은 person_image_url, 의류 이미지는 product_image_url을 사용합니다.

prompt 파라미터를 추가해야 하나요?

아니요. 인터페이스에 프롬프트 필드가 없으며, 가상 착용은 두 입력 이미지로 결정됩니다.

왜 num_images: 1을 명시적으로 입력하나요?

현재 한 장의 결과만 지원합니다. 명시적으로 입력하면 요청 장수와 장당 $0.1075의 예산이 직접 대응됩니다.

taskId를 받으면 바로 이미지를 읽을 수 있나요?

작업을 조회하거나 알림을 받아야 합니다. 작업의 data.status=success 이후 data.output[0].url에서 이미지를 가져옵니다.

계속 읽기

가격과 예산 · API 연동 · 사례와 이미지 선택 · Google Virtual Try-On

가상 착용 또는 범용 이미지 편집 방식을 선택해야 할 때는 Google Virtual Try-On과 Seedream 5.0 Lite 비교를 참고해 옷, 신발, 인물 외관을 항목별로 확인하십시오.