말하는 아바타 영상 API: 스크립트로 아바타 영상 생성하기

Sume의 말하는 아바타 영상 API는 준비된 아바타와 스크립트로 말하는 영상을 만듭니다. avatar_handle과, Sume가 추정한 길이가 4-60초인 script를 담아 POST /v1/avatar-1.0/talking-video를 보내세요. 요청은 Job으로 실행되며, 완료된 결과에는 공개 media.sume.com 영상 산출물이 포함될 수 있습니다.

아래 내용은 모두 아바타 영상 생성 문서 페이지에서 가져왔습니다.

호출하기 전에 무엇이 필요한가요?

• 최상위 avatar_handle로 참조할 준비된 아바타가 필요합니다. 만드는 방법은 재사용 가능한 AI 아바타 만들기에 나와 있습니다.
• script와 video_inputs 중 정확히 하나가 필요합니다. 이 가이드는 script를 사용하며, 순서 있는 장면은 다중 장면 아바타 영상 API에서 다룹니다.
• 스크립트는 Sume가 추정한 길이가 4-60초(양 끝 포함)여야 합니다. 더 긴 스크립트는 줄이거나 여러 Job으로 나누세요.
• product_image나 사진 장면 같은 미디어 필드에는 가져올 수 있는 공개 HTTPS URL이 필요합니다.

요청은 어떤 형태인가요?

아래 요청은 프롬프트로 장면을 지정한, 제품 없는 9:16 영상을 만듭니다. 제품 없는 아바타 영상이라면 product_image를 생략하고, 그렇지 않다면 선택적인 제품 레퍼런스로 넘기세요.

새 연동에는 /v1/avatar-1.0/talking-video를 우선 사용하세요. 호환 별칭은 POST /v1/models/sume/avatar-1.0/talking-video/runs(정식 model-run 별칭)와 POST /v1/models/sume/avatar-video/v1.0/runs(레거시 실행 별칭, 본문 계약 동일)입니다.

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: avatar-video-001" \
  -d '{
    "avatar_handle": "product_host",
    "script": "Meet the Acme travel mug. It fits every cup holder and every bag.",
    "scene": { "type": "prompt", "prompt": "Bright kitchen counter, morning light" },
    "quality": "plus",
    "aspect_ratio": "9:16"
  }'

어떤 옵션을 설정할 수 있나요?

어떤 품질 등급을 골라야 하나요?

요율은 초당 $0.184(standard), $0.245(plus), $0.55(max), 제품 이미지 없음 기준이며, 여기에 기본 5.5% 에이전트 수수료가 더해집니다. 제품 이미지가 있을 때의 요율은 API 요금에 있습니다. 문서는 세 등급을 다음과 같이 설명합니다.

• plus: 생략했을 때의 기본값입니다. "Balanced quality path."(균형 잡힌 품질 경로)
• standard: "Fastest Sume execution path."(가장 빠른 Sume 실행 경로)
• max: "Highest quality tier; slower turnaround."(가장 높은 품질 등급, 더 느린 처리)

Sume가 아바타 영상에 자막을 새겨 넣을 수 있나요?

네. 선택 필드 captions는 생성이 끝난 뒤 아바타가 말하는 스크립트를 사용해 깨끗한 최종 MP4에 스타일을 입혀 새깁니다. 옵션은 단독 영상 캡션과 같은 네 가지로, style, 선택 font, language 힌트, script_text입니다.

• 스타일은 slam(기본), punch, tiktok-green, korean-ad(한국어 음성용 한글 카라오케), 그리고 한글 아이덴티티인 weight-shift, black-outline, highlight, pill-karaoke, clip-wipe, editorial-emphasis가 있습니다.
• 한국어 스크립트에 slam, punch, tiktok-green을 쓰면 400 caption_hangul_text_latin_style로 거부됩니다. 한국어 음성에는 한글 스타일을 고르세요.
• 추정 길이가 60초를 넘으면 인라인 자막은 거부됩니다.
• 자막 단계의 실패는 소프트 실패입니다. 이 경우에도 아바타 Job은 깨끗한 기본 video_url과 captions.status=failed로 성공할 수 있습니다.
• 인라인 자막은 별도로 과금되는 영상 캡션 Job을 만들지 않습니다. 기존 공개 영상 URL에 자막을 넣으려면 영상 캡션을 사용하세요.

{
  "captions": {
    "enabled": true,
    "style": "slam",
    "language": "auto"
  }
}

완성된 영상은 어떻게 받나요?

Job 상태를 폴링하고, 이벤트를 읽고, 결과를 가져오세요. 완료된 결과에는 공개 media.sume.com 영상 산출물과 함께 preview_image_url, scene_previews 같은 공개 가능한 프리뷰 필드가 포함될 수 있습니다. 나중에 아바타 영상 리소스를 나열하거나 읽으려면 GET /v1/avatar-videos 또는 GET /v1/avatar-videos/avatar_video_123을 호출하세요.

curl https://api.sume.com/v1/jobs/job_123/status \
  -H "Authorization: Bearer $SUME_API_KEY"

curl https://api.sume.com/v1/jobs/job_123/events \
  -H "Authorization: Bearer $SUME_API_KEY"

curl https://api.sume.com/v1/jobs/job_123/result \
  -H "Authorization: Bearer $SUME_API_KEY"

전체 렌더 비용을 내기 전에 첫 프레임을 확인할 수 있나요?

네. 전체 렌더 비용을 내기 전에 첫 프레임 스틸을 검토하려면 먼저 아바타 영상 프리뷰를 만든 다음, 프리뷰 id로 generate-video를 호출하세요. 이 흐름은 아바타 영상 프리뷰: 첫 프레임 승인하기에서 다룹니다.