아바타 영상 프리뷰: 렌더링 전에 첫 프레임 승인하기

아바타 영상 프리뷰는 Sume 말하는 아바타 영상의 첫 프레임 스틸 단계로, 전체 렌더를 시작하지 않고 생성됩니다. POST /v1/avatar-video-previews로 프리뷰를 만들고 스틸을 검토하거나 다시 생성한 다음, 프리뷰 id로 generate-video를 호출해 최종 렌더를 시작하세요.

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

프리뷰는 언제 사용해야 하나요?

Avatar Video 생성 비용을 온전히 쓰기 전에 구도를 승인하고 싶을 때 프리뷰를 사용하세요. 프리뷰 단계 없이 바로 전체 렌더를 하려면 말하는 아바타 영상 API에서처럼 아바타 영상 생성을 대신 사용하세요. 프리뷰는 다음 세 가지 경우에 적합합니다.

• 전체 렌더 전에 장면 구도와 첫 프레임을 검토할 때.
• 다중 장면 video_inputs에서 장면마다 스틸을 하나씩 받고 싶을 때. 다중 장면 아바타 영상 API를 참고하세요.
• 생성할 때 자막 의도를 저장해 두고 generate-video 시점에만 자막을 적용하고 싶을 때. 프리뷰 스틸에는 자막이 절대 새겨지지 않습니다.

프리뷰 흐름은 어떤 엔드포인트로 이루어지나요?

프리뷰는 어떻게 만드나요?

생성 본문은 Avatar Video 필드와 같습니다. script와 video_inputs 중 정확히 하나를 보내고, 선택적으로 product_image, scene, quality, aspect_ratio, title, captions를 함께 보냅니다. quality는 생략하면 plus가 기본값입니다(standard, plus, max 중 하나).

반환된 Job은 다른 생성과 마찬가지로 /v1/jobs/job_123/status와 /v1/jobs/job_123/result에서 폴링하세요.

curl -X POST https://api.sume.com/v1/avatar-video-previews \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "avatar_handle": "product_host",
    "script": "Meet the Acme travel mug. It fits every cup holder and every bag.",
    "quality": "plus"
  }'

준비된 프리뷰에는 무엇이 들어 있나요?

id로 프리뷰 리소스를 읽으세요. 준비되면 공개 가능한 필드에는 다음이 포함됩니다.

• preview_image_url: 대표 스틸입니다(다중 장면이면 장면 0).
• scene_previews[]: 가능한 경우 입력 장면마다 스틸 하나씩입니다. 장면을 공유하는 다중 장면 프리뷰에서는 뒤쪽 장면 스틸이 첫 프레임의 포즈를 이어받은 연속 이미지입니다.
• resource_status / job_status: 준비 여부와 Job 폴링에는 레거시 status 필드 대신 이 둘을 사용하세요.

curl https://api.sume.com/v1/avatar-video-previews/avp_123 \
  -H "Authorization: Bearer $SUME_API_KEY"

스틸은 어떻게 다시 생성하나요?

POST /v1/avatar-video-previews/:id/regenerate를 호출하세요. 저장된 프리뷰 요청(아바타, 스크립트 또는 video_inputs, 장면, 품질, 화면 비율)을 재사용해 첫 프레임 스틸만 새로 만듭니다. 같은 avatar_video_preview_id와 함께 새 프리뷰 전용 Job이 반환됩니다.

승인한 프리뷰를 어떻게 최종 영상으로 만드나요?

프리뷰 id로 generate-video를 호출하세요. Sume는 일반 Avatar Video 워크플로를 시작하고, 가능하면 프리뷰의 첫 프레임을 재사용합니다. 프리뷰를 만들 때 저장한 자막은 이 단계에서 적용됩니다. 반환된 Job을 폴링한 다음 /v1/avatar-videos/avatar_video_123에서 아바타 영상 리소스를 읽으세요.

최종 렌더는 전체 Avatar Video 생성이며, 등급별 초당 요금이 적용됩니다. 요율은 초당 $0.184(standard), $0.245(plus), $0.55(max), 제품 이미지 없음 기준이고, 여기에 기본 5.5% 에이전트 수수료가 더해집니다. 제품 이미지가 있을 때의 요율은 API 요금에 있습니다.

• 본문을 비우거나 {}를 보내면 프리뷰 생성 때 고른 품질이 유지됩니다.
• 선택 필드 quality는 최종 렌더 등급만 덮어씁니다. 프리뷰 스틸은 등급과 무관하게 항상 재사용되므로, 승인한 뒤 등급을 바꿔도 새 프리뷰가 필요하지 않습니다.
• 접수, 사전 결제, 원장 예약, 프로바이더 제출, 리드백 모두 실제 적용된(덮어쓴) 등급을 사용합니다.
• 구조적 필드(script, video_inputs, avatar_handle, scene, aspect_ratio)를 바꾸려면 여전히 새 프리뷰가 필요합니다.

curl -X POST https://api.sume.com/v1/avatar-video-previews/avp_123/generate-video \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "quality": "standard" }'

프리뷰에는 어떤 제한이 있나요?

• 길이 범위는 Avatar Video와 같은 추정 4-60초(양 끝 포함)입니다.
• 미디어 입력은 URL 우선의 공개 HTTPS 필드입니다. product_image, scene.image_url, 장면 배경 이미지 URL이 여기에 해당합니다.
• 프리뷰 생성 때의 인라인 자막은 generate-video를 위해 저장되며, 프리뷰 스틸에는 새겨지지 않습니다.
• generate-video의 quality는 최종 영상의 프로바이더 등급만 바꿉니다.
• 정확한 요청·응답 스키마는 라이브 OpenAPI에 있습니다.