Sume API로 영상에 자막을 입히는 방법

Sume로 영상에 자막을 입히려면 클립의 공개 HTTPS URL을 POST /v1/video-captions로 보내세요. Sume는 음성 인식 또는 직접 넣은 단어·구절 타이밍에 맞춰, 지정한 스타일이나 문구에 따라 고른 스타일로 자막을 입힌 영상을 Job 기반으로 반환합니다.

아래 내용은 모두 2026-09-25에 확인한 영상 캡션 문서를 기준으로 합니다.

자막 Job은 어떻게 만드나요?

이미 완성된 클립이 있다면 독립 실행형 자막 API를 쓰세요. video_url은 필수입니다. 선택 필드는 style, font, design, language, script_text, words, cues / segments이고, 여기에 평소의 통신 필드인 mode, webhook_url, wait_timeout_seconds가 더해집니다. Job은 GET /v1/video-captions/:id로 다시 조회합니다.

다음 요청은 punch 스타일로 자막을 입히고, 화면에 새기는 문구를 스크립트에 맞춥니다.

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."
  }'

어떤 자막 스타일을 골라야 하나요?

style은 룩과 모션을 정하고, design은 그 값을 고치며, font는 서체를 고르고, language(ko, en, …)는 음성 인식에 어떤 언어를 기대할지 알려 줄 뿐입니다. language가 스타일이나 폰트를 고르는 일은 없습니다. style을 생략하면 문구가 스타일을 정하며, 라틴 문구는 slam, 한국어 문구는 black-outline이 됩니다. 직접 지정한 스타일은 지정한 그대로 렌더링됩니다.

design은 요청 하나에 한해 스타일의 colors, typography, placement, phrasing, motion 토큰을 덮어씁니다. 색은 hex, rgb()/rgba(), transparent 중 하나로 지정하고, 문서에 적힌 범위를 벗어난 숫자는 400을 반환합니다. 그래서 잘못된 룩은 렌더링되고 과금되는 대신 요청 시점에 실패합니다. font는 한글 스타일에서만 서체를 바꾸며, pretendard, do-hyeon, noto-sans-kr 같은 SIL Open Font License 1.1 서체로 이루어진 고정 목록에서 고릅니다. 목록에 없는 이름은 다른 서체로 대체되지 않고 거부됩니다.

무음 클립에 자막을 넣거나 직접 쓴 문구를 입히려면 어떻게 하나요?

음성에 맞춘 자막은 script_text로 만들든, script_text를 생략해 음성 인식으로 만들든 들리는 음성이 있어야 합니다. 무음 클립은 일반적인 정책 거부가 아니라 next_action: use_overlay_captions가 붙은 caption_no_speech로 실패합니다.

문구를 정하는 필드는 네 개이며, 서로 함께 쓸 수 없습니다.

• cues 또는 segments: 구절 단위 오버레이 카드이며, 카드마다 text, start, end(초)가 있습니다. 음성 인식을 건너뛰므로 무음 클립에는 이 방법을 씁니다.
• words: 단어 단위의 text, start, end입니다. 이 역시 음성 인식을 건너뜁니다.
• script_text: 음성 인식의 단어 타이밍이 계속 타이밍 기준이 되고, 화면에 새기는 문구는 스크립트에 맞춰 정렬됩니다. 정렬은 script_alignment_mismatch 또는 script_alignment_failed로 실패할 수 있으며, 권장하는 다음 동작은 simplify_script_text_or_omit입니다.

다시 전사하지 않고 자막 영상의 스타일을 바꿀 수 있나요?

네. video_url 대신 source_caption_id를 새 스타일과 함께 보내세요: { "source_caption_id": "…", "style": "black-outline" }. Sume는 그 자막의 원본 영상과 이미 확보한 단어 타이밍을 재사용하므로 음성 인식을 다시 실행하지 않습니다. 문구를 고칠 때만 words를 함께 보내세요.

과금은 달라지지 않습니다. 스타일을 바꾸는 것도 렌더링이기 때문입니다.

자막 영상은 어떻게 받고, 비용은 얼마인가요?

GET /v1/jobs/:id/status와 GET /v1/jobs/:id/result를 폴링하거나 GET /v1/video-captions/:id를 조회하세요. 준비가 끝나면 리소스는 공개 가능한 상태, 스타일, 자막을 입힌 video_url과 산출물을 반환합니다. 원본 전사문, 렌더러 내부 정보, 서명된 소스 URL은 공개 계약에 포함되지 않습니다.

접수된 독립 실행형 자막 Job마다 현재의 고정 추정 기준으로 60초 이하 영상에 대해 정해진 금액의 Sume 사용량이 예약되고 확정됩니다. 금액은 API 요금에 있으며, 문서는 최신 가격을 GET /v1/catalog에서 확인하라고 안내합니다. 지갑의 동작 방식은 Sume 요금제는 어떻게 동작하나요에서 설명합니다.

말하는 아바타 영상의 인라인 captions는 아바타 영상 추정치에 붙는 별도 부가 항목이며, video_caption 리소스를 만들지 않습니다.

자막 API가 거부하거나 지원하지 않는 것은 무엇인가요?

• 가져올 수 있는 공개 HTTPS 영상 URL이 아닌 video_url. localhost, 사설 네트워크, HTTPS가 아닌 URL, 서명되었거나 비공개인 URL, 프로바이더 작업 URL은 거부됩니다.
• SRT 업로드와 프로바이더 작업 ID. 구절 단위 문구는 대신 cues나 segments로 보내세요.
• slam, punch, tiktok-green에 보낸 한국어 문구: 400(caption_hangul_text_latin_style). 라틴 문구를 slam으로 보내는 경우는 달라지지 않습니다.
• 라틴 스타일과 함께 지정한 한글 font: 400(caption_font_requires_hangul_style).
• hex, rgb()/rgba(), transparent가 아닌 CSS 문법으로 쓴 design 색, 그리고 문서에 적힌 범위를 벗어난 design 숫자.