---
title: 아바타 비디오 생성
description: 준비된 아바타와 스크립트 또는 다중 장면 입력, 그리고 선택적 제품·장면 레퍼런스로 말하는 아바타 비디오를 만드는 방법을 살펴보세요.
---

아바타 비디오는 준비된 아바타를 스크립트 기반의 말하는 비디오로 바꿉니다. 정식
Avatar 1.0 라우트를 사용하세요.

```text
POST /v1/avatar-1.0/talking-video
```

실행 요청은 최상위 `avatar_handle`(또는 `video_inputs` 안의 장면별 캐릭터
필드)로 준비된 아바타를 참조합니다. `script`와 `video_inputs` 중 정확히 하나를
제공하세요.

Sume가 추정한 목표 비디오 길이가 4~60초 범위일 때 스크립트와 다중 장면 계획이
접수됩니다. 더 긴 스크립트는 줄이거나 여러 Job으로 나누세요.

## 아바타 비디오 만들기

<!-- api-call-example:avatar-talking-video -->

### 선택적인 제품과 장면 입력

- 제품 없는 아바타 비디오라면 `product_image`를 생략하세요.
- 장면 연출에는 `scene: { "type": "prompt", "prompt": "..." }`을 사용하세요.
- 사진 장면 레퍼런스에는
  `scene: { "type": "photo", "image_url": "https://..." }`를 사용하세요.
- 미디어 필드는 가져올 수 있는 공개 HTTPS URL이어야 합니다.
  [미디어 입력](/workflows/asset-library)에서 살펴보세요.

### 품질

Avatar Video는 `quality: "standard" | "plus" | "max"`를 받습니다.

| 값 | 동작 |
|---|---|
| `plus` | 생략했을 때의 **기본값**입니다. 균형 잡힌 품질 경로입니다. |
| `standard` | 가장 빠른 Sume 실행 경로입니다. |
| `max` | 가장 높은 품질 등급이며 처리 시간이 더 깁니다. |

### 화면 비율과 해상도

- `aspect_ratio`는 `1:1`, `3:4`, `9:16`, `4:3`, `16:9`를 지원합니다. 기본값은
  `9:16`입니다.
- `resolution`은 현재 `720p`입니다.

## 다중 장면 `video_inputs`

훅, 데모, 무음 비트를 한 영상에 담아야 한다면 단일 `script` 대신 순서가 있는
`video_inputs`를 사용하세요. 계획된 전체 길이는 여전히 4~60초 안에 들어와야
합니다.

```bash
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-multi-001" \
  -d '{
    "avatar_handle": "sume_clawra",
    "aspect_ratio": "9:16",
    "quality": "plus",
    "video_inputs": [
      {
        "id": "hook",
        "voice": {
          "type": "text",
          "script": "Wait, this turned one selfie into a whole video?",
          "duration": 3
        },
        "background": {
          "type": "prompt",
          "prompt": "Casual bedroom framing, native UGC lighting"
        }
      },
      {
        "id": "demo",
        "voice": {
          "type": "silence",
          "duration": 4
        },
        "background": {
          "type": "prompt",
          "prompt": "Casual bedroom framing, native UGC lighting"
        }
      },
      {
        "id": "cta",
        "voice": {
          "type": "text",
          "input_text": "You pick a template, drop in your photo, and it builds the clip around you.",
          "duration": 5
        },
        "background": {
          "type": "prompt",
          "prompt": "Casual bedroom framing, native UGC lighting"
        }
      }
    ]
  }'
```

`voice.type: "silence"`는 말하지 않는 비트입니다. `duration`이 필수이고
`script` / `input_text`는 허용되지 않습니다. 말하는 장면은 여전히
`type: "text"`를 쓰며 `script`와 `input_text` 중 정확히 하나를 사용합니다.

현재 실행은 최종 비디오 하나당 해석된 아바타 하나를 지원하고, 장면 배경이 하나의
공유 장면으로 해석되기를 기대합니다.

## 인라인 캡션

선택 필드 `captions`는 생성이 끝난 뒤 깨끗한 최종 MP4에 스타일을 입혀 새깁니다.
말한 스크립트 또는 `video_inputs` 텍스트를 사용합니다. 프리뷰 스틸에는 캡션이
들어가지 않습니다.

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

- `captions`는 단독 [비디오 캡션](/models/video-captions)과 같은 네 가지 옵션을
  받습니다 — `style`, 선택 `font`, `language` 힌트, `script_text`.
- 스타일: `slam`(기본), `punch`, `tiktok-green`, `korean-ad`(한국어 음성용 한글
  카라오케), 그리고 한글 아이덴티티 `weight-shift`, `black-outline`,
  `highlight`, `pill-karaoke`, `clip-wipe`, `editorial-emphasis`.
- 한국어 대본을 `style: "slam"`(또는 `punch` / `tiktok-green`)로 보내면 스타일을
  몰래 바꾸지 않고 `400 caption_hangul_text_latin_style`로 거부합니다. 해당
  서체는 한글을 두부로 렌더링합니다. 한국어 음성에는 한글 스타일을 쓰세요.
- 추정 길이가 60초를 넘으면 인라인 캡션은 거부됩니다.
- 캡션 단계 실패는 소프트 실패입니다. 아바타 Job은 깨끗한 기본 `video_url`과
  `captions.status=failed`로 성공할 수 있습니다.
- 인라인 캡션은 별도로 과금되는 비디오 캡션 Job을 만들지 **않습니다**. 기존 공개
  비디오 URL에 캡션을 넣으려면 [비디오 캡션](/models/video-captions)을
  사용하세요.

## 폴링과 복구

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

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

완료된 결과에는 공개 `media.sume.com` 비디오 산출물과 함께
`preview_image_url`, `scene_previews` 같은 공개 가능한 프리뷰 필드가 포함될 수
있습니다.

## 아바타 비디오 리소스 읽기

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

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

## 먼저 미리 보고 생성하기

전체 렌더에 비용을 쓰기 전에 첫 프레임 스틸을 확인하려면
[아바타 비디오 프리뷰](/models/avatar-video-previews)를 만든 다음 프리뷰 id로
`generate-video`를 호출하세요.

## 호환 별칭

| 별칭 | 설명 |
|---|---|
| `POST /v1/models/sume/avatar-1.0/talking-video/runs` | 정식 model-run 별칭입니다. 새 연동에는 `/v1/avatar-1.0/talking-video`를 사용하세요. |
| `POST /v1/models/sume/avatar-video/v1.0/runs` | 레거시 실행 별칭입니다. 본문 계약은 같습니다. |

## 관련 문서

- [아바타 만들기](/models/avatar)
- [아바타 비디오 프리뷰](/models/avatar-video-previews)
- [페이스 스왑 (Beta)](/models/face-swap)
- [비디오 캡션](/models/video-captions)
- [Job과 결과](/workflows/jobs-and-results)