비디오 캡션

이 문서는 영문 원고를 AI로 번역한 내용이라 표현이 어색할 수 있습니다.

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

캡션 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를 보내세요.

Create a video caption job

POST /v1/video-captions

Required

Video URL

스타일, 폰트, 언어

필드	값 / 기본값
`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은 그 토큰을 요청 하나에 대해 덮어씁니다. 모든 필드는 선택 사항이며 스타일의 값 위에 필드 단위로 병합되므로, 키 하나가 딱 하나만 바꿉니다.

위 요청은 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를 보내세요.

해당 자막의 원본 영상과 이미 확보한 단어 타이밍을 재사용하므로 음성 인식이 다시 돌지 않습니다. 문구를 고칠 때만 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를 생략하세요.

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