---
title: 비디오 캡션
description: 기존 공개 비디오 URL에 스타일, 언어, 선택적 스크립트 정렬을 적용해 캡션을 입히는 방법을 살펴보세요.
---

독립 실행형 비디오 캡션은 공개 HTTPS 비디오 URL을 받아 Job 기반의 캡션 입힌
비디오를 반환합니다. 이미 완성된 클립이 있다면 이 방식을 권장합니다. Avatar
Video에서는 [talking-video](/models/avatar-videos)에 인라인 `captions`를
켜거나 [프리뷰](/models/avatar-video-previews)에 캡션 의도를 저장할 수도
있습니다.

```text
POST /v1/video-captions
GET  /v1/video-captions/:id
```

## 캡션 Job 만들기

필수: `video_url`. 선택: `style`, `font`, `language`, `script_text`,
`words`, `cues` / `segments`(작성한 오버레이, 음성 인식 없음), 그리고
평소의 `mode` / `webhook_url` / `wait_timeout_seconds` 통신 필드입니다.

음성 정렬 자막(`script_text`, 또는 생략 시 STT)은 들리는 음성이 필요합니다.
무음 클립은 `caption_no_speech`(`next_action: use_overlay_captions`)로
끝나며, 일반 정책 거절이 아닙니다. ASR 없이 문구를 새기려면 `cues`(또는
`segments`)에 `text` + `start` + `end`를 보내세요.

<!-- api-call-example:video-caption-create -->

### 스타일, 폰트, 언어

