AI 제품 데모 영상 생성 API: 실제 동작 하나 보여 주기

Sume API로 제품 데모 영상을 생성하려면 카탈로그 Format sume-product-usage-demo를 POST /v1/formats/sume/sume-product-usage-demo/runs로 호출하면서, 제품 사진은 attachments에, 보여 줄 동작 하나는 instruction에 넣으세요. 직접 만들려면 제품을 사용하는 장면의 스틸을 POST /v1/videos로 영상으로 만들되 동작마다 클립을 하나씩 만들고, Timeline 1.0 렌더로 클립들을 이어 붙이세요.

아래 내용은 2026-09-27에 확인한 Sume 문서 Format 카탈로그 (영문), Format 호출하기 (영문), 영상 생성 (영문), Timeline 1.0 페이지와 Sume API 레퍼런스에서 가져왔습니다. AI UGC 광고 생성 API는 이 Format을 UGC Format들과 함께 나열하지만, 이 글은 데모를 다룹니다.

제품 사용 데모 Format은 무엇을 만드나요?

sume-product-usage-demo(카탈로그 제목: Sume Product Usage Demo)는 카탈로그의 영상 Format입니다. 설명은 다음과 같습니다. "Create a finished product-usage video that demonstrates one real action, texture, or result in a casual social setting. Use when the user asks for skincare application, household product demos, unbox-and-use clips, and hands-on product ads. Not for: static campaign deliverables."(일상적인 소셜 분위기에서 실제 동작, 질감, 결과 하나를 보여 주는 완성된 제품 사용 영상을 만듭니다. 스킨케어 바르기, 생활용품 데모, 언박싱 후 사용 클립, 직접 써 보는 제품 광고를 요청받았을 때 쓰며, 정적인 캠페인 결과물에는 쓰지 않습니다.)

이것은 Format이 내세우는 목표이지, 개별 클립에 대한 보장이 아닙니다. 레시피는 비공개로 유지되며, 여러분이 보내는 것은 브리프(instruction), 호출자 데이터(input), 이미지(attachments)입니다. 실행의 model 필드는 실행을 오케스트레이션하는 LLM만 고르며, 이미지·영상·오디오 모델은 Format의 도구가 고릅니다.

데모 실행의 브리프는 어떻게 쓰나요?

formats:write가 있는 키라면 어떤 키로든 호출할 수 있습니다. 각 실행은 설명에 적힌 범위 안에 두세요.

• instruction에는 동작, 질감, 결과 중 하나를 적으세요. 이 필드는 8000자까지 받으며, 앞의 약 4000자가 실행에 전달됩니다.
• 팩샷은 공개 HTTPS image_url을 담은 input_image로 첨부하세요. 실행 하나에 이미지를 최대 30장까지 넣을 수 있습니다.
• 제품 정보는 input에 넣으세요. input은 통째로 파일에 기록되며, 에이전트는 그 파일을 지시가 아니라 데이터로 다루라는 안내를 받습니다.
• SumeMediaFile# 필드가 있는 output_schema를 바인딩하고 그 필드를 primary_output_key에 지정하세요. 그러면 primary_output_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: acme-serum-demo-pump-v1" \
  -d '{
    "instruction": "Demo: one pump of the attached serum worked into the back of a hand.",
    "input": { "product_name": "Acme Serum" },
    "attachments": [
      { "type": "input_image", "image_url": "https://example.com/serum.png", "filename": "serum.png" }
    ],
    "output_schema": {
      "name": "acme/demo-clip/v1",
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": ["demo_video"],
        "properties": { "demo_video": { "$ref": "SumeMediaFile#" } }
      }
    },
    "primary_output_key": "demo_video",
    "generation_spend_cap_usd": 20,
    "communication": { "webhook_url": "https://example.com/hooks/sume" }
  }'

데모 클립을 직접 만들려면 어떻게 하나요?

제품을 사용하는 장면의 스틸을 영상으로 만들되, 클립 하나에 동작 하나씩 담으세요. 사진을 첫 프레임으로 삼아 영상으로 만드는 방법은 제품 사진으로 영상 만들기 API에서 다룹니다. 데모에서 달라지는 것은 시작하는 스틸과, 클립이 그다음에 쓰이는 곳입니다.

• 사용 장면 스틸은 팩샷을 input_references에 담아 POST /v1/images로 보내 만드세요. 응답의 data[].url은 Sume가 호스팅하는 서명된 URL이고, 영상 문서에는 이 URL을 frame_images에 바로 넣는 방법이 나와 있지 않습니다. 그러니 고른 스틸은 직접 관리하는 공개 HTTPS URL에 올려 두세요.
• 그 스틸을 POST /v1/videos의 frame_images에 frame_type: "first_frame"으로 넣으세요. 팩샷을 추가 input_references 항목으로 함께 보내는 방법에는 기대지 마세요. 둘 다 보내면 frame_images가 우선하고, 요청은 이미지로 영상 만들기로 처리됩니다.
• 길이, 해상도, 소리는 모델마다 다릅니다. GET /v1/videos/models에서 supported_durations, supported_resolutions, generate_audio를 확인하세요.
• 클립의 media.sume.com URL은 GET /v1/jobs/{id}/result에서 읽으세요. 아래 Timeline 단계에 이 URL이 필요합니다. Sume는 생성 결과를 노출하기 전에 Sume 소유의 미디어 URL로 미러링합니다.

여러 단계를 데모 하나로 어떻게 이어 붙이나요?

단계마다 클립을 따로 렌더링한 뒤, 그 클립들을 Timeline 1.0 렌더 하나(POST /v1/timeline-1.0/render)의 video[] 슬롯에 배치하세요. 렌더는 MP4 하나를 반환합니다. 렌더에 들어가는 모든 URL은 이미 워크스페이스에 있는 media.sume.com 아티팩트나 에셋이어야 합니다. 전환 효과는 영상 전환 효과 API에서 다룹니다.

• 렌더 하나에는 슬롯이 1–200개 들어갑니다. video[0].start는 0이어야 하고, 이후 슬롯의 시작 시각은 계속 커져야 합니다.
• 렌더의 오디오는 보이스오버 스파인(audio.url 또는 audio.parts[])에 선택 사항인 soundtrack 배경 음악을 더한 것입니다. audio.mode: "silence"를 쓰면 대신 무음 오디오 트랙을 렌더링합니다.
• POST /v1/timeline-1.0/plan은 Job을 만들거나 크레딧을 예약하지 않고 문서를 검사합니다.

데모 비용은 얼마인가요?

Format 경로에서는 생성이 API 요금의 요율로 계량되고 generation_spend_cap_usd로 제한됩니다. 최대 $500이며, null은 $500으로 실행되고, 0은 거부됩니다. 영수증의 usage.debited_usd_micros는 에이전트 자체의 LLM 턴을 포함해 지갑에서 차감된 금액입니다. 직접 만드는 경로에서는 영상 Job마다 제출 시 공급사 정가 × 1.25가 예약되고, 이미지와 렌더는 각각 따로 과금됩니다.