AI UGC 광고 생성 API: Sume로 만드는 두 가지 방법

Sume API로 UGC 스타일 광고 영상을 만들려면 두 가지 중 하나를 쓰세요. sume-close-camera-ugc 같은 카탈로그 Format을 POST /v1/formats/sume/{slug}/runs로 호출하면서 브리프는 instruction에, 제품 이미지는 attachments에 넣거나, POST /v1/avatar-1.0/talking-video에 직접 쓴 스크립트와 product_image, scene을 담아 Avatar 1.0 말하는 영상을 렌더링하면 됩니다.

아래 내용은 2026-09-26에 확인한 Sume 문서 Format 카탈로그 (영문), Format 호출하기 (영문), 아바타 영상 생성 페이지에서 가져왔습니다. 카탈로그 전체는 바로 쓰는 제품 영상 Format에서 다룹니다.

UGC 스타일 광고에는 어떤 카탈로그 Format이 맞나요?

카탈로그는 예약된 sume handle에서 응답합니다. slug 중 두 개는 ugc로 끝나고, 세 번째는 이름이 제품 사용 데모를 가리킵니다. Format이 하는 일은 각자 저장된 레시피에 달려 있으므로 호출하기 전에 먼저 읽어 보세요. GET /v1/formats/sume/{slug}는 description과 io 프로필을 돌려주고, 그 프로필의 input_kind가 그 Format이 기대하는 input의 형태를 알려 줍니다. 카탈로그에 없는 slug는 404 format_not_found를 반환합니다.

UGC Format은 어떻게 호출하나요?

카탈로그 Format도 다른 Format과 똑같이 formats:write가 있는 키로 호출합니다. 카탈로그 전반의 규칙은 바로 쓰는 제품 영상 Format에 있습니다. UGC 스타일 광고라면 브리프는 instruction에, 제품 사진은 attachments에 넣으세요. 에이전트가 볼 수 있는 이미지를 최대 30장까지 넣을 수 있습니다. attachments 대신 input에 넣는 미디어 URL은 attachments와 예산 하나를 함께 씁니다. 실행당 파일 30개까지이고, 그중 영상은 10개, 오디오는 10개까지입니다. 에이전트는 Format의 레시피를 적용하고, 이미지·영상·오디오 모델은 Format의 도구가 고릅니다.

모든 생성 요청에 Idempotency-Key를 보내세요. 202는 실행 영수증을 돌려줍니다. communication.webhook_url을 추가하면 실행이 완료되거나 실패할 때 서명된 format.run.terminal POST를 한 번 받습니다.

curl -sS -X POST "https://api.sume.com/v1/formats/sume/sume-close-camera-ugc/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sku-4411-ugc-v1" \
  -d '{
    "instruction": "Short vertical ad for the attached product.",
    "attachments": [
      { "type": "input_image", "image_url": "https://example.com/product.jpg" }
    ],
    "generation_spend_cap_usd": 20
  }'

대신 아바타로 UGC 스타일 광고를 만들려면 어떻게 하나요?

진행자를 직접 고르고 모든 대사를 직접 쓰고 싶다면 아바타 경로를 쓰세요. 요청은 avatar_handle로 준비된 아바타를 지정하고, script와 video_inputs 중 정확히 하나를 담습니다. 제품 없는 영상이라면 product_image를 생략하세요. scene은 prompt를 담은 { "type": "prompt" }이거나 image_url을 담은 { "type": "photo" }일 수 있으며, 미디어 필드는 가져올 수 있는 공개 HTTPS URL이어야 합니다. 아직 아바타가 없다면 재사용 가능한 AI 아바타 만들기를 참고하세요.

문서의 다중 장면 예시는 UGC 광고와 같은 구성입니다. 말하는 훅, demo라는 이름의 사 초 길이 silence 비트, 말하는 콜투액션으로 이루어지며, 모든 장면의 배경 프롬프트는 "Casual bedroom framing, native UGC lighting"입니다.

curl -X POST https://api.sume.com/v1/avatar-1.0/talking-video \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ugc-avatar-sku-4411-v1" \
  -d '{
    "avatar_handle": "acme_host",
    "script": "I kept this in my bag all week. Here is why.",
    "product_image": "https://example.com/product.png",
    "scene": { "type": "prompt", "prompt": "Casual bedroom framing, native UGC lighting" },
    "quality": "plus",
    "aspect_ratio": "9:16"
  }'

자막을 넣고, 비용을 내기 전에 첫 프레임을 확인할 수 있나요?

네, 아바타 경로에서는 할 수 있습니다. 선택 필드 captions를 쓰면 말한 스크립트로 만든 자막을 최종 MP4에 스타일과 함께 입힙니다. 기본 스타일은 slam이며, 인라인 자막은 별도로 과금되는 자막 Job을 만들지 않습니다. 자막 단계가 실패해도 아바타 Job은 깨끗한 video_url과 captions.status=failed로 성공할 수 있습니다. 전체 렌더 비용을 내기 전에 첫 프레임 스틸을 검토하려면 아바타 영상 프리뷰를 만든 뒤 그 id로 generate-video를 호출하세요. 방법은 아바타 영상 프리뷰에 나온 대로입니다.

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

제작 결정을 Format에 저장된 레시피와 도구에 맡기고 싶다면 카탈로그 Format을, 진행자를 정해 두고 대사를 정확히 지정해야 한다면 아바타 경로를 고르세요. Format 경로에서는 실행 상한에 잡히는 생성이 API 요금의 요율로 계량되고, generation_spend_cap_usd가 그 범위를 제한합니다. 최대 $500이며, null은 $500으로 실행되고, 0은 거부됩니다. 영수증의 usage.billable_amount_usd_micros는 에이전트 자체의 LLM 턴을 제외하므로 실행의 총비용이 아닙니다. 아바타 영상은 quality와 제품 이미지를 보내는지에 따라 초 단위로 가격이 매겨집니다. 제품 이미지가 있을 때 요율은 standard 초당 $0.194, plus 초당 $0.258, max 초당 $0.58입니다.

어떤 제한이 있나요?

아래 제한은 같은 문서 페이지에서 가져왔습니다.

• 아바타 스크립트와 다중 장면 계획은 추정 길이가 4–60초여야 합니다. 더 긴 스크립트는 줄이거나 여러 Job으로 나누세요.
• 현재 아바타 실행은 최종 영상 하나에 해석된 아바타 하나만 지원하며, 장면 배경이 공유 장면 하나로 해석되기를 기대합니다.
• 아바타 aspect_ratio는 1:1, 3:4, 9:16, 4:3, 16:9 중 하나이고, resolution은 현재 720p입니다.
• 카탈로그 Format은 공개된 그대로 사용합니다. 바꾸고 싶다면 Format 라이브러리에서 fork한 뒤 {your_handle}/{slug}로 사본을 호출하세요.