JavaScript 음성 인식 API: Node.js에서 오디오를 텍스트로

JavaScript로 음성을 텍스트로 변환하려면 음성이 어디서 오는지에 따라 방법을 고르세요. 웹 페이지에서는 Web Speech API의 SpeechRecognition 인터페이스가 기기의 마이크(또는 오디오 트랙)를 들으며, 기본적으로 사용자의 플랫폼이 제공하는 서비스를 씁니다. 오디오 파일을 단어별 타이밍이 있는 텍스트로 바꾸려면 서버에서 호스팅된 음성 인식(STT) API를 호출하세요. 파일의 URL을 보내고, Job을 기다린 뒤, 전사문을 읽으면 됩니다. Node.js에서 Sume의 TypeScript SDK로는 transcribeSttV1(POST /v1/stt-1.0/transcribe)을 호출하고, waitForJob으로 기다린 다음, Job의 result에서 text, words, segments를 읽습니다.

Sume 쪽 단계는 TypeScript SDK와 실행 기다리기 (영문) 문서, 그리고 Sume API 레퍼런스의 STT 1.0 스키마에서 가져왔으며, 2026-09-27에 확인했습니다. 브라우저 API는 MDN의 Web Speech API 페이지를 바탕으로 설명합니다. SDK 설치, API 키를 서버에 두는 방법, waitForJob 패턴은 JavaScript 텍스트 음성 변환(TTS) API와 같으며, 이 글은 전사 쪽을 다룹니다.

Node.js에서 오디오 파일은 어떻게 전사하나요?

녹음 파일의 URL을 제출하고, Job을 기다린 뒤, Job 레코드에서 전사문을 읽으세요. 아래 코드는 감지된 언어, 전체 텍스트, 각 문장의 시작과 끝을 초 단위로 출력합니다.

import { createSumeClient, transcribeSttV1, waitForJob } from "@sume-com/sdk";

const client = createSumeClient({ apiKey: process.env.SUME_API_KEY! });

const { data, error } = await transcribeSttV1({
  client,
  headers: { "idempotency-key": "support-call-0042" },
  body: {
    audio_url: "https://example.com/audio/support-call.m4a",
    segmentation: { mode: "sentence" },
  },
});
if (error) throw new Error(JSON.stringify(error));

const job = await waitForJob(data!.data.request_id, { client });
if (job.status !== "completed") throw new Error(`STT job ${job.status}`);

const result = job.result;
console.log(result?.language_code, result?.text);
for (const s of result?.segments ?? []) console.log(s.start, s.end, s.text);

요청에는 어떤 오디오 URL과 옵션을 넣나요?

필수 필드는 audio_url 하나뿐이고 본문에는 파일 바이트를 담을 필드가 없으므로, 녹음 파일은 자체 스토리지 같은 공개 HTTPS 주소에 이미 올라가 있어야 합니다. API 레퍼런스는 Sume 미디어 URL을 권장합니다. 단어별 타이밍에는 옵션이 필요 없습니다. 항상 함께 반환됩니다.

결과에서 단어와 문장은 어디에 있나요?

job.result에 있습니다. text는 전사문 전체입니다. words는 { word, start, end }의 배열이며, 시간은 오디오 시작부터의 초 단위입니다. 단어만 필요하다면 type이 spacing이 아닌 항목만 남기세요. 분할을 켜면 segments가 문장마다 index, text, start, end, duration_seconds를 담아 추가됩니다. 파일 위에서 빈틈없이 이어지는 시간 범위이며, 오디오를 잘라 내지는 않습니다. 모든 결과 필드는 단어별 타임스탬프를 주는 음성 인식 API에 정리되어 있습니다.

오디오를 스트리밍하거나 마이크 음성을 실시간으로 전사할 수 있나요?

STT 1.0으로는 할 수 없습니다. STT 1.0은 URL에 있는 파일을 Job으로 전사하며, 현재 Developer API에는 SSE나 WebSocket 전송 방식이 없습니다. 웹 페이지에서 실시간 음성을 다룰 때는 앞에서 설명한 Web Speech API가 브라우저 인터페이스입니다. 녹음을 단어별 타이밍과 함께 보관하려면 공개 HTTPS URL에 저장한 뒤 그 파일을 전사하세요.

한도는 어떻게 되고, 비용은 얼마인가요?

STT 1.0 요금은 오디오 분당 $0.01이며, 기본적으로 5.5% 에이전트 수수료가 더해집니다.

• 요청 하나로 문서에 명시된 최대치인 10분 분량의 오디오까지 처리합니다. 더 긴 녹음은 여러 부분으로 나눠 전사하고, 각 부분의 시작 시각을 그 부분의 타임스탬프에 더하세요. 긴 오디오 파일 전사하기를 참고하세요.
• 화자 라벨은 없습니다. diarize는 서버 쪽에서 고정되어 있고 현재 코드에서는 꺼진 채 실행되며, 이 값을 보내는 요청은 거부됩니다.