| 필드 | 값 / 기본값 |
|---|---|
| `style` | 생략하면 문구가 정합니다 — 라틴은 `slam`, 한국어는 `black-outline`. 직접 지정할 수도 있습니다: `slam`, `punch`, `tiktok-green`, `korean-ad`(한국어 음성용 캡컷 스타일 한글 카라오케: 한 번에 짧은 구절 하나, 하단 배치, 발화 중인 어절만 굵게 강조 — `language: "ko"`와 함께 사용, 한국어 `script_text`(멘트) 지원), 그리고 아래 한글 아이덴티티 |
| `font` | 선택한 스타일에 쓸 한글 서체입니다. 생략하면 그 스타일의 기본 서체를 씁니다. 한글 스타일에서만 유효합니다 — [폰트](#폰트) 참고. |
| `design` | 선택 사항입니다. 스타일의 색·타이포·배치·구절 나누기·모션을 요청 단위로 덮어씁니다 — [디자인 오버라이드](#디자인-오버라이드) 참고. |
| `language` | 음성 인식 힌트입니다(`ko`, `en` 등). 자동 감지하려면 생략하세요. |

`style`이 룩과 모션을 정하고 `design`이 그 값을 고치며, `font`는 그릴 서체를,
`language`는 음성 인식에게 어떤 언어를 기대할지 알려줄 뿐입니다. **`language`가
스타일이나 폰트를 대신 고르지 않습니다.** 다만 `style`을 생략하면 문구를 따라
갑니다 — 한국어 문구는 라틴 기본값으로 두부를 굽는 대신 `black-outline`으로
정해집니다. 직접 지정한 스타일은 지정한 그대로 렌더됩니다.

### 디자인 오버라이드

스타일은 디자인 토큰의 묶음이고, `design`은 그 토큰을 요청 하나에 대해
덮어씁니다. 모든 필드는 선택 사항이며 스타일의 값 위에 필드 단위로 병합되므로,
키 하나가 딱 하나만 바꿉니다.

```json
{
  "video_url": "https://example.com/clean.mp4",
  "style": "black-outline",
  "design": { "colors": { "active": "#22D3EE" } }
}
```

위 요청은 `black-outline`의 강조색만 청록으로 바꿔 굽습니다.

| 그룹 | 필드 |
|---|---|
| `colors` | `base`, `active`, `stroke`, `accent`, `accent_deep`, `card`(`null`이면 카드 없음) |
| `typography` | `base_weight`, `active_weight`, `active_scale`, `font_size_ratio`, `safe_width_ratio`, `stroke_width_px` |
| `placement` | `anchor_ratio`, `landscape_anchor_ratio` — 자막 줄 중심의 화면 높이 비율 |
| `phrasing` | `max_words`, `max_chars`, `pause_seconds` |
| `motion` | `enter_seconds`, `exit_seconds`, `emphasis_in_seconds`, `emphasis_out_seconds` |

색은 hex, `rgb()`/`rgba()`, `transparent`만 받습니다. 다른 CSS 문법은 렌더
문서에 그려지는 대신 거부됩니다. 문서에 적힌 범위를 벗어난 숫자도 `400`이라,
잘못된 룩이 렌더되고 과금되는 대신 요청 시점에 실패합니다. `design`은 아직
이 토큰을 읽지 않는 경로로 렌더되는 `punch`와 `tiktok-green`에서는 거부됩니다.

### 한글 문구를 라틴 스타일로 보내면 거부됩니다

`slam`, `punch`, `tiktok-green`은 한글 글립이 없는 라틴 디스플레이 서체로
그립니다. 한국어 문구를 이 스타일로 보내면 스타일을 몰래 바꾸는 대신 `400`
(`caption_hangul_text_latin_style`)으로 거부합니다. 고르지 않은 자막이 오류보다
낫지 않고, 두부(tofu)로 가득 찬 영상도 값은 똑같이 나가기 때문입니다. 라틴
문구의 `slam`은 그대로입니다.

`font`도 같습니다. 아래 서체는 모두 한글 서체이므로 라틴 스타일과 함께 보내면
`400`(`caption_font_requires_hangul_style`)입니다.

### 한글 자막 아이덴티티

말하는 영상(토킹 헤드, UGC, 크리에이터 보이스오버)의 **한국어 음성**에는
`slam` 대신 아래 스타일을 쓰세요. `slam`이 쓰는 라틴 디스플레이 서체에는 한글
글립이 없어 두부(tofu)로 렌더링됩니다. 아래 스타일은 단어를 하나씩 던지지 않고
어절을 구절 카드로 묶으며, 대소문자 변환 없이 원문 그대로 새깁니다.

| 스타일 | 느낌 |
|---|---|
| `black-outline` | CapCut 스타일 흰 글자 + 두꺼운 검정 외곽선, 화면 중앙 부근. 무난한 기본값입니다. |
| `weight-shift` | 구절 카드에서 지금 말하는 단어만 굵어지고 나머지는 뒤로 물러납니다. |
| `highlight` | 말하는 단어 뒤로 포인트 색 블록이 쓸고 지나갑니다. |
| `pill-karaoke` | 어두운 알약 모양 배경 위에서 색이 음성을 따라갑니다. |
| `clip-wipe` | 단어가 왼쪽에서 오른쪽으로 닦이듯 나타납니다. 작은 화면에서 가장 또렷합니다. |
| `editorial-emphasis` | 왼쪽 정렬 두 줄 카드. 앞 어절은 작게 두고 구절 끝 어절이 두 배 가까운 크기의 디스플레이 서체로 아래 줄에 왼쪽에서 밀려 들어옵니다. |

`korean-ad`는 광고형 카라오케 룩입니다(weight-shift에 발화 어절 강조색). `style`을
생략했을 때 정해지는 값은 `korean-ad`가 **아니라** `black-outline`이므로, 광고형
룩이 필요할 때 `korean-ad`를 직접 지정하세요.

`style`을 생략하면 강조색도 함께 빠집니다. 두 기본 스타일 모두 발화 어절을
금색으로 물들이도록 작성돼 있지만, 아무도 요청하지 않은 룩이 강조색을 들고 오면
안 되므로 생략한 요청은 발화 어절도 글자색을 그대로 유지합니다. `black-outline`
(또는 `slam`)을 직접 지정하면 그 스타일 고유의 금색 강조가 그대로 남고, 어느
쪽이든 `design.colors.active`로 강조색을 지정할 수 있습니다.

### 폰트

선택 사항입니다. `font`를 생략하면 스타일의 기본 서체를 씁니다 — `korean-ad`,
`weight-shift`, `highlight`, `pill-karaoke`, `editorial-emphasis`는 Pretendard,
`black-outline`과 `clip-wipe`는 Do Hyeon입니다. 지정하면 스타일은 그대로 두고
서체만 바뀝니다.

`editorial-emphasis`의 강조 줄은 `font`와 무관하게 검은고딕으로 그립니다. 이
아이덴티티의 룩은 두 서체의 대비 그 자체이기 때문입니다. `font`는 다른
스타일에서 한 줄을 바꾸듯, 여기서는 앞 줄만 바꿉니다.

| `font` | 서체 | 느낌 |
|---|---|---|
| `pretendard` | Pretendard Variable | 깔끔한 기본 |
| `do-hyeon` | 도현 | 두툼한 라운드, 캡컷 클래식 |
| `black-han-sans` | 검은고딕 | 임팩트 |
| `jua` | 주아 | 부드럽고 귀여운 라운드 |
| `dunggeunmo` | 둥근모 | 픽셀 / 레트로 |
| `bagel-fat-one` | Bagel Fat One | 두툼한 라운드 |
| `dongle` | Dongle Bold | 장난기 있는 라운드 디스플레이 |
| `gasoek-one` | Gasoek One | 초굵은 임팩트 |
| `yeon-sung` | 배민 연성 | 붓글씨 느낌 |
| `single-day` | Single Day | 부드러운 손글씨 |
| `hi-melody` | Hi Melody | 부드럽고 귀여운 라운드 |
| `nanum-pen` | 나눔손글씨 펜 | 손글씨 |
| `gowun-dodum` | 고운돋움 | 부드러운 에디토리얼 |

일곱 서체 모두 SIL Open Font License 1.1이며 렌더러에 함께 들어 있습니다. 목록에
없는 이름은 다른 서체로 바꿔치기하지 않고 거부하므로, 요청하지 않은 서체로
자막이 나가는 일은 없습니다.

`weight-shift`와 `korean-ad`는 `wght` 축을 애니메이션하는데, 이 축은
Pretendard만 가지고 있습니다. 고정 굵기 서체에서는 색과 크기 강조는 그대로이고
굵기 변화만 사라집니다.

### 음성 인식을 두 번 돌리지 않고 스타일만 바꾸기

같은 영상을 다른 스타일로 다시 구우려면 `video_url` 대신 `source_caption_id`를
보내세요.

```json
{ "source_caption_id": "…", "style": "black-outline" }
```

해당 자막의 원본 영상과 이미 확보한 단어 타이밍을 재사용하므로 음성 인식이 다시
돌지 않습니다. 문구를 고칠 때만 `words`를 함께 보내세요. 과금은 동일합니다 —
스타일 변경도 렌더링 한 번입니다.

`video_url`과 함께 `words`(단어 단위) 또는 `cues` / `segments`(구절 단위
오버레이 카드)를 `text`, `start`, `end`(초)로 보낼 수도 있습니다. 둘 다 음성
인식을 건너뛰고 보낸 문구를 보낸 시각에 새깁니다 — 무음 클립용 경로입니다.
`script_text`, `words`, `cues`, `segments`는 함께 쓸 수 없습니다.

### 선택 필드 `script_text`

이 값을 주면 Sume는 음성 인식의 단어 타이밍을 타이밍 원본으로 유지하면서 화면에
새길 문구를 스크립트에 맞춥니다. 정렬은 다음과 같은 타입이 정해진 공개 Job
오류로 실패할 수 있습니다.

- `script_alignment_mismatch`
- `script_alignment_failed`

권장하는 다음 동작은 `simplify_script_text_or_omit`입니다. 음성 인식 문구를
그대로 새기려면 `script_text`를 생략하세요.

```bash
curl -X POST https://api.sume.com/v1/video-captions \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-caption-script-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/example/clean.mp4",
    "style": "punch",
    "script_text": "Say hello to the Sume developer platform."
  }'
```

## 가격 참고

접수된 독립 캡션 Job마다 현재 고정 추정 기준으로 60초 이하 비디오에 대해 Sume
사용량 **0.20 USD**가 예약되고 확정됩니다. 실제 가격은 `GET /v1/catalog`와
OpenAPI에서 확인하세요.

인라인 Avatar Video 캡션은 아바타 비디오 추정치에 붙는 별도 부가 항목이며
`video_caption` 리소스를 만들지 **않습니다**.

## 폴링하고 읽기

```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"

curl https://api.sume.com/v1/video-captions/vc_123 \
  -H "Authorization: Bearer $SUME_API_KEY"
```

리소스는 준비되면 공개 가능한 상태, 스타일, 캡션이 입혀진 `video_url`과 산출물을
반환합니다. 원본 트랜스크립트, 렌더러 내부 정보, 서명된 소스 URL은 공개 계약에
포함되지 않습니다.

## 제약

- `video_url`은 가져올 수 있는 공개 HTTPS 비디오 URL이어야 합니다.
- localhost, 사설 네트워크, HTTPS가 아닌 URL, 서명된·비공개 URL, 프로바이더 작업
  URL은 거부됩니다.
- 원본 큐 목록, SRT 업로드, 프로바이더 작업 id는 지원하지 않습니다.

## 관련 문서

- [아바타 비디오 생성](/models/avatar-videos) (인라인 캡션)
- [아바타 비디오 프리뷰](/models/avatar-video-previews)
- [미디어 입력](/workflows/asset-library)
- [Job과 결과](/workflows/jobs-and-results)