2026-09-26미디어 도구

단어별 타임스탬프를 주는 음성 인식 API: Sume STT 1.0

공개 HTTPS 오디오 URL을 POST /v1/stt-1.0/transcribe로 보내면 단어마다 시작·끝 초가 붙은 전사문을 받고, 원하면 문장 구간도 받을 수 있습니다.

읽는 시간 5분Sume

Sume API로 단어별 타임스탬프가 담긴 전사문을 받으려면 공개 HTTPS audio_url을 POST /v1/stt-1.0/transcribe로 보내세요. Sume STT 1.0(sume/stt-1.0)이 이를 Job으로 실행하며, 완료된 결과에는 전사문 text와 함께 각 단어의 start와 end를 오디오 시작부터의 초 단위로 담은 words[] 배열이 들어 있습니다.

STT 1.0은 Sume API 레퍼런스의 바탕이 되는 OpenAPI 문서에 명세되어 있으며, API 레퍼런스 문서 페이지는 정확한 요청·응답 형태의 기준으로 이 문서를 안내합니다. Job 상태와 과금은 핵심 개념을 따릅니다. 모두 2026-09-26에 확인한 내용입니다.

오디오 파일은 어떻게 전사하나요?

필수 필드가 audio_url 하나뿐인 JSON 본문을 보내세요. 같은 본문은 POST /v1/models/sume/stt-1.0/runs에서도 동작합니다. 단어별 타이밍을 켜는 플래그는 없으며, 타이밍은 항상 반환됩니다.

audio_url: 전사할 공개 HTTPS 오디오 URL입니다.
language_code: 2–16자의 선택적 BCP-47 언어 힌트로, en이나 ko 같은 값입니다. 생략하면 언어를 자동으로 감지합니다.
duration_seconds: 사용량 예약에 쓰이는 선택적 정수로, 1에서 600 사이입니다. 생략하면 Sume가 1분 기준으로 예약합니다.
segmentation: 선택 사항입니다. { "mode": "sentence" }를 보내면 문장 구간도 함께 받습니다.
Job 요청과 함께 저장되는 metadata, 그리고 공통 통신 필드인 mode, webhook_url, wait_timeout_seconds.

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: stt-interview-001" \
  -d '{
    "audio_url": "https://example.com/audio/interview.m4a",
    "language_code": "ko",
    "duration_seconds": 20,
    "mode": "async"
  }'

전사문은 어떤 형태인가요?

STT Job은 미디어 아티팩트 대신 텍스트와 타이밍을 반환합니다. Job이 completed가 되면 GET /v1/jobs/:id/result에서 읽으세요.

Sume API 레퍼런스의 STT 1.0 결과 필드, 2026-09-26 확인.
필드	내용
`text`	전사문 텍스트.
`language_code`	감지되었거나 요청한 언어 코드(있는 경우).
`language_probability`	언어 감지 신뢰도(있는 경우).
`words[]`	`word`, `start`, `end`. 시간은 오디오 시작부터의 초 단위이며, `start` 순으로 정렬됩니다. STT 결과에는 항상 있고, 비어 있을 수 있습니다.
`words[].type`	제공되는 경우 토큰의 종류(예: `word`, `spacing`).
`words_truncated`, `words_total`	`words`가 상한인 20,000개 항목에 도달했을 때만 나타납니다. 600초 분량의 전사문은 이 상한에 한참 못 미치며, 타이밍이 조용히 누락되는 일은 없습니다.
`segments[]`	문장 분할을 요청한 경우에만: `index`, `text`, `start`, `end`, `duration_seconds`.

문장 타임스탬프도 받으려면 어떻게 하나요?

"segmentation": { "mode": "sentence" }를 추가하세요. Sume는 반환된 단어를 문장 끝 문장부호 기준으로 문장으로 묶고, 문장부호가 없는 구간은 무음 지점에서 나눕니다. 모드는 sentence 하나뿐입니다.

구간은 빈틈 없이 순서대로 이어집니다. 각 구간의 end는 다음 구간의 start와 같습니다.
boundary_lead_ms(0–500, 기본값 70)는 다음 구간이 시작되기 전, 문장의 마지막 단어 뒤로 이어 붙이는 여유분입니다. TTS 1.0과 규칙도 기본값도 같습니다.
구간은 제출한 audio_url 위의 시간 범위입니다. 잘라 낸 파일은 만들어지지 않으므로, 오디오를 자르는 일은 직접 해야 합니다.
타이밍이 있는 단어가 하나도 돌아오지 않으면, 분할은 타입이 지정된 오류를 내며 실패합니다(fail closed).

폴링, 대기, 웹훅 중 무엇을 써야 하나요?

모든 모드는 첫 응답에서 Job ID를 반환하며, GET /v1/jobs/:id/result는 result_ready가 true가 될 때까지 409 job_not_completed로 응답합니다.

async(기본값)는 status_url, result_url, events_url, cancel_url과 함께 즉시 반환됩니다.
sync와 subscribe는 똑같이 최대 wait_timeout_seconds(0–30)까지만 기다립니다. 그때까지 Job이 끝나지 않아도 응답은 2xx이며, 현재 Job 상태와 폴링 URL이 담깁니다. status_url을 계속 폴링하고, 두 번째 유료 Job을 제출하지 마세요.
webhook은 즉시 반환되고, job.completed, job.failed, job.canceled에 대해서만 서명된 콜백을 보냅니다. mode 없이 webhook_url을 보내면 webhook이 선택됩니다.
클라이언트에서 타임아웃이 나면 Job ID를 보관했다가 Jobs API로 복구하세요. 같은 페이로드로 Idempotency-Key를 다시 쓰면 원래 Job이 반환됩니다. AI 영상 API의 멱등성 키를 참고하세요.

음성 인식 비용은 얼마인가요?

API 요금에는 음성 전사가 오디오 분당 $0.01로 나와 있으며, 여기에 기본 5.5% 에이전트 수수료가 더해집니다. 제출 응답은 예상 금액을 usage.billable_amount_usd로 알려 줍니다.

Sume는 제출할 때 예상 사용량을 예약하고, 성공하면 비용을 확정하며, 확정 전에 실패하거나 취소된 Job은 환불합니다. 이 예약의 크기는 duration_seconds로 정해집니다. 잔액이 예상 금액을 감당하지 못하면 제출은 402를 반환하고 Job은 시작되지 않습니다.

Sume에 호스팅된 영상 속 음성은 영상 검사로도 전사할 수 있습니다. 영상 검사는 클립의 오디오에 STT 1.0을 실행합니다.

STT 1.0에는 어떤 한도가 있나요?

요청 스키마는 위에서 설명한 여덟 개 필드 외에는 받지 않습니다. 문서에 나온 범위는 다음과 같습니다.

duration_seconds: 1–600이므로 힌트의 최댓값은 10분입니다.
language_code: 2–16자.
words[]: 최대 20,000개 항목이며, 상한에 도달하면 words_truncated로 표시됩니다.
분할: sentence만 가능하며, 시간 범위로만 제공되고 잘라 낸 오디오는 없습니다.
webhook_url: 공개 HTTPS, 최대 2,048자. localhost, 사설 네트워크, HTTPS가 아닌 콜백 URL은 거부됩니다.

출처

작성자 Sume