영상 텍스트 변환 API: 오디오 트랙을 보내 전사하기

API로 영상을 텍스트로 전사하려면 영상의 오디오 트랙을 음성 인식 엔드포인트로 보내고, 단어별 타임스탬프가 담긴 전사문을 돌려받으세요. 음성 인식은 화면이 아니라 소리를 대상으로 동작합니다. Sume에서는 이미 Sume에 있는 클립이라면 transcribe: true를 넣어 POST /v1/video-inspect로 보냅니다. 직접 가진 MP4라면 오디오를 추출해 공개 HTTPS URL에 올린 뒤, POST /v1/stt-1.0/transcribe로 STT 1.0에 보내세요.

검사는 영상 검사 문서에 설명되어 있습니다. STT 1.0은 Sume API 레퍼런스의 바탕이 되는 OpenAPI 문서에 명세되어 있으며, API 레퍼런스 문서 페이지는 정확한 요청·응답 형태의 기준으로 이 문서를 안내합니다. 모두 2026-09-27에 확인했습니다.

내 영상에는 어떤 경로가 맞나요?

영상 파일이 어디에 있는지에 따라 경로를 고르세요. 다른 사이트의 영상 페이지 링크는 어느 쪽에서도 동작하지 않습니다. STT 1.0에는 오디오 파일 URL이 필요하고, 검사는 워크스페이스의 media.sume.com에 있는 파일만 읽기 때문입니다.

직접 가진 MP4 파일은 어떻게 전사하나요?

영상이 아니라 오디오를 보내세요. STT 1.0 문서는 audio_url을 공개 HTTPS 오디오 URL로 설명하며, 요청에는 파일 업로드 필드가 없습니다. 이 필드에 영상 파일을 보내는 방법은 문서화되어 있지 않으므로, 오디오는 직접 준비하세요.

• 오디오 트랙은 직접 쓰는 도구로 추출하세요. 참고로 Sume의 오디오 분리 문서는 16 kHz 모노를 “the STT shape”(STT 형태)라고 부릅니다.
• 오디오 파일은 자체 스토리지처럼 STT 1.0이 공개 HTTPS로 가져올 수 있는 곳에 두세요.
• duration_seconds를 파일 길이(1–600)로 설정하고, 문장 타임스탬프가 필요하면 segmentation도 넣어 제출하세요. 그런 다음 단어별 타임스탬프를 주는 음성 인식 API에서처럼 Job을 폴링하고 결과를 읽으세요.

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: webinar-042-audio" \
  -d '{
    "audio_url": "https://example.com/audio/webinar-042.m4a",
    "duration_seconds": 540,
    "segmentation": { "mode": "sentence" }
  }'

이미 Sume에 있는 영상은 어떻게 전사하나요?

앞서 실행한 Sume Job의 출력처럼 클립이 워크스페이스의 media.sume.com 아티팩트나 에셋이라면 영상 검사를 쓰세요. transcribe: true를 넣으면 검사가 클립의 오디오에 STT 1.0을 실행하므로 따로 추출할 것이 없습니다. Idempotency-Key는 필수이며, 호스트 밖 URL은 접수 단계에서 거부됩니다.

• 기본 sync 모드는 최대 30초 기다린 뒤, 완료된 검사를 200으로 돌려주거나 폴링할 Job을 202로 돌려줍니다. 나중에 GET /v1/video-inspect/{id}로 읽으세요.
• 오디오 트랙이 없는 클립은 inspect_source_has_no_audio로 실패합니다. 먼저 probe.has_audio를 확인하세요. frames: false 검사면 충분합니다.
• 함께 반환되는 프로브와 스틸은 영상 검사 API에서 다룹니다.

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

영상이 10분보다 길면 어떻게 하나요?

여러 조각으로 나눠 전사하세요. STT 1.0의 duration_seconds는 최대 600이고, 검사의 길이 힌트도 최대 600초입니다. 오디오를 10분 이하의 조각으로 자르고, 조각마다 전사한 뒤, 각 조각의 시작 시각을 그 조각의 타임스탬프에 더하세요. 자세한 과정은 긴 오디오 파일 전사하기에서 다룹니다.

Sume에 있는 영상이라면 range를 지정한 오디오 분리가 트랙의 그 부분을 media.sume.com의 새 오디오 파일로 반환하므로, 이 파일을 STT 1.0으로 보내면 됩니다. 분리는 최대 1,800초 길이의 원본을 읽습니다. 모든 조각이 STT 1.0에 맞도록 각 구간은 600초 이하로 두세요. 분리는 한 번 할 때마다 별도의 Job이며 Job당 요율이 붙습니다. 문서는 이 요율을 GET /v1/catalog에서 확인하라고 안내합니다.

영상을 전사하는 비용은 얼마인가요?

두 경로 모두 전사문을 오디오 분 단위로, STT 1.0 공개 요율에 따라 과금합니다. API 요금에 나온 오디오 분당 $0.01이며, 기본적으로 5.5% 에이전트 수수료가 더해집니다. duration_seconds를 생략하면 Sume가 1분을 예약합니다. 검사에서는 프로브와 스틸이 과금되지 않으며, 예약이 걸리는 것은 전사뿐입니다.