FASHN Try-On v1.6 API: 사용 가능한 curl 및 Python 요청 예제

FASHN Try-On v1.6은 hiapi의 가상 착장(image-to-image) 모델입니다. 인물 사진과 의류 사진 두 장을 주면, 합성된 착장 결과 이미지를 반환합니다. 이 글은 개발자를 위한 fashn try-on api 실전 가이드입니다: 제가 완전히 실행에 성공한 실제 /v1/tasks 요청, 온라인 파라미터 검증기로 대조 확인한 전체 입력 schema, 그리고 파라미터 표에 적혀 있지 않은 프로덕션 환경 세부 사항을 담았습니다.

모델 페이지 및 온라인 체험: FASHN Try-On v1.6.

1. 무엇을 만들게 되는지 + 사전 준비물

전체 흐름은 표준 비동기 태스크 패턴입니다: POST로 태스크를 한 번 생성하고, 태스크가 종료 상태에 도달할 때까지 폴링한 다음, 출력 이미지를 다운로드합니다.

필요한 것:

• API key(sk-...) — hiapi 빠른 시작에서 발급받을 수 있습니다.
• 공개 접근 가능한 이미지 URL 두 개: model_image용 인물 사진과 garment_image용 의류 사진.

2. 최소 실행 예제

태스크 생성 (curl)

curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fashn-tryon-v1.6",
    "input": {
      "model_image": "https://cdn.example.com/person.jpg",
      "garment_image": "https://cdn.example.com/shirt.png"
    }
  }'

응답 — 완성된 이미지가 아니라 접수된 태스크입니다:

{"code":200,"data":{"taskId":"tk-hiapi-01M5D3JTGD12PFF3SFM9JRNPAZ"},"message":"success"}

model_image와 garment_image만 필수 필드이며, 나머지 필드는 모두 기본값이 있습니다.

결과 폴링 (curl)

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01M5D3JTGD12PFF3SFM9JRNPAZ \
  -H "Authorization: Bearer sk-YOUR_KEY"

태스크가 완료되면 data.status: "success"를 받게 되고, 이미지는 data.output[0].url에 있습니다:

{
  "code": 200,
  "data": {
    "status": "success",
    "model": "fashn-tryon-v1.6",
    "storage": "temp",
    "output": [
      { "type": "image", "url": "https://temp.hiapi.ai/.../...-0.png", "expireAt": 1793119887 }
    ]
  },
  "message": "success"
}

여기서 expireAt이 중요합니다: 출력은 임시 저장소에 보관됩니다(TTL 약 7일). 이 바이트 데이터를 즉시 다운로드하거나 다른 곳으로 옮겨 저장하세요 — 직접 핫링크하지 마세요.

Python으로 엔드투엔드 실행

import time, requests

API = "https://api.hiapi.ai"
KEY = "sk-YOUR_KEY"
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

