Format으로 제품 사진 한 장에서 마케팅 에셋 만들기

Sume API로 제품 사진 한 장에서 여러 마케팅 에셋을 만들려면, 에셋마다 카탈로그 Format 실행을 하나씩 시작하고 각 실행의 attachments에 같은 팩샷 URL을 보내세요. 예를 들어 히어로 스틸에는 sume-water-splash-hero를, 영상에는 sume-product-commercial을 씁니다. 실행마다 Idempotency-Key와 지출 상한을 따로 두고, 각 에셋은 그 실행의 영수증에서 읽으세요.

아래 내용은 2026-09-27에 확인한 Sume 문서 Format 카탈로그 (영문), Format 호출하기 (영문), 실행과 결과 (영문), 구조화 출력 (영문) 페이지에서 가져왔습니다. 각 Format의 설명은 카탈로그 항목에서 그대로 인용했습니다. 카탈로그 전체는 바로 쓰는 제품 영상 Format에 정리되어 있습니다.

어떤 Format이 어떤 에셋을 만드나요?

각 Format은 설명을 보고 고르세요. 설명으로 스틸과 영상도 구분할 수 있습니다. 아래 이미지 Format의 설명은 "Not for: animated or motion deliverables"(애니메이션이나 모션 결과물용이 아님)로, 영상 Format의 설명은 "Not for: static campaign deliverables"(정적인 캠페인 결과물용이 아님)로 끝납니다. 여기 나온 이미지 Format 세 개는 모두 스킨케어 작업을 명시하므로, 이 키트는 스킨케어 제품용입니다. 설명은 각 Format의 목표를 밝힐 뿐 결과를 약속하지 않으며, 그 뒤의 레시피는 비공개로 유지됩니다.

에셋마다 실행을 하나씩 어떻게 시작하나요?

formats:write가 있는 키로 Format마다 POST /v1/formats/sume/{slug}/runs를 한 번씩 보내세요. 대량 실행 요청은 같은 Format에 대한 여러 호출을 큐에 넣는 기능이므로, 여러 Format이 섞인 키트는 생성 요청을 따로따로 보내야 합니다. Sume는 생성 요청마다 첨부를 가져와 내구성 있는 저장소에 복사하며, 이미 media.sume.com에 있는 URL은 다시 복사하지 않습니다.

• 멱등성 키의 범위는 Format 하나입니다. 같은 Idempotency-Key를 두 Format에 보내면 실행이 두 개 시작됩니다. 아래처럼 제품, Format, 버전으로 각 키를 만드세요. 요청마다 uuidgen으로 키를 새로 만들면 이 헤더는 장식에 그칩니다.
• 실행이 시작하는 Job에는 워크스페이스의 생성 동시성 한도가 그대로 적용되며, Job은 슬롯이 빌 때까지 queued 상태로 기다릴 수 있습니다. 영상 Job 동시성과 큐를 참고하세요.
• 실행과 그 미디어, 지출은 호출한 키에 귀속됩니다.

for SLUG in sume-water-splash-hero sume-product-commercial sume-close-camera-ugc; do
  curl -sS -X POST "https://api.sume.com/v1/formats/sume/$SLUG/runs" \
    -H "Authorization: Bearer $SUME_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: sku-4411-$SLUG-v1" \
    -d '{
      "instruction": "Campaign asset for the attached moisturizer.",
      "attachments": [
        { "type": "input_image", "image_url": "https://example.com/sku-4411.png", "filename": "packshot.png" }
      ],
      "generation_spend_cap_usd": 20,
      "communication": { "webhook_url": "https://example.com/hooks/sume" }
    }'
done

각 에셋은 어떻게 돌려받나요?

output_schema를 생략하면 각 실행의 output은 내장 형태인 sume/action-run-output/v1을 씁니다. text와 images, videos, audio, files 배열로 이루어지며, 실행이 생성한 미디어로 결정적으로 채워집니다. primary_output_url은 videos, images, audio, files 순서로 값을 찾으므로, 읽는 코드 하나로 스틸과 클립을 모두 처리할 수 있습니다. 직접 만든 스키마를 바인딩한다면 그 Format이 만드는 것만 필수로 요구하세요.

각 실행은 완료되거나 실패할 때 서명된 format.run.terminal 웹훅을 한 번 보냅니다. 중복은 request_id로 걸러 내세요. GET /v1/format-runs 목록 조회는 없으므로, 각 실행의 data.id를 그 실행이 만드는 에셋과 짝지어 저장하세요. media.sume.com URL은 만료되지 않고 URL을 가진 사람이면 누구나 접근할 수 있으므로, 제품에 고객별 접근 제어가 필요하다면 프록시를 두거나 복사해 두세요.

키트 하나의 비용은 얼마인가요?

실행마다 자체 상한이 있습니다. generation_spend_cap_usd는 최대 $500이며, null은 $500으로 실행되고 0은 거부됩니다. 생략하면 실행은 Format의 상한을 물려받으며, 이 값은 GET /v1/formats/…가 generation_spend_cap_usd_micros로 알려 줍니다.

키트의 비용은 각 실행의 usage.debited_usd_micros를 더한 값으로, 에이전트 자체의 LLM 턴을 포함해 지갑에서 차감된 금액입니다. 상한이 집계하는 금액이 아니라 이 수치가 비용인 이유는 AI 영상 한 편 생성 비용에서 설명합니다.

에셋 하나가 실패하면 어떻게 하나요?

failed 영수증에는 이유를 담은 error가 있고, artifacts[]에는 실행이 만든 것이 그대로 나열됩니다. 그 에셋 하나는 다음 두 가지 중 한 방법으로 다시 만드세요.

• 키를 만드는 규칙에서 버전을 올려 새 키를 만들고, 같은 Format의 실행을 새로 시작하세요.
• 실행이 작업을 남겼다면 previous_run_id로 이어 가세요. 이어 가기는 자체 상한과 자체 웹훅을 가진 새 실행입니다. 어떤 실행을 이어 갈 수 있는지는 Sume API로 AI 영상의 장면 하나를 다시 생성하기에서 다룹니다.