가상 착용(Virtual Try-On) 영상 API: 사람에게 옷 입히기

Sume API로 가상 착용 영상을 만들려면 카탈로그 Format 두 개 중 하나인 sume-virtual-try-on이나 sume-virtual-fitting을 POST /v1/formats/sume/{slug}/runs로 호출하면서, 사람과 옷의 사진을 attachments에 넣으세요. 단계마다 직접 승인하고 싶다면 POST /v1/images로 착용 스틸을 만든 뒤 POST /v1/videos로 움직임을 입히세요.

Format에 관한 내용은 Format 카탈로그 (영문), Format 호출하기 (영문), Format API (영문) 문서 페이지와 각 Format의 공개 설명에서, 단계별 경로는 Image API (영문)와 영상 생성 (영문) 페이지에서 가져왔습니다. 모두 2026-09-27에 확인했습니다.

어떤 가상 착용 Format을 호출해야 하나요?

GET /v1/formats/sume/{slug}는 호출하기 전에 어느 쪽 Format이든 description을 돌려줍니다. 두 설명 모두 “Not for: static campaign deliverables”(정적인 캠페인 결과물용 아님)로 끝나므로, 둘 다 영상을 만듭니다. 광고나 의상 전환에는 sume-virtual-try-on이, 상품 페이지용 핏 미리보기에는 sume-virtual-fitting이 맞습니다. “Accurate garment fit”(정확한 옷 핏)은 그 Format이 밝힌 목표일 뿐 보장이 아니므로, 게시하기 전에 모든 영상을 검토하세요.

사람과 옷은 어떻게 보내나요?

서비스 계정 키를 제외하면 formats:write가 있는 API 키는 모두 카탈로그 Format을 호출할 수 있습니다. 실행과 그 미디어, 지출은 호출한 키에 귀속되며, 먼저 fork하거나 설치할 것은 없습니다. 브리프는 instruction에 넣으세요. instruction은 8,000자까지 받고, 실행에는 앞부분 약 4,000자가 전달되며, Format의 레시피 뒤에 조합되므로 둘이 어긋나면 instruction이 우선합니다.

각 사진은 공개 HTTPS image_url을 담은 input_image로 attachments에 넣으세요. filename은 에이전트가 보는 라벨이므로, 어느 사진이 사람이고 어느 사진이 옷인지 알려 주는 데 쓰세요. 영상에 나오는 데 동의한 사람의 사진을 쓰세요.

curl -sS -X POST "https://api.sume.com/v1/formats/sume/sume-virtual-try-on/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: look-042-jacket-tryon-v1" \
  -d '{
    "instruction": "Show the person in person.jpg wearing the jacket in jacket.png.",
    "attachments": [
      { "type": "input_image", "image_url": "https://example.com/person.jpg", "filename": "person.jpg" },
      { "type": "input_image", "image_url": "https://example.com/jacket.png", "filename": "jacket.png" }
    ],
    "generation_spend_cap_usd": 20
  }'

사진에는 어떤 제한이 있나요?

Sume는 실행을 만들 때 모든 첨부 파일을 가져와 검사하므로, 깨졌거나 비공개인 이미지는 실행이 아니라 생성 요청 단계에서 실패합니다.

• 형식은 JPEG, PNG, WebP, GIF, AVIF 중 하나입니다. 현재 첨부 유형은 input_image 하나뿐입니다.
• 실행당 이미지 30장, 500 MB까지이고, 이미지 한 장은 30 MB까지입니다. 크기 상한을 넘으면 413 attachment_too_large입니다.
• Sume가 가져올 수 없는 이미지는 502 attachment_fetch_failed가 되며, details.index가 어느 이미지인지 알려 줍니다.
• 같은 Idempotency-Key와 본문을 다시 보내면 원래 실행이 돌아오며, 두 번 과금되지 않습니다.

가상 착용을 한 단계씩 직접 만들려면 어떻게 하나요?

움직임에 비용을 쓰기 전에 룩을 먼저 승인하고 싶다면 작업을 Job 두 개로 나누세요. 모델별 프레임 지원은 Image-to-Video API에, 스틸에 쓸 모델별 레퍼런스 한도는 레퍼런스 이미지 기반 이미지 생성 API에 있습니다.

• 스틸을 만드세요. 사람과 옷을 공개 HTTPS URL로 input_references에 담아 POST /v1/images를 보냅니다. input_references 디스크립터가 {"min": 0, "max": 0}인 모델은 텍스트로 이미지 생성만 지원하며 레퍼런스를 거부하고, ChatGPT Image 2.5(openai/gpt-image-2.5)는 최대 16장까지 받습니다. 이미지로 이미지를 만드는 호출에서는 레퍼런스에 맞추도록 aspect_ratio: "auto"를 쓰는 편이 좋습니다.
• 승인한 스틸은 직접 관리하는 공개 HTTPS URL에 올려 두세요. Image API는 data[].url을 Sume가 호스팅하는 서명된 URL로 반환하며, 이 URL을 영상 요청에 바로 넘기는 방법은 영상 생성 문서에 나와 있지 않습니다.
• 스틸에 움직임을 입히세요. 스틸을 frame_type이 first_frame인 frame_images 항목으로 넣어 POST /v1/videos를 보냅니다. 요청에 input_references도 있으면 frame_images가 우선하고, 요청은 이미지로 영상 만들기로 실행됩니다. 레퍼런스만 보내는 방법은 Reference-to-Video API에서 다룹니다.

무엇이 돌아오고, 비용은 얼마인가요?

Format 실행은 영수증과 함께 202로 응답하고, 실행 자체는 몇 분이 걸립니다. 실행을 폴링하거나, communication.webhook_url을 설정해 서명된 format.run.terminal POST를 한 번 받으세요. 완료된 실행에는 화면에 보여 줄 결과 하나인 primary_output_url과 artifacts[]가 채워집니다. 이 media.sume.com URL은 만료되지 않고 URL을 가진 누구에게나 공개되므로, 고객마다 비공개로 접근해야 한다면 프록시하거나 복사해 두세요.

실행 안의 생성은 API 요금의 요율로 계량되며 generation_spend_cap_usd의 제한을 받습니다. 상한은 최대 $500이고, null이면 $500으로 실행되며, 0은 거부됩니다. 에이전트 자체의 LLM 턴까지 포함한 실행 비용은 usage.debited_usd_micros입니다. 단계별 경로에서는 실패한 이미지는 과금되지 않으며, 영상 Job은 공급사 정가 × 1.25로 예약되고 기본 5.5% 에이전트 수수료가 더해집니다.

API 실행이 하지 않는 일은 무엇인가요?

Format 경로에는 다음 세 가지 경계가 있습니다.

• 승인 대기 없음. 승인은 이미 부여된 것으로 처리되며, 끝낼 수 없는 실행은 반쯤 끝난 completed가 아니라 failed로 돌아옵니다.
• 모델 선택 없음. 실행의 model 필드는 오케스트레이션을 맡는 LLM만 고르며, 이미지·영상·오디오 모델은 Format의 도구가 고릅니다.
• 레시피 수정 없음. 카탈로그 Format을 바꾸려면 Format 라이브러리에서 fork한 뒤 {your_handle}/{slug}로 사본을 호출하세요.