def try_on(model_image, garment_image, **opts):
    payload = {
        "model": "fashn-tryon-v1.6",
        "input": {"model_image": model_image, "garment_image": garment_image, **opts},
    }
    r = requests.post(f"{API}/v1/tasks", json=payload, headers=HEADERS, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    while True:                     # poll until terminal
        time.sleep(3)
        d = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        if d.get("status") == "success":
            return d["output"][0]["url"]
        if d.get("status") in ("fail", "error"):
            raise RuntimeError(f"task failed: {d}")

url = try_on(
    "https://cdn.example.com/person.jpg",
    "https://cdn.example.com/shirt.png",
    category="tops", mode="quality",
)
print(url)

3. 입력 schema (온라인 검증기로 대조 검증 완료)

fashn-tryon-v1.6은 닫힌 schema를 사용합니다 — 아래에 나열되지 않은 필드는 모두 거부되므로, hiapi가 노출하지 않는 FASHN 네이티브 추가 파라미터를 끼워 넣을 수 없습니다.

필드	필수 여부	타입	허용 값
model_image	예	string (URL)	인물 사진
garment_image	예	string (URL)	의류 사진
category	아니오	enum	tops, bottoms, one-pieces, auto
mode	아니오	enum	performance, balanced, quality
garment_photo_type	아니오	enum	auto, model, flat-lay
output_format	아니오	enum	png, jpeg
seed	아니오	integer	재현성 용도
segmentation_free	아니오	boolean	—

이를 어떻게 확인했는지: {"model":"fashn-tryon-v1.6","input":{}}를 보내면

invalid input: model_image: missing required field "model_image"; garment_image: missing required field "garment_image"

가 반환됩니다. 위의 모든 열거형 값은 유효하지 않은 값을 보내 확인했습니다. 예를 들어 mode: value must be one of 'performance', 'balanced', 'quality'처럼 반환됩니다. num_samples, num_images 또는 표 밖의 어떤 필드를 전달하면 additional properties '...' not allowed가 반환됩니다 — 다중 샘플 옵션은 없습니다. 한 번의 요청으로 이미지 한 장을 반환하며, 다른 결과를 원하면 여러 번 호출하면서 seed를 바꾸면 됩니다.

4. 프로덕션 환경 실무

• 검증은 과금보다 먼저 일어납니다. 잘못된 입력은 HTTP 400과 함께 {"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: ..."} 응답 본문을 반환하고, 태스크가 생성되지 않습니다 — 형식이 잘못된 요청은 비용이 발생하지 않습니다. 유효한 요청은 code:200과 taskId를 반환합니다.
• 재제출하지 말고 재폴링하세요. POST /v1/tasks를 호출할 때마다 새 태스크(과금 대상)가 생성됩니다. 폴링 요청이 타임아웃되면 이미 가지고 있는 taskId로 계속 폴링하세요. 응답을 놓쳤다고 해서 태스크가 실패한 것은 아닙니다.
• 폴링 대신 콜백을 사용하세요. 배치 시나리오에서는 콜백을 등록해 태스크가 최종 상태에 도달하면 hiapi가 알려주도록 할 수 있어, 직접 폴링할 필요가 없습니다 — 구체적인 필드는 통합 비동기 API 참고 문서를 참조하세요. 위 예제는 폴링을 사용합니다.

5. 실제 한 번 실행했을 때의 상황

위의 최소 요청을 실행했습니다 — 768×1152 인물 사진과 768×1152 의류 이미지를 사용하고 mode와 category는 생략했습니다:

• 지연 시간: 태스크 객체 기준 created부터 completed까지 약 13초.
• 출력: 단일 PNG, 크기 768×1152, 즉 세로형 이미지입니다. 모델 페이지에는 출력 크기가 인물 사진을 따른다고 설명되어 있으며(검증된 실행에서 972×1296과 768×1152 두 크기가 측정됨), 이번 실행도 이와 일치합니다 — width/height/aspect_ratio 필드가 없으므로 인물 사진의 크기가 출력 크기를 결정합니다.
• 상태 경로: 폴링 중 처음에는 archiving으로 표시되다가 이후 success로 바뀌었고, storage는 temp였습니다.
• 기본값이 실제로 유효합니다. mode와 category를 생략해도 성공했으므로, 이 두 이미지 URL이 정말로 유일하게 제공해야 하는 입력입니다 — 모델이 의류 유형을 자동으로 인식합니다.

과금은 출력 이미지 수를 기준으로 계산되며, 선택한 mode에 따라 달라지지 않습니다. 현재 요금은 가격 페이지에서 확인하세요.

관련 링크

• FASHN Try-On v1.6 모델 페이지 및 온라인 체험
• 통합 비동기(태스크) API 참고 문서
• 빠른 시작 — API key 발급
• 가격

자주 묻는 질문

어떤 필드가 필수인가요? model_image와 garment_image뿐이며, 둘 다 공개 접근 가능한 URL이어야 합니다.

한 번의 호출로 여러 변형을 생성할 수 있나요? 아니요 — num_samples와 num_images는 schema에서 거부됩니다. 한 번의 요청은 이미지 한 장을 반환하며, 여러 번 호출하면서 seed를 바꿔 다른 결과를 얻으세요.

출력 크기를 어떻게 제어하나요? 직접 설정할 수 없습니다. 결과는 인물 사진의 크기를 따릅니다 — 입력한 768×1152가 768×1152 출력을 생성했습니다.

결과 URL의 유효 기간은 얼마나 되나요? 출력은 expireAt(약 7일)이 있는 임시 저장소에 있습니다. 이 바이트 데이터를 즉시 다운로드하세요.

품질 모드가 가격을 바꾸나요? 아니요 — performance, balanced, quality 어느 것이든 출력 이미지 수를 기준으로 과금됩니다.