자막 자동 생성 API: 전사하고 문구를 고친 뒤 입히기

입히기 전에 확인할 수 있는 자막을 자동으로 만들려면 transcribe: true를 넣은 POST /v1/video-inspect로 클립을 전사하고, 돌려받은 텍스트를 고친 다음, 그 텍스트를 script_text로 담아 POST /v1/video-captions에 보내세요. Sume는 음성 인식의 단어 타이밍을 그대로 두고, 고친 문구를 그 타이밍에 맞춰 정렬합니다.

각 단계는 2026-09-26에 확인한 Sume의 영상 검사 문서와 영상 캡션 문서, 그리고 API 레퍼런스 스키마를 따릅니다. 검토 단계가 필요 없다면 영상에 자막을 입히는 방법에서처럼, 문구 없이 보낸 자막 Job이 호출 한 번으로 전사하고 자막을 입힙니다.

편집할 수 있는 전사문은 어떻게 받나요?

검사는 이전 Sume Job의 출력물처럼 이미 워크스페이스에 있는 media.sume.com 아티팩트나 에셋인 클립 하나를 읽습니다. 공개 인터넷에서 가져오는 기능은 없습니다. Idempotency-Key는 필수입니다. frames: false는 스틸을 건너뛰고, language_code(예: en, ko)는 선택 힌트이며, segmentation.mode: "sentence"는 자막 줄 형태의 갭 없는 문장 구간을 추가합니다.

기본 mode는 sync입니다. 호출은 최대 30초 기다린 뒤 완료된 검사를 200으로 돌려주거나, 폴링할 큐 대기 Job을 202로 돌려줍니다. 리소스는 나중에 GET /v1/video-inspect/:id로 읽으세요.

curl -X POST https://api.sume.com/v1/video-inspect \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-inspect-transcript-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4",
    "frames": false,
    "transcribe": true,
    "segmentation": { "mode": "sentence" }
  }'

전사문에는 무엇이 들어 있나요?

준비가 끝나면 검사 리소스에 probe, warnings[], transcript 객체가 담깁니다. 편집하거나 재사용할 전사문 필드는 다음과 같습니다.

고친 텍스트는 어떻게 입히나요?

text에서 이름, 브랜드 용어, 오타를 고친 다음, 고친 텍스트 전체를 script_text(최대 8,000자)로, 같은 media.sume.com URL을 video_url로 보내세요. Sume는 음성 인식의 단어 타이밍을 타이밍 원본으로 유지하면서 화면에 새길 문구를 스크립트에 맞춥니다.

정렬은 타입이 정해진 Job 오류인 script_alignment_mismatch 또는 script_alignment_failed로 실패할 수 있으며, 권장하는 다음 동작은 simplify_script_text_or_omit입니다. 음성 인식 문구를 그대로 새기려면 script_text를 생략하세요. script_text, words, cues, segments는 함께 쓸 수 없습니다.

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-reviewed-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4",
    "script_text": "Welcome to the Acme onboarding tour. Today we set up your first project."
  }'

직접 정한 타이밍으로 입힐 수도 있나요?

네. words와 cues / segments는 음성 인식을 건너뛰고, 보낸 문구를 보낸 시각에 그대로 새깁니다. 그래서 실패할 정렬 단계가 없습니다.

• words: text, start, end(초)로 이루어진 항목 1–1,200개이며, 각 text는 최대 200자입니다. 검사의 words[]는 word 키를 쓰므로, 옮겨 올 때 이 키를 text로 바꾸세요.
• cues 또는 그 별칭인 segments: text, start, end가 있는 구절 단위 카드 1–200개이며, 각 text는 최대 400자입니다. text에 줄바꿈을 넣으면 두 줄 카드가 됩니다.
• cues의 각 항목은 text, start, end만 받습니다. 검사의 문장 segments[]를 cues로 재사용하려면 이 세 키만 남기고 index와 duration_seconds는 빼세요.

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

전사와 자막 입히기는 따로 과금되는 두 개의 Job이며, 상한도 각각 따로 있습니다.

• 검사의 프로브와 스틸은 과금되지 않습니다. 예약은 전사에만 걸리며, Sume STT 1.0 요율인 오디오 분당 $0.01(API 요금 기준)에 기본적으로 5.5% 에이전트 수수료가 더해집니다.
• duration_seconds가 없으면 전사는 1분을 예약하며, 이 힌트의 최댓값은 600초입니다. 검사할 수 있는 소스 길이는 최대 1,800초입니다.
• 오디오 트랙이 없는 클립은 검사에서 inspect_source_has_no_audio로 실패합니다. 무음 클립에 보낸 음성 정렬 자막 Job은 caption_no_speech로 실패합니다.
• 독립 실행형 자막 Job은 현재 고정 추정 기준으로 60초 이하 영상에 대해 영상 캡션 페이지에 나온 고정 금액으로 과금됩니다.
• 자막 리소스는 전사문이 아니라 자막을 입힌 video_url을 반환하며, 원본 전사문은 그 공개 계약에 포함되지 않습니다. 그래서 편집할 텍스트는 검사에서 받습니다.
• SRT 업로드는 지원하지 않습니다. 구절 단위 문구는 대신 cues나 segments로 보내세요.