음성 인식 API로 오디오의 언어를 감지하는 방법

API로 오디오 파일의 언어를 감지하려면 언어 힌트 없이 음성 인식을 실행하고, 결과에서 감지된 언어 코드를 읽으세요. 같은 호출로 전사문도 받습니다. Sume STT 1.0은 language_code를 생략하면 언어를 자동으로 감지하며, 결과는 값이 있는 경우 language_code와 신뢰도인 language_probability를 알려 줍니다.

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

API로 말하는 언어를 어떻게 감지하나요?

language_code 없이 오디오를 보내세요. API 레퍼런스에 있는 auto_detect_language 예시가 바로 그렇습니다. audio_url과 mode만 있고 다른 필드는 없습니다. URL은 공개 HTTPS여야 하며, 아래 요청은 사용량 예약의 크기를 정하는 duration_seconds도 설정합니다.

제출한 뒤에는 terminal이 true가 될 때까지 GET /v1/jobs/{id}/status를 폴링하거나 webhook_url을 넘기고, 그다음 GET /v1/jobs/{id}/result에서 언어 필드를 읽으세요.

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: detect-lang-call-0117" \
  -d '{
    "audio_url": "https://example.com/audio/call-0117.wav",
    "duration_seconds": 90,
    "mode": "async"
  }'

결과에서 무엇을 알 수 있나요?

완료된 결과의 data.result 아래에는 다음 필드가 담깁니다. 두 언어 필드는 모두 “when available”(있는 경우)이므로, 이 필드가 없는 결과도 처리하도록 코드를 작성하세요. 레퍼런스는 language_probability를 신뢰도라고만 하고 척도는 밝히지 않으므로, 기준값은 직접 가진 파일의 결과를 보고 정하세요.

// data from GET /v1/jobs/{id}/result
const { language_code, language_probability, text } = data.result;
const unsure =
  !language_code ||
  (language_probability != null && language_probability < MIN_CONFIDENCE);
if (unsure) sendToReview(file, text); // MIN_CONFIDENCE: your own cutoff
else routeByLanguage(file, language_code, text);

대신 언어 힌트를 넘겨야 하나요?

언어를 이미 알고 있을 때만 넘기세요. language_code는 en이나 ko 같은 2–16자의 선택적 BCP-47 힌트입니다. 힌트를 주면 결과의 language_code는 감지된 코드가 아니라 요청한 코드일 수 있으므로, 힌트를 그대로 되돌려줄 뿐일 수도 있습니다.

언어가 표시되지 않은 파일에는 힌트를 빼고, 한국어로만 된 아카이브처럼 이미 분류해 둔 파일에는 힌트를 설정하세요.

영상의 언어도 감지할 수 있나요?

네, 영상이 Sume에 있다면 가능합니다. transcribe: true를 넣은 영상 검사는 워크스페이스의 media.sume.com에 있는 클립에 STT 1.0을 실행하며, 검사의 language_code도 같은 방식으로 동작합니다. 자동 감지를 원하면 생략하세요. API 레퍼런스에서 검사 전사문에는 language_code 필드는 있지만 language_probability는 없습니다.

직접 가진 영상 파일이라면 영상 텍스트 변환 API에서처럼 오디오 트랙을 STT 1.0으로 보내세요.

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

• 감지에는 전체 전사가 함께 따라오며, API 요금에 나온 오디오 분당 $0.01로 과금되고 기본적으로 5.5% 에이전트 수수료가 더해집니다. 긴 녹음에서 비용을 줄이려면 짧은 발췌 구간을 보내세요. 오디오 분이 적을수록 비용도 적게 듭니다.
• 요청 하나에 파일 하나, 최대 10분입니다. duration_seconds의 범위는 1–600입니다. 생략하면 Sume가 1분을 예약합니다.
• 결과에는 파일 전체에 대한 language_code가 하나만 있습니다. 중간에 언어가 바뀌는 녹음에 어떤 코드가 붙는지는 레퍼런스에 나와 있지 않습니다.
• 레퍼런스가 예시 힌트로 드는 것은 en과 ko입니다. 감지에 의존하기 전에, 여러분이 다룰 녹음과 비슷한 녹음으로 먼저 시험해 보세요.