API로 긴 영상에 자막 넣기: 나눠서 입히고 다시 잇기

Sume API로 60초보다 긴 영상에 자막을 넣으려면 POST /v1/video-trim으로 영상을 60초 미만의 조각으로 자르고, 조각마다 POST /v1/video-captions로 자막을 입힌 뒤, 자막을 입힌 조각들을 POST /v1/audio-detach로 분리한 원래 오디오 위에 POST /v1/timeline-1.0/render 한 번으로 다시 이어 붙이세요. 현재 코드에서는 자막 Job 하나가 60초보다 긴 소스를 거부합니다.

아래 단계는 2026-09-27에 확인한 Sume의 영상 캡션, 영상 트림, 오디오 분리, Timeline 1.0, 영상 검사 문서와 Sume API 레퍼런스의 자막 스키마를 바탕으로 합니다. 현재 동작이라고 설명한 내용은 Sume의 코드에서 확인한 것입니다. 60초 이하 클립 하나라면 영상에 자막을 입히는 방법을 참고하세요.

왜 자막 Job 하나로 영상 전체를 처리할 수 없나요?

세 가지 한도가 모두 60초에 걸려 있으므로, 더 긴 영상에는 조각마다 자막 Job이 하나씩 필요합니다.

• 자막 문서는 현재 고정 추정치에 따라 독립 실행형 Job의 가격을 60초 이하 영상 기준으로 매깁니다.
• API 레퍼런스는 모든 words와 cues의 시각 상한을 60초로 둡니다.
• 현재 자막 워커는 직접 words를 넘기더라도 60초보다 긴 소스를 duration_out_of_range로 거부합니다.

영상은 어디서 잘라야 하나요?

자막 줄 하나가 두 조각에 걸치지 않도록 문장 경계에서 자르고, 조각들이 영상 전체를 덮도록 틈 없이 자르세요. POST /v1/video-inspect에 transcribe: true와 segmentation: { "mode": "sentence" }를 넣어 한 번 전사하면, 초 단위 start와 end가 담긴 갭 없는 문장 segments[]를 받습니다. 온전한 문장들을 60초 미만의 조각으로 묶고, 첫 조각은 0에서 시작하고 마지막 조각은 영상 끝까지 이어지게 하세요. 전사 요청은 긴 영상을 짧은 클립으로 나누기에서 다룹니다.

• 영상은 앞서 실행한 Sume Job의 출력처럼 이미 워크스페이스의 media.sume.com에 있어야 합니다. 검사, 트림, 오디오 분리는 최대 1,800초 길이의 소스를 읽습니다.
• 전사문은 STT 1.0 요율인 오디오 분당 $0.01로 과금되며, 예약 크기를 정하는 duration_seconds 힌트는 최대 600초입니다. 프로브는 과금되지 않습니다.

조각마다 어떻게 자르고 자막을 입히나요?

각 조각은 POST /v1/video-trim(video_url, start, end)으로 자르고, 기본값 두 개를 그대로 두세요. 하나는 프레임 단위로 정확하게 재인코딩하는 precision: "exact"로, 이음매가 전사문이 가리킨 위치에 정확히 놓이게 합니다. 다른 하나는 audio: "keep"으로, 음성 인식 자막에는 음성이 필요하기 때문입니다. 결과의 video_url은 새 media.sume.com MP4입니다.

그 video_url을 공개 HTTPS 영상을 받는 POST /v1/video-captions로 보내세요. 문서의 예제도 media.sume.com URL을 씁니다. 이음매 앞뒤로 룩이 같도록 모든 조각에 같은 style을 지정하세요. 음성 인식을 한 번 더 돌리지 않으려면 조각의 단어를 words로 넘기세요. 이때 word를 text로 이름을 바꾸고, 각 시각에서 트림 결과의 actual_start_seconds를 빼세요.

curl -X POST https://api.sume.com/v1/video-captions \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: talk-captions-part-2" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk-part-2.mp4",
    "style": "slam",
    "words": [
      { "text": "Next,", "start": 0.5, "end": 0.9 },
      { "text": "open", "start": 0.9, "end": 1.2 }
    ]
  }'

자막을 입힌 조각은 어떻게 다시 이어 붙이나요?

POST /v1/audio-detach로 원본 영상의 오디오를 분리하세요. 기본 출력은 Timeline의 audio.url이 기대하는 형식인, 샘플 단위로 정확한 wav이며, 결과에는 audio_url과 duration_seconds가 담깁니다. 검사 전사문의 audio_url은 쓰지 마세요. API 레퍼런스는 그 16 kHz 모노 파일을 타임라인 스파인이 아니라 음성 인식 입력이라고 설명합니다. 오디오 분리 한 번의 출력은 최대 900초이므로, 더 긴 소스는 range를 지정한 분리 두 번이 필요하며 그 결과를 audio.parts[]로 넘깁니다.

그다음 렌더링하세요. 각 자막 Job의 video_url(media.sume.com에 있는 자막 입힌 MP4)마다 video[] 슬롯을 하나씩 주고, 슬롯은 조각의 원래 start 위치에 두며, duration은 조각의 길이로, source_in은 0으로 지정하세요. 트림 문서도 트림한 MP4를 같은 방식으로 배치합니다. transition은 빼고, 기본 출력이 1080×1920이므로 output.width와 output.height를 소스 크기에 맞추세요. 현재 컴파일러에서 렌더의 소리는 스파인뿐이므로, 원래 트랙이 끊기지 않고 한 번만 재생됩니다. 먼저 과금되지 않는 POST /v1/timeline-1.0/plan으로 본문을 확인하세요.

curl -X POST https://api.sume.com/v1/timeline-1.0/render \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: talk-captioned-001" \
  -d '{
    "audio": { "url": "https://media.sume.com/artifacts/artf_demo/talk.wav", "duration_seconds": 150 },
    "output": { "width": 1920, "height": 1080 },
    "video": [
      { "source_url": "https://media.sume.com/artifacts/artf_demo/part-1-captioned.mp4", "start": 0, "duration": 58.4, "source_in": 0 },
      { "source_url": "https://media.sume.com/artifacts/artf_demo/part-2-captioned.mp4", "start": 58.4, "duration": 55.1, "source_in": 0 },
      { "source_url": "https://media.sume.com/artifacts/artf_demo/part-3-captioned.mp4", "start": 113.5, "duration": 36.5, "source_in": 0 }
    ]
  }'

비용은 얼마이고, 한도는 어떻게 되나요?

모든 단계는 각각 별도의 Job이며 따로 과금되고, 기본적으로 5.5% 에이전트 수수료가 더해집니다. 현재 코드에서는 트림, 자막, 오디오 분리, 렌더 Job이 각각 생성 동시성 슬롯을 하나씩 차지합니다. Generation admission 문서에 따르면 Free 요금제의 기본값은 처리 중인 Job 하나와 큐 대기 Job 다섯 개이며, 큐를 넘는 제출은 429 queue_full로 실패합니다. Sume 영상 Job 동시성과 큐를 참고하세요.