---
title: Avatar UGC video
description: Formats by Sume의 Avatar video Format을 백엔드에서 호출해, 스크립트를 캡션과 사운드트랙이 들어간 크리에이터 스타일 talking-head 비디오로 바꾸세요.
---

**역할:** 스크립트를 넘기면 완성된 talking-head 비디오를 돌려줍니다 — 브리프에 맞는
카탈로그 아바타 캐스팅, 캡션 번인, 사운드트랙 믹스까지. Format이 preview-then-generate
파이프라인 전체를 소유하므로, 글을 보내고 비디오 URL을 읽으면 됩니다.

**이럴 때 쓰세요.** 크리에이터 스타일 UGC 광고를 대량으로 만들고 스크립트만 바뀔
때입니다. 발표자 없이 제품 이미지와 모션 광고가 필요하면
[Product promo](/formats/product-promo)를 쓰세요.

1st-party slug: `sume-avatar-video-generation`.

## 1. 주소 잡기

아래 스코프를 가진 키라면 `sume/sume-avatar-video-generation`로 바로 호출합니다. fork도,
설치도 필요 없습니다: 카탈로그 Format은 소유자 없이 공유되며, run과 그 미디어, 그 지출은
호출한 키에 귀속됩니다.

Format을 *바꾸고* 싶을 때는 fork가 그대로 있습니다 —
[Format 라이브러리의 Avatar video generation](https://www.sume.com/agents/format)을
열고 **Fork**를 누르면 사용자가 소유한 편집 가능한 사본을 받습니다. fork는 본문과
spend cap을 유지하고 새 slug를 받으며(fork는 원본 slug를 재사용할 수 없으므로
대시보드는 `sume-avatar-video-generation-custom`을 제안합니다), 상세 페이지는 이를
`{your_handle}/{slug}`로 보여 줍니다. 호출을 위한 선행 조건이 아니라 커스터마이즈
단계입니다.

## 2. 스코프

| Scope | Needed for |
|---|---|
| `formats:read` | Format 읽기, run 읽기·목록입니다. |
| `formats:write` | run 시작, run 취소입니다. |

Formats가 출시되기 전에 만든 키에는 이 스코프가 없고, 기존 키에 스코프를 추가할 수
없습니다 — [API Keys](https://www.sume.com/dashboard/api-keys)에서 새 키를 만들고
교체하세요. 서비스 계정 키로는 Format run을 시작할 수 없습니다.

## 3. 호출하기

```bash
export SUME_API_KEY="sume_live_..."

curl -sS -X POST "https://api.sume.com/v1/formats/sume/sume-avatar-video-generation/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "instruction": "Make a 20-second vertical UGC ad from this script. Warm, casual delivery.",
    "input": {
      "script": "I tried three trail shoes this month. This is the only pair I still wear.",
      "aspect_ratio": "9:16",
      "captions": true,
      "product_url": "https://example.com/products/trail-runner"
    },
    "generation_spend_cap_usd": 30
  }'
```

이미 경로를 저장한 클라이언트를 위해 불투명한 `skl_…` 경로는 계속 유효합니다. 새
연동은 `{handle}/{slug}`를 쓰세요.

수락된 run은 `202`를 반환합니다.

```json
{
  "data": {
    "id": "run_...",
    "object": "format.run",
    "format": { "id": "skl_...", "slug": "sume-avatar-video-generation", "version": 1 },
    "status": "queued",
    "status_url": "https://api.sume.com/v1/format-runs/run_.../status",
    "result_url": "https://api.sume.com/v1/format-runs/run_.../result",
    "created_at": "2026-08-02T09:00:00.000Z"
  }
}
```

매 호출에 `Idempotency-Key`를 보내세요. 같은 본문으로 재전송하면 `200`과 원래 run이
돌아옵니다. 다른 본문으로 재전송하면 `409 idempotency_conflict`입니다.

### `input`에 대해

`input`은 자유 형식 JSON이며, 프롬프트에 호출자 데이터로만 울타리를 치고
instruction으로 쓰이지 않습니다. **선언된 스키마가 아닙니다** — Format 본문이 어떤
키를 읽을지 정하므로, 위 예시는 계약이 아니라 현실적인 형태입니다. 작게, 문자
그대로 유지하세요. 최대 64개 키, 8 KiB입니다.

이유가 없다면 캐스팅은 Format에 맡기세요. 스크립트와 브리프에 맞춰 아바타 카탈로그를
검색합니다. 직접 `avatar_handle`을 지정하면 그 결과를 고정하고 검색 단계를 건너뜁니다.

## 4. Spend cap

Avatar video는 카탈로그에서 가장 비싼 항목입니다 — 끝나기 전에 음악, 스틸, 비디오를
만들 수 있으므로 — cap을 의도적으로 설정하세요.

Format의 cap은 run이 따로 지정하지 않았을 때 물려받는 값입니다. 현재
값은 `PublicFormat.generation_spend_cap_usd_micros`에서 읽습니다. 한 번도 지정하지
않은 Format은 플랫폼 기본값 **$400**이며, 설정 가능한 상한은 $500입니다.

run의 `generation_spend_cap_usd`는 $500까지 그 run만의 천장을 지정합니다 — Format
자체의 cap보다 큰 값도 적용되고, $500을 넘으면 오류입니다.

cap이 너무 낮으면 비디오 run이 비디오 없이 끝나는 흔한 이유입니다. `artifacts[]`에
스틸만 있고 비디오가 없으면, 프롬프트를 바꾸기 전에 cap을 올리세요.

## 5. 폴링한 뒤 결과 읽기

Avatar video run은 깁니다. 촘촘한 루프 대신 백오프로 폴링하거나,
`communication.webhook_url`을 넘겨 Sume가 종료 receipt를 전달하게 하세요.

```bash
curl -sS "https://api.sume.com/v1/format-runs/$RUN_ID" \
  -H "Authorization: Bearer $SUME_API_KEY"
```

상태는 `queued`, `processing`, `completed`, `failed`, `canceled`, `skipped`입니다.
가벼운 확인은 `status_url`을 폴링하세요. 상태 필드와 `next_action`만 돌아옵니다.

`completed` receipt는 `output`, run이 만든 모든 내구성 파일인 `artifacts[]`,
완성된 비디오인 `primary_output_url`을 담습니다. 미디어 URL은 만료되지 않는 내구성
있는 `media.sume.com` HTTPS URL입니다.

진행 중인 run 취소:

```bash
curl -sS -X POST "https://api.sume.com/v1/format-runs/$RUN_ID/cancel" \
  -H "Authorization: Bearer $SUME_API_KEY"
```

run이 종료되면 취소는 no-op이며, 어느 쪽이든 현재 receipt가 돌아옵니다.

## 사람들이 놀라는 두 가지

**새 fork는 첫 run 전까지 inactive로 읽힙니다.** 방금 만든 사본에 대해 `GET /v1/formats/{format_id}`는
`status: "inactive"`와 `api_trigger_enabled: false`를 보고합니다. 둘 다 지연
프로비저닝되는 runner에서 읽히기 때문입니다. 그 필드가 `true`가 될 때까지 연동을
막지 마세요 — 첫 `POST .../runs`가 runner를 프로비저닝하고 run은 정상 진행됩니다.
`sume/{slug}` 자체는 항상 `active`로 읽힙니다. 카탈로그는 정의상 호출 가능하기 때문입니다.

**미리보기 게이트는 API run을 멈추지 않습니다.** 채팅에서 이 Format은 미리보기
스틸을 보여 주고 비디오를 만들기 전에 승인을 기다립니다. API에는 사람이 없으므로
run에는 그 승인이 이미 허용되었고 spend cap 안에서 유료 단계까지 계속하라고 알려
줍니다. 정말로 끝낼 수 없는 run — 예를 들어 브리프에 맞는 아바타가 없을 때 — 은
`output_error.code`가 `unattended_blocked`인 `failed`로 돌아오며, 절반만 끝난
`completed`는 없습니다.

## 다음

- [Format 호출하기](/formats/call) — 전체 invoke 계약과 모든 오류 코드
- [실행과 결과](/formats/runs) — receipt, 버전, 취소
- [구조화 출력](/formats/structured-output) — 스키마를 바인딩하고 typed JSON을 받기
- [Product promo](/formats/product-promo) — 이 Format의 제품 이미지 대응
- [아바타 비디오 생성](/models/avatar-videos) — 파이프라인을 직접 구동하고 싶을 때의 하위 모델 API
- [OpenAPI](https://api.sume.com/reference) — 정확한 요청·응답 스키마