제품 사진 영상 변환 API: SKU 사진으로 만드는 이커머스 클립

Sume API로 제품 사진을 영상으로 만들려면, 이커머스 히어로 클립용 sume-product-commercial처럼 제품에 맞는 카탈로그 Format을 POST /v1/formats/sume/{slug}/runs로 호출하면서 사진을 attachments에 넣으세요. 모션을 직접 작성하려면 사진을 POST /v1/videos 요청의 first_frame으로 보내세요.

아래 내용은 Format 카탈로그 (영문), Format API (영문), Format 호출하기 (영문), 영상 생성 (영문), Video Router (영문) 문서 페이지와 각 Format의 공개 설명에서 가져왔으며, 2026-09-27에 확인했습니다. 카탈로그 자체는 바로 쓰는 제품 영상 Format에서 소개합니다.

어떤 제품에 어떤 Format이 맞나요?

아래 카탈로그 영상 Format 다섯 개는 설명에 제품이나 이커머스 작업을 명시하며, 각 설명은 “Not for: static campaign deliverables”(정적인 캠페인 결과물용 아님)로 끝납니다. GET /v1/formats/sume/{slug}는 호출하기 전에 Format의 전체 설명을 돌려줍니다. sume-virtual-fitting은 옷을 “on a supplied person”(제공한 인물에게 입힌 모습으로) 보여 주므로 사람 사진도 함께 첨부하세요. 이 워크플로는 가상 착용 영상 API에서 다룹니다.

사진과 제품 정보는 어떻게 보내나요?

formats:write가 있는 키로 Format을 호출하세요. 브리프는 instruction에, 각 제품 사진은 공개 HTTPS image_url을 담은 input_image로 attachments에 넣으며, 실행당 30장까지입니다. Sume는 실행을 만들 때 각 이미지(JPEG, PNG, WebP, GIF, AVIF, 최대 30 MB)를 가져오므로, 비공개이거나 깨진 이미지는 실행이 아니라 생성 요청 단계에서 실패합니다.

제품 정보는 input에 넣으세요. input은 최상위 키 최대 64개, 최대 2 MiB의 자유 형식 JSON 객체입니다. Sume는 input에 들어갈 필드 목록을 공개하지 않으며, Format은 자신이 아는 키만 읽습니다. input 안 어디에 있든 미디어 URL은 attachments와 예산 하나를 함께 씁니다. 실행당 파일 30개까지이고 그중 영상은 10개, 오디오 파일은 10개까지이지만, 상품 페이지 URL은 이 예산에 포함되지 않습니다.

curl -sS -X POST "https://api.sume.com/v1/formats/sume/sume-product-usage-demo/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sku-1042-usage-demo-v1" \
  -d '{
    "instruction": "Show the attached hand cream being applied.",
    "input": { "product_url": "https://shop.example.com/p/1042" },
    "attachments": [
      { "type": "input_image", "image_url": "https://example.com/sku-1042-front.jpg" },
      { "type": "input_image", "image_url": "https://example.com/sku-1042-back.jpg" }
    ],
    "generation_spend_cap_usd": 20
  }'

SKU 카탈로그 전체는 어떻게 실행하나요?

SKU마다 실행과 Idempotency-Key를 따로 두세요. 키는 SKU와, 일부러 다시 실행하고 싶을 때 올리는 버전으로 만듭니다. 문서는 요청마다 uuidgen을 쓰면 “makes the header decorative”(헤더가 장식이 될 뿐)이라고 경고합니다. 또 키는 Format 하나에 한정되므로, 같은 키를 두 Format에 보내면 실행이 두 개 시작됩니다.

한 번에 많이 큐에 넣으려면 POST /v1/formats/{handle}/{slug}/bulk-runs를 쓰세요. 항목을 1–100개 받고 각 항목은 일반 실행 본문과 같으며, 그중 concurrency(1–16)개를 동시에 진행합니다. 큐 요청은 자체 Idempotency-Key를 받으므로, 배치마다 새 키를 만드세요. 큐의 동작 방식은 Sume Format 대량 실행에서 다룹니다.

제품 사진을 직접 영상으로 만들려면 어떻게 하나요?

공개 HTTPS URL에 있는 사진을 frame_type이 first_frame인 frame_images 항목으로 넣어 POST /v1/videos를 보내고, 움직임은 prompt에 설명하세요. model: "sume/auto"를 쓰면 Sume가 모델 계열을 고르며, 생성 옵션의 기본값은 720p와 8초이고 클립 길이는 3–10초, 비율은 16:9 또는 9:16입니다. 어떤 모델이 어떤 프레임을 받는지는 Image-to-Video API에서 확인하세요.

• 호출은 Job id와 polling_url을 담아 202를 반환합니다. status가 completed가 될 때까지 폴링하세요. 같은 Job은 GET /v1/jobs/{id}/status와 GET /v1/jobs/{id}/result에서도 볼 수 있습니다.
• Idempotency-Key를 보내세요. 재전송하면 원래 Job이 반환됩니다.

curl -X POST https://api.sume.com/v1/videos \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sku-1042-i2v-v1" \
  -d '{
    "model": "sume/auto",
    "prompt": "Slow camera push-in on the product, soft studio light",
    "aspect_ratio": "9:16",
    "duration": 6,
    "frame_images": [
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/sku-1042-front.jpg" },
        "frame_type": "first_frame"
      }
    ]
  }'

어느 경로를 골라야 하고, 각각 비용은 얼마인가요?

제작 결정을 Format에 저장된 레시피와 도구에 맡기려면 Format을, 모션 프롬프트를 직접 쓰려면 직접 경로를 고르세요. 에이전트 자체의 LLM 턴까지 포함한 Format 실행의 총비용은 영수증의 usage.debited_usd_micros입니다.

출시하기 전에 무엇을 확인해야 하나요?

같은 문서 페이지에 나온 규칙 몇 가지입니다.

• Format 미디어 URL은 만료되지 않는 내구성 있는 media.sume.com URL이며, URL을 가진 누구에게나 공개됩니다. 판매자마다 별도의 접근 제어가 필요하다면 프록시하거나 복사해 두세요.
• API 실행은 무인 실행입니다. 승인은 이미 부여된 것으로 처리되며, 끝낼 수 없는 실행은 반쯤 끝난 completed가 아니라 failed로 돌아옵니다.