대본으로 영상에 자막을 넣는 방법

대본으로 영상에 자막을 넣으려면 텍스트의 줄마다 시각이 있어야 합니다. 그 줄이 말해지는 순간에 나타나야 하기 때문입니다. Sume에서는 이 시각을 직접 정하지 않습니다. 대본을 script_text로 담아 영상 URL과 함께 POST /v1/video-captions로 보내세요. Sume는 각 단어가 언제 발화되는지 찾는 데만 음성 인식을 쓰고, 그 시각에 보낸 문구를 입혀 새 자막 영상으로 반환합니다.

Sume 관련 내용은 2026-09-27에 확인한 영상 캡션 문서와 Sume API 레퍼런스의 자막 스키마에서 가져왔습니다. 전사문을 먼저 받아 고친 뒤 입히려면 자막 자동 생성 후 편집하기를 참고하세요.

대본은 어떻게 보내나요?

대본 전체를 script_text에 최대 8,000자까지 넣고, 영상의 공개 HTTPS URL은 video_url에 넣으세요. language는 en이나 ko 같은 선택 사항인 음성 인식 힌트이며, 생략하면 언어를 자동으로 감지합니다. 이 값이 스타일이나 폰트를 고르는 일은 없습니다.

curl -X POST https://api.sume.com/v1/video-captions \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: transcript-captions-001" \
  -d '{
    "video_url": "https://example.com/interview.mp4",
    "language": "en",
    "script_text": "Thanks for joining us. Today we look at three ways to cut costs."
  }'

대본은 어떻게 준비해야 하나요?

타이밍은 음성에서, 문구는 보낸 텍스트에서 오므로 텍스트는 실제로 말한 내용이어야 합니다.

• 발화된 단어만 순서대로 남기세요. 화자 이름표, 타임스탬프, [음악] 같은 메모에는 맞춰 정렬할 음성이 없습니다.
• 이름과 철자는 텍스트에서 고치세요. 음성 인식의 단어 타이밍이 계속 타이밍 기준이 되고, 입히는 문구는 스크립트에 맞춰 정렬됩니다.
• style을 생략하면 문구가 스타일을 정합니다. 라틴 문구는 slam, 한국어 문구는 black-outline입니다. 한국어 텍스트를 slam, punch, tiktok-green으로 보내면 400 caption_hangul_text_latin_style로 거부됩니다.
• script_text는 words, cues, segments와 함께 쓸 수 없습니다.

대본이 오디오와 맞지 않으면 어떻게 되나요?

Job이 실패합니다. 독립 실행형 자막 API는 다른 문구로 대신 입히지 않습니다. 정렬 오류는 타입이 정해진 script_alignment_mismatch 또는 script_alignment_failed이며, 권장하는 다음 동작은 simplify_script_text_or_omit입니다. 텍스트를 줄이거나 고치세요. 아니면 script_text를 생략해 음성 인식 문구를 대신 입히세요. 들리는 음성이 없는 클립은 next_action: use_overlay_captions와 함께 caption_no_speech로 실패합니다.

텍스트가 번역문이거나 대응하는 발화가 아예 없다면 정렬을 건너뛰고, 영상 자막 번역 API에서처럼 시각을 정한 cues를 대신 보내세요.

어떤 제한이 있고, 비용은 얼마인가요?

• video_url은 가져올 수 있는 공개 HTTPS 영상이어야 합니다. localhost, 사설 네트워크, HTTPS가 아닌 URL, 서명되었거나 비공개인 URL은 거부됩니다.
• 현재 자막 워커는 60초보다 긴 원본(duration_out_of_range)이나 오디오 스트림이 없는 원본을 거부합니다. 더 긴 영상은 긴 영상에 자막 넣기를 참고하세요.
• 결과는 자막 파일이 아니라 자막을 입힌 영상입니다. 자막 리소스는 자막을 입힌 video_url을 반환하며, 원본 전사문은 그 공개 계약에 포함되지 않습니다. 별도 자막 파일이 필요하면 음성 인식 타이밍으로 직접 만드세요.
• 접수된 자막 Job마다 60초 이하 영상에 대해 영상 캡션 페이지에 나온 고정 금액이 예약되고 확정됩니다. 최신 가격은 GET /v1/catalog에서 확인하세요.