---
title: 아바타 비디오 프리뷰
description: 첫 프레임 Avatar Video 프리뷰를 만들고, 스틸을 다시 생성하고, 최종 비디오까지 생성하는 방법을 살펴보세요.
---

아바타 비디오 프리뷰는 전체 토킹 비디오 렌더를 시작하지 않고 첫 프레임 스틸
단계만 생성합니다. Avatar Video 생성 비용을 온전히 쓰기 전에 구도를 승인하고
싶을 때 사용하세요.

```text
POST /v1/avatar-video-previews
GET  /v1/avatar-video-previews/:id
POST /v1/avatar-video-previews/:id/regenerate
POST /v1/avatar-video-previews/:id/generate-video
```

## 언제 사용하나요

- 전체 렌더 전에 장면 구도와 첫 프레임을 검토할 때
- 장면마다 스틸이 하나씩 필요한 다중 장면 `video_inputs`일 때
- 생성 시점에 캡션 의도를 저장해 두고 `generate-video` 때만 캡션을 적용하고 싶을
  때(프리뷰 스틸에는 캡션이 새겨지지 않습니다)

프리뷰 단계 없이 바로 전체 렌더를 하려면
[아바타 비디오 생성](/models/avatar-videos)을 사용하세요.

## 프리뷰 만들기

생성 본문은 Avatar Video 필드와 같습니다. `script`와 `video_inputs` 중 정확히
하나를 제공하고, 선택적으로 `product_image`, `scene`, `quality`,
`aspect_ratio`, `title`, `captions`를 함께 보냅니다.

`quality`는 생략하면 **`plus`**가 기본값입니다(`standard` | `plus` | `max`).

<!-- api-call-example:avatar-video-preview-create -->

응답에는 Job 폴링 URL과 `avatar_video_preview_id`가 들어 있습니다. 다른 생성과
마찬가지로 Job을 폴링하세요.

```bash
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/result \
  -H "Authorization: Bearer $SUME_API_KEY"
```

## 프리뷰 리소스 읽기

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

준비되면 공개 가능한 필드는 다음과 같습니다.

- `preview_image_url` — 대표 스틸입니다(다중 장면이면 장면 0).
- `scene_previews[]` — 가능한 경우 입력 장면마다 스틸 하나씩입니다.
- `resource_status` / `job_status` — 준비 여부와 Job 폴링에는 레거시 `status`
  필드 대신 이 둘을 사용하세요.

장면을 공유하는 다중 장면 프리뷰에서는 뒤쪽 장면 스틸이 첫 프레임의 포즈를
이어받은 연속 이미지입니다.

## 스틸 다시 생성하기

저장된 프리뷰 요청(아바타, 스크립트 또는 `video_inputs`, 장면, 품질, 화면
비율)을 재사용해 첫 프레임 스틸만 새로 만듭니다.

<!-- api-call-example:avatar-video-preview-regenerate -->

같은 `avatar_video_preview_id`와 함께 프리뷰 전용 Job이 새로 돌아옵니다.

## 최종 비디오 생성하기

프리뷰가 마음에 들면 프리뷰 id에서 일반 Avatar Video 워크플로를 시작하세요.
Sume는 가능한 경우 프리뷰 첫 프레임을 재사용합니다. 프리뷰 생성 때 저장한 캡션은
이 단계에서 적용됩니다.

본문을 비우면(또는 `{}`) 프리뷰 생성 때 고른 품질이 유지됩니다. 선택 필드
`quality`는 **최종 렌더** 등급만 덮어씁니다. 프리뷰 스틸은 등급과 무관하게 항상
재사용되므로, 승인 후 등급을 낮추거나 올려도 프리뷰를 다시 만들 필요가 없습니다.

<!-- api-call-example:avatar-video-preview-generate -->

접수, 사전 결제, 원장 예약, 프로바이더 제출, 리드백 모두 실제 적용된(덮어쓴)
등급을 사용합니다. 구조적 필드(`script`, `video_inputs`, `avatar_handle`,
`scene`, `aspect_ratio`)를 바꾸려면 여전히 새 프리뷰가 필요합니다.

반환된 Job을 폴링한 다음 아바타 비디오 리소스를 읽으세요.

```bash
curl https://api.sume.com/v1/avatar-videos/avatar_video_123 \
  -H "Authorization: Bearer $SUME_API_KEY"
```

## 제약

- Avatar Video와 같은 길이 범위입니다. 추정 4~60초입니다.
- 미디어 입력은 URL 우선의 공개 HTTPS 필드입니다(`product_image`,
  `scene.image_url`, 장면 배경 이미지 URL 등).
- 프리뷰 생성 때의 인라인 캡션은 `generate-video`를 위해 저장되며, 프리뷰
  스틸에는 새겨지지 않습니다.
- 프리뷰 스틸은 등급과 무관합니다. `generate-video`의 `quality`는 최종 비디오
  프로바이더 등급만 바꿉니다.
- 정확한 요청·응답 스키마는 라이브
  [OpenAPI](https://api.sume.com/reference/json)에 있습니다.

## 관련 문서

- [아바타 비디오 생성](/models/avatar-videos)
- [비디오 캡션](/models/video-captions) (독립 캡션 Job)
- [Job과 결과](/workflows/jobs-and-results)