SRT 자막 파일을 영상에 입히는 방법

SRT 파일을 영상에 입히려면 자막 블록마다 두 타임코드 사이의 프레임에 텍스트를 그려 넣으세요. 그러면 텍스트가 화면의 일부가 되어 어떤 플레이어에서든 보입니다. Sume 자막 API가 이 작업을 하지만 .srt 파일 자체는 받지 않습니다. 블록마다 text와 초 단위의 start, end가 담긴 cue로 바꾼 다음, cue를 영상 URL과 함께 POST /v1/video-captions로 보내세요. cue를 보내면 음성 인식을 건너뛰므로, Sume는 보낸 줄을 보낸 시각에 정확히 그대로 입힙니다.

Sume 관련 내용은 2026-09-27에 확인한 영상 캡션 문서와 Sume API 레퍼런스의 자막 스키마에서 가져왔으며, 현재 코드라고 밝힌 내용은 Sume의 코드에서 확인했습니다. 애초에 자막을 입힐지 말지는 하드 자막과 소프트 자막의 차이에서 다룹니다.

SRT 블록은 어떻게 cue로 바꾸나요?

SRT 블록은 일련번호, 00:00:01,000 --> 00:00:03,500 같은 타이밍 줄, 그리고 한 줄 이상의 텍스트로 이루어집니다. 블록 하나는 다음과 같이 cue 하나가 됩니다.

• 일련번호는 버리세요. cue는 text, start, end만 받습니다.
• 두 타임코드를 모두 초로 바꾸세요. 시간 × 3600에 분 × 60과 초를 더하고, 쉼표 뒤의 밀리초는 소수로 붙입니다. 00:00:03,500은 3.5가 됩니다.
• 블록의 텍스트 줄은 줄바꿈으로 이으세요. 문서에 따르면 두 줄 카드를 만들 때 cue 텍스트에 줄바꿈을 하나 넣을 수 있습니다. 현재 코드에서 라틴 문구의 기본 스타일인 slam은 줄바꿈을 무시하고 단어를 대문자로 그립니다.
• <i> 같은 SRT 서식 태그는 지우세요. 문서는 cue 텍스트에 쓸 마크업을 정의하지 않습니다.

import re

TIME = r"(\d+):(\d\d):(\d\d)[,.](\d{3})"

def seconds(h, m, s, ms):
    return int(h) * 3600 + int(m) * 60 + int(s) + int(ms) / 1000

def srt_to_cues(srt_text):
    cues = []
    for block in re.split(r"\n\s*\n", srt_text.strip()):
        lines = block.strip().splitlines()
        timing = next(i for i, line in enumerate(lines) if "-->" in line)
        start, end = re.findall(TIME, lines[timing])[:2]
        text = re.sub(r"<[^>]+>", "", "\n".join(lines[timing + 1 :])).strip()
        cues.append({"text": text, "start": seconds(*start), "end": seconds(*end)})
    return cues

cue는 Sume에 어떻게 보내나요?

영상의 공개 HTTPS URL은 video_url로, 목록은 cues로 보내세요(segments는 별칭입니다). cues는 words, segments, script_text와 함께 쓸 수 없습니다. Idempotency-Key도 추가하세요. 요청이 타임아웃되어 같은 키와 같은 본문으로 다시 보내면, 두 번째 Job이 생기지 않고 원래 Job이 돌아옵니다.

style을 생략하면 문구가 스타일을 정합니다. 라틴 문구는 slam, 한국어 문구는 black-outline입니다. 직접 지정한 스타일은 지정한 그대로 렌더링되지만, 한국어 줄을 slam, punch, tiktok-green으로 보내면 400 caption_hangul_text_latin_style로 거부됩니다. 자막 줄을 위아래로 옮기려면 영상에 입히는 자막 커스터마이즈를 참고하세요.

한국어 줄에는 "design": { "phrasing": { "max_words": 1 } }를 추가하세요. 현재 코드에서 black-outline을 비롯한 한글 구절 카드 스타일은 간격이 0.45초 이하인 짧은 cue들을 최대 22자짜리 카드 하나로 합치므로, 줄이 자기 start보다 먼저 나타날 수 있습니다. 상한을 하나로 두면 cue마다 카드가 따로 생깁니다.

curl -X POST https://api.sume.com/v1/video-captions \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: srt-burn-001" \
  -d '{
    "video_url": "https://example.com/clip.mp4",
    "cues": [
      { "text": "Welcome to the tour.", "start": 1.0, "end": 3.5 },
      { "text": "Setup takes one minute.", "start": 3.5, "end": 6.2 }
    ]
  }'

어떤 제한이 있나요?

보내기 전에 파일이 다음 제한에 맞는지 확인하세요. 이보다 긴 자막 파일은 Job 하나에 들어가지 않습니다.

영상이 60초보다 길면 어떻게 하나요?

영상을 나누세요. 60초 이하의 조각으로 자르되, SRT 블록 안이 아니라 블록과 블록 사이에서 자르세요. 조각마다 그 조각에 들어가는 cue를 넘기면서 모든 start와 end에서 조각의 시작 시각을 빼고, 자막을 입힌 조각들은 다시 이어 붙이세요. 자르고 다시 잇는 과정은 긴 영상에 자막 넣기에서 단계별로 설명합니다. Sume의 자르기·잇기 도구는 이전 Sume Job의 출력물처럼 이미 워크스페이스의 media.sume.com에 있는 영상만 읽습니다.

결과는 어떻게 받고, 비용은 얼마인가요?

종료 상태가 될 때까지 GET /v1/jobs/:id/status를 폴링한 다음, GET /v1/video-captions/:id에서 자막을 입힌 video_url을 읽으세요. 접수된 독립 실행형 자막 Job마다 60초 이하 영상에 대해 영상 캡션 페이지에 나온 고정 금액이 예약되고 확정됩니다. 문서는 최신 가격을 GET /v1/catalog에서 확인하라고 안내합니다. 제출 응답은 Job의 금액을 usage.billable_amount_usd로 알려 줍니다.