--- title: "stt (Speech-To-Text) " slug: "ai-naver-clovaspeechrecognition-stt" tags: ["CSR", "CLOVA Speech Recognition"] updated: 2026-09-17T09:10:00Z published: 2026-09-17T09:10:00Z canonical: "api-fin.ncloud-docs.com/ai-naver-clovaspeechrecognition-stt" --- > ## Documentation Index > Fetch the complete documentation index at: https://api-fin.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # stt (Speech-To-Text) ## 개요 - CLOVA Speech Recognition REST API (이하 CSR REST API)는 HTTP 기반의 REST API로 제공하는 음성인식 API로, 인식에 사용할 언어와 음성 데이터를 입력받고, 그에 맞는 인식 결과를 텍스트로 반환합니다. - 입력 음성데이터 포맷은 mp3, aac, ac3, ogg, flac, wav을 지원합니다. ## 요청 | Method | Request URI | | --- | --- | | POST | `https://naveropenapi.apigw-pub.fin-ntruss.com/recog/v1/stt` | ### 요청 파라미터 | 파라미터 이름 | 타입 | 설명 | 필수 여부 | | --- | --- | --- | --- | | lang | string | 음성인식에 사용할 언어 - Kor: 한국어 ※ 금융 클라우드에서는 한국어만 지원합니다. | 필수 | ### 요청 헤더 | 헤더명 | 설명 | | --- | --- | | X-NCP-APIGW-API-KEY-ID | 앱 등록 시 발급받은 Client ID `X-NCP-APIGW-API-KEY-ID:{Client ID}` | | X-NCP-APIGW-API-KEY | 앱 등록 시 발급 받은 Client Secret `X-NCP-APIGW-API-KEY:{Client Secret}` | | Content-Type | application/octet-stream으로 고정 `Content-Type: application/octet-stream` | ### 요청 바디 | 필드명 | 필수 여부 | 타입 | 제약 사항 | 설명 | | --- | --- | --- | --- | --- | | image | Yes | mp3, aac, ac3, ogg, flac, wav | 바이너리 사운드 데이터 (최대 60초) | 음성 파일 | ## 응답 ### 응답 바디 | 필드 이름 | 데이터 타입 | 설명 | | --- | --- | --- | | `text` | string | 음성에 대한 Text | ## 예시 ### 요청 예시 ``` [HTTP Request URL] https://naveropenapi.apigw-pub.fin-ntruss.com/recog/v1/stt?lang=Kor [HTTP Request Body] --- binary sound data --- ``` ### 응답 예시 ``` { "text": "안녕하세요" } ``` ### API 예제 다음은 각 언어별 CSR API 구현 예제입니다 ``` import java.io.*; import java.net.HttpURLConnection; import java.net.URL; public class Main { public static void main(String[] args) { String clientId = "YOUR_CLIENT_ID"; // Application Client ID"; String clientSecret = "YOUR_CLIENT_SECRET"; // Application Client Secret"; try { String imgFile = "음성 파일 경로"; File voiceFile = new File(imgFile); String language = "Kor"; // 언어 코드 ( Kor ) String apiURL = "https://naveropenapi.apigw-pub.fin-ntruss.com/recog/v1/stt?lang=" + language; URL url = new URL(apiURL); HttpURLConnection conn = (HttpURLConnection)url.openConnection(); conn.setUseCaches(false); conn.setDoOutput(true); conn.setDoInput(true); conn.setRequestProperty("Content-Type", "application/octet-stream"); conn.setRequestProperty("X-NCP-APIGW-API-KEY-ID", clientId); conn.setRequestProperty("X-NCP-APIGW-API-KEY", clientSecret); OutputStream outputStream = conn.getOutputStream(); FileInputStream inputStream = new FileInputStream(voiceFile); byte[] buffer = new byte[4096]; int bytesRead = -1; while ((bytesRead = inputStream.read(buffer)) != -1) { outputStream.write(buffer, 0, bytesRead); } outputStream.flush(); inputStream.close(); BufferedReader br = null; int responseCode = conn.getResponseCode(); if(responseCode == 200) { // 정상 호출 br = new BufferedReader(new InputStreamReader(conn.getInputStream())); } else { // 오류 발생 System.out.println("error!!!!!!! responseCode= " + responseCode); br = new BufferedReader(new InputStreamReader(conn.getInputStream())); } String inputLine; if(br != null) { StringBuffer response = new StringBuffer(); while ((inputLine = br.readLine()) != null) { response.append(inputLine); } br.close(); System.out.println(response.toString()); } else { System.out.println("error !!!"); } } catch (Exception e) { System.out.println(e); } } } ``` ``` "https://naveropenapi.apigw-pub.fin-ntruss.com/recog/v1/stt?lang=".$lang, CURLOPT_RETURNTRANSFER => 1, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_POST => 1, CURLOPT_POSTFIELDS => file_get_contents($file_path), CURLOPT_HTTPHEADER => array( "Content-Type: application/octet-stream", "X-NCP-APIGW-API-KEY-ID: ".$client_id, "X-NCP-APIGW-API-KEY: ".$client_secret ), )); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "cURL Error #:" . $err; } else { echo $response; } ?> ``` ``` const fs = require('fs'); const request = require('request'); const clientId = 'YOUR_CLIENT_ID'; const clientSecret = 'YOUR_CLIENT_SECRET'; // language => 언어 코드 ( Kor ) function stt(language, filePath) { const url = `https://naveropenapi.apigw-pub.fin-ntruss.com/recog/v1/stt?lang=${language}`; const requestConfig = { url: url, method: 'POST', headers: { 'Content-Type': 'application/octet-stream', 'X-NCP-APIGW-API-KEY-ID': clientId, 'X-NCP-APIGW-API-KEY': clientSecret }, body: fs.createReadStream(filePath) }; request(requestConfig, (err, response, body) => { if (err) { console.log(err); return; } console.log(response.statusCode); console.log(body); }); } stt('Kor', '음성 파일 경로 (ex: ./test.wav)'); ``` ``` import sys import requests client_id = "YOUR_CLIENT_ID" client_secret = "YOUR_CLIENT_SECRET" lang = "Kor" # 언어 코드 ( Kor ) url = "https://naveropenapi.apigw-pub.fin-ntruss.com/recog/v1/stt?lang=" + lang data = open('음성 파일 경로', 'rb') headers = { "X-NCP-APIGW-API-KEY-ID": client_id, "X-NCP-APIGW-API-KEY": client_secret, "Content-Type": "application/octet-stream" } response = requests.post(url, data=data, headers=headers) rescode = response.status_code if(rescode == 200): print (response.text) else: print("Error : " + response.text) ``` ``` using System; using System.Net; using System.Text; using System.IO; using System.Collections.Generic; using System.Collections.Specialized; namespace NaverAPI_Guide { class APIExamSTT { static void Main(string[] args) { string FilePath = "YOUR_FILE_NAME"; FileStream fs = new FileStream(FilePath, FileMode.Open, FileAccess.Read); byte[] fileData = new byte[fs.Length]; fs.Read(fileData, 0, fileData.Length); fs.Close(); string lang = "Kor"; // 언어 코드 ( Kor ) string url = $"https://naveropenapi.apigw-pub.fin-ntruss.com/recog/v1/stt?lang={lang}"; HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url); request.Headers.Add("X-NCP-APIGW-API-KEY-ID", "YOUR_CLIENT_ID"); request.Headers.Add("X-NCP-APIGW-API-KEY", "YOUR_CLIENT_SECRET"); request.Method = "POST"; request.ContentType = "application/octet-stream"; request.ContentLength = fileData.Length; using (Stream requestStream = request.GetRequestStream()) { requestStream.Write(fileData, 0, fileData.Length); requestStream.Close(); } HttpWebResponse response = (HttpWebResponse)request.GetResponse(); Stream stream = response.GetResponseStream(); StreamReader reader = new StreamReader(stream, Encoding.UTF8); string text = reader.ReadToEnd(); stream.Close(); response.Close(); reader.Close(); Console.WriteLine(text); } } } ``` ## 오류 코드 | HttpStatusCode | ErrorCode | ErrorMessage | Description | | --- | --- | --- | --- | | 413 | STT000 | Request Entity Too Large | 허용 음성데이터 용량을 초과 ( 최대 3MB ) | | 413 | STT001 | Exceed Sound Data length | 허용 음성데이터 길이를 초과 ( 60초 ) | | 400 | STT002 | Invalid Content Type | application/octet-stream 이외의 content-type인 경우 발생 | | 400 | STT003 | Empty Sound Data | 음성 데이터가 입력되지 않음 | | 400 | STT004 | Empty Language | 언어 파라미터가 입력되지 않음 | | 400 | STT005 | Invalid Language | 정해진 언어 이외의 언어 값이 입력 | | 500 | STT006 | Failed to pre-processing | 음성인식 전처리 중 오류가 발생. 음성 데이터가 정상적인 wav, mp3, flac 인지 확인이 필요 | | 400 | STT007 | Too Short Sound Data | 음성 데이터 길이가 너무 짧음 | | 500 | STT998 | Failed to STT | 음성인식 중 오류가 발생. 고객지원으로 문의 필요 | | 500 | STT999 | Internal Server Error | 알 수 없는 오류 발생. 고객지원으로 문의 필요 |