영상 자막 번역 API: 영어 자막을 한국어 자막으로

Sume API로 영어 영상의 자막을 한국어로 번역하려면, 음성 인식으로 타이밍이 있는 영어 문장을 받아 문장마다 번역한 다음, 한국어 줄을 타이밍이 있는 cues로 담아 black-outline 같은 한글 스타일과 함께 POST /v1/video-captions에 보내세요. cue를 보내면 음성 인식을 건너뛰므로, 각 한국어 줄이 지정한 시각에 정확히 그대로 새겨집니다.

아래 내용은 2026-09-27에 확인한 영상 검사, 영상 캡션, Agent Completions 문서와 Sume API 레퍼런스의 STT 1.0 및 자막 스키마를 바탕으로 합니다. 한국어 음성에 자막을 다는 일은 다른 작업이며, 한국어 자막 API에서 다룹니다.

파이프라인은 어떤 호출로 이루어지나요?

세 단계입니다. 첫 단계와 마지막 단계는 정해진 Sume 호출이고, 가운데 단계에는 어떤 번역 도구든 쓸 수 있습니다.

타이밍이 있는 영어 문장은 어떻게 받나요?

음성 인식 힌트인 language_code: "en"과 segmentation: { "mode": "sentence" }를 함께 보내세요. 두 전사 호출 모두 이 조합을 받아, 자막 줄 형태의 갭 없는 문장 segments[]를 반환합니다. 검사 요청 전체와 전사문 필드는 자막 자동 생성에서 볼 수 있습니다.

• 영어 영상이 이전 Sume Job의 출력물처럼 이미 워크스페이스에 있는 media.sume.com 클립이라면 영상 검사를 쓰세요. 오디오 트랙이 없는 클립은 inspect_source_has_no_audio로 실패합니다.
• 오디오가 공개 HTTPS audio_url에 있다면 STT 1.0을 쓰세요. 스키마는 Sume 미디어 URL을 권장합니다. duration_seconds(1–600)가 예약 크기를 정하며, 생략하면 일 분을 예약합니다.

타이밍을 잃지 않고 줄을 번역하려면 어떻게 하나요?

번역 도구에는 문장 텍스트만 보내고, 각 구간의 start와 end는 같은 순서 그대로 직접 작성한 코드에 보관하세요. 한국어 줄을 하나씩 원래 구간과 짝짓고, 자막을 입히기 전에 개수가 맞는지 확인하세요.

파이프라인 전체를 Sume 안에서 처리하려면 Agent Completions로 Sume 에이전트에게 요청하세요. 영어 줄은 input에 넣으세요. 에이전트는 input을 지시가 아니라 데이터로만 다룹니다. output_schema는 lines 배열에 바인딩하고, 기본값이 없는 generation_spend_cap_usd를 설정하세요. 호출은 실행 영수증과 함께 202로 응답하며, output에 줄이 담길 때까지 실행을 폴링하면 됩니다.

• 키에는 agent_completions:write가 필요합니다. Agent Completions 출시 전에 만든 키에는 이 스코프가 없어서 403 insufficient_scope를 받습니다.
• 상한은 0보다 커야 하며, 실행의 생성 지출을 기준으로 적용됩니다. 에이전트 자체의 LLM 턴은 이 상한 밖에서 과금되므로, 상한이 곧 실행의 총비용은 아닙니다.

curl -sS -X POST https://api.sume.com/v1/agent/completions \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: subtitles-ko-001" \
  -d '{
    "instruction": "Translate each English line in the input into Korean subtitles. Keep the order and the count.",
    "input": { "lines": ["Today we are introducing the new dashboard.", "Setup takes one minute."] },
    "output_schema": {
      "name": "acme/subtitles-ko/v1",
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": ["lines"],
        "properties": { "lines": { "type": "array", "items": { "type": "string" } } }
      }
    },
    "generation_spend_cap_usd": 1
  }'

한국어 줄은 영상에 어떻게 입히나요?

영상의 공개 HTTPS URL을 video_url로 보내고, 줄마다 cue를 하나씩 보내세요. cue에는 text와 초 단위의 start, end가 들어갑니다. Sume는 영어 오디오를 다시 전사하지 않고, 보낸 문구를 보낸 시각에 정확히 그대로 새깁니다. 긴 한국어 줄은 text에 줄바꿈을 넣어 두 줄 카드로 만들 수 있습니다. cues는 words, segments, script_text와 함께 쓸 수 없습니다.

한국어 자막 API에서 설명하듯 black-outline 같은 한글 스타일을 직접 지정하세요. 라틴 스타일은 한국어 문구를 거부하며, 현재 코드에서는 style을 생략하면 모든 cue의 글자를 합쳐서 스타일을 정하므로, 영어 이름이 많은 번역문은 라틴 스타일인 slam으로 정해질 수 있습니다.

curl -X POST https://api.sume.com/v1/video-captions \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: captions-ko-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4",
    "style": "black-outline",
    "cues": [
      { "text": "오늘은 새 대시보드를 소개합니다.", "start": 0, "end": 3.2 },
      { "text": "설정은 1분이면 끝납니다.", "start": 3.2, "end": 6.0 }
    ]
  }'

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

제한은 대부분 자막 단계에서 정해집니다.

• cue의 start와 end는 0초부터 60초까지이며, 현재 자막 워커는 60초보다 긴 원본 영상을 duration_out_of_range로 거부합니다. 더 긴 영상은 긴 영상을 짧은 클립으로 나누기처럼 먼저 자르세요.
• Job 하나는 cue를 1–200개 받으며, 각 cue의 text는 1–400자입니다.
• SRT 업로드는 지원하지 않습니다. 줄은 cues로 보내세요.
• video_url은 가져올 수 있는 공개 HTTPS 영상이어야 합니다. localhost, 사설 네트워크, HTTPS가 아닌 URL, 서명된 URL이나 비공개 URL은 거부됩니다.
• 전사는 API 요금에 나온 STT 1.0 요율인 오디오 분당 $0.01로 과금되며, 기본적으로 5.5% 에이전트 수수료가 더해집니다. 검사의 프로브는 과금되지 않습니다. 자막 Job은 60초 이하 영상에 대해 영상 캡션 페이지에 나온 고정 금액을 Job마다 예약하며, 여기에도 같은 수수료가 더해집니다.