YouTube 챕터 생성기: 전사문으로 타임스탬프 만들기

YouTube 챕터 생성기는 영상의 전사문을 영상 설명란에 붙여 넣을 타임스탬프와 제목 목록으로 바꿔 줍니다. 목록은 00:00에서 시작합니다. 필요한 것은 두 가지로, 음성 인식에서 얻은 문장 타임스탬프와 주제가 바뀌는 지점을 정하는 언어 모델입니다. Sume에서는 STT 1.0이 타이밍이 있는 문장을 반환하고, Agent Completions가 직접 정의한 스키마에 맞춘 JSON으로 챕터를 반환합니다.

아래 YouTube 규칙은 YouTube 고객센터: Video Chapters에서 인용했습니다. Sume 단계는 STT 1.0에 관해서는 Sume API 레퍼런스를, 그 밖에는 Agent Completions와 구조화 출력 (영문) 문서를 따릅니다. 모두 2026-09-27에 확인했습니다.

YouTube 챕터에는 무엇이 필요한가요?

챕터는 설명란에 넣은 타임스탬프 목록에서 만들어집니다. YouTube가 자동 챕터를 추가할 수도 있지만, 도움말은 “not all videos are eligible for automatic chapters”(모든 영상이 자동 챕터 대상은 아님)라고 하고, 직접 추가한 목록에 대해서는 “will override automatic video chapters.”(자동 챕터보다 우선함)라고 설명합니다. 채널에 아직 챕터 기능이 없다면, YouTube는 Advanced features(고급 기능) 이용 권한을 신청하라고 안내합니다.

말한 내용에서 타임스탬프는 어떻게 얻나요?

오디오를 문장 구간과 함께 전사하세요. STT 1.0은 YouTube 링크가 아니라 공개 HTTPS 오디오 URL을 받으므로, 직접 가진 영상 파일에서 시작하세요. 영상의 오디오 트랙을 추출해 STT 1.0이 가져올 수 있는 곳에 호스팅하면 됩니다. 이미 Sume에 있는 영상이라면 transcribe: true와 같은 segmentation을 넣은 영상 검사가 그 단계 없이 문장 구간을 반환합니다.

• 각 구간에는 index, text, start, end, duration_seconds가 담기며, 시간은 오디오 시작부터의 초 단위입니다.
• 요청 하나는 최대 10분을 처리합니다. 더 긴 영상은 긴 오디오 파일 전사하기에서처럼 여러 조각으로 나눠 전사하고, 각 조각의 시작 시각을 그 조각의 구간에 더하세요.

curl -X POST https://api.sume.com/v1/stt-1.0/transcribe \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: episode-42-part-1" \
  -d '{
    "audio_url": "https://example.com/audio/episode-42-part-1.m4a",
    "duration_seconds": 600,
    "segmentation": { "mode": "sentence" }
  }'

전사문을 챕터로 어떻게 바꾸나요?

타이밍이 있는 문장을 언어 모델에 넘기고, 챕터 시작 시각과 제목을 정해진 JSON 형태로 요청하세요. Sume의 POST /v1/agent/completions에서는 구간을 input에 담아 보내고(에이전트는 이 값을 지시가 아니라 데이터로 다룹니다), output_schema로 형태를 고정하세요. API로 영상 요약하기는 같은 호출로 요약을 만들며, 여기서는 출력이 챕터 시작 시각과 제목뿐입니다.

• generation_spend_cap_usd는 필수이고 기본값이 없으며 0일 수 없습니다. 챕터에는 미디어 생성이 필요 없으므로 상한은 작게 잡아도 충분합니다.
• 스키마는 엄격한 부분집합에 맞아야 합니다. 루트는 객체이고, 모든 객체가 additionalProperties: false를 설정하며, 모든 속성이 required에 나열되어야 합니다.
• 호출은 agent.run 영수증과 함께 202를 반환합니다. next_action이 더 이상 poll_status가 아닐 때까지 영수증의 status_url을 폴링하세요. 완료된 실행은 output을 여러분의 chapters로 채웁니다. 스키마를 만족하는 것이 없으면 output은 null이고 output_error가 이유를 알려 주며, API에서는 실행이 failed로 끝납니다.
• API 키에는 agent_completions:write 스코프가 필요합니다. Agent Completions가 나오기 전에 만든 키에는 이 스코프가 없습니다.

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: episode-42-chapters" \
  -d '{
    "instruction": "Split this talk into chapters where the topic changes. Start each chapter at a segment start. Keep titles short.",
    "input": { "segments": [{ "index": 0, "text": "Welcome back to the show.", "start": 0, "end": 2.4 }] },
    "output_schema": {
      "name": "acme/youtube-chapters/v1",
      "schema": {
        "type": "object", "additionalProperties": false, "required": ["chapters"],
        "properties": { "chapters": { "type": "array", "items": {
          "type": "object", "additionalProperties": false,
          "required": ["start_seconds", "title"],
          "properties": {
            "start_seconds": { "type": "number" }, "title": { "type": "string" } } } } }
      }
    },
    "generation_spend_cap_usd": 1
  }'

설명란에 넣을 챕터는 어떤 형식으로 쓰나요?

붙여 넣기 전에 모델이 준 목록을 코드로 YouTube 규칙과 대조하세요. 시작 시각순으로 정렬하고, 첫 챕터를 00:00으로 맞추고, 10초가 안 되는 챕터는 빼고, 최소 세 개가 남는지 확인하세요. 아래 포매터는 MM:SS 형식으로 쓰며, 60분이 넘으면 시간 자리를 더합니다.

const pad = (n) => String(n).padStart(2, "0");
function stamp(seconds) {
  const s = Math.floor(seconds);
  const h = Math.floor(s / 3600);
  const m = Math.floor((s % 3600) / 60);
  return (h ? h + ":" + pad(m) : pad(m)) + ":" + pad(s % 60);
}

function toDescription(chapters, videoSeconds) {
  const sorted = [...chapters].sort((a, b) => a.start_seconds - b.start_seconds);
  const kept = [{ ...sorted[0], start_seconds: 0 }]; // the first timestamp is 00:00
  for (const c of sorted.slice(1)) {
    // YouTube: each chapter runs 10 seconds or longer
    if (c.start_seconds - kept[kept.length - 1].start_seconds >= 10) kept.push(c);
  }
  if (videoSeconds - kept[kept.length - 1].start_seconds < 10) kept.pop();
  if (kept.length < 3) throw new Error("YouTube needs at least three timestamps");
  return kept.map((c) => stamp(c.start_seconds) + " " + c.title).join("\n");
}

비용은 얼마인가요?

전사는 API 요금에 나온 오디오 분당 $0.01이며 기본적으로 5.5% 에이전트 수수료가 더해지므로, 30분짜리 영상의 전사문은 수수료 전 $0.30입니다.

에이전트 자체의 턴을 포함한 completion 비용은 GET /v1/usage?run_id=…가 돌려주는 debited_usd입니다(Usage). 지출 상한은 에이전트의 LLM 턴이 아니라 생성에만 적용되므로, 실제 비용은 이 값으로 확인하세요.