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.ntruss.com/recog/v1/stt

요청 파라미터

파라미터 이름 타입 설명 필수 여부
lang string 음성인식에 사용할 언어
- Kor: 한국어
- Jpn: 일본어
- Chn: 중국어
- Eng: 영어
필수

요청 헤더

헤더명 설명
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.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, Jpn, Eng, Chn )
            String apiURL = "https://naveropenapi.apigw.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);
        }
    }
}
<?php

$curl = curl_init();
$file_path = "음성 파일 경로";

$lang = "Kor";  // 언어 코드 ( Kor, Jpn, Eng, Chn )
$client_id = "YOUR_CLIENT_KEY";
$client_secret = "YOUR_CLIENT_SECRET";

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://naveropenapi.apigw.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, Jpn, Eng, Chn )
function stt(language, filePath) {
    const url = `https://naveropenapi.apigw.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, Jpn, Eng, Chn )
url = "https://naveropenapi.apigw.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, Jpn, Eng, Chn )
            string url = $"https://naveropenapi.apigw.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 인지 확인이 필요합니다.
500 STT998 Failed to STT 음성인식 중 오류가 발생하였습니다. 고객지원을 통해 문의하시면 신속히 조치하겠습니다.
500 STT999 Internal Server Error 알 수 없는 오류 발생하였습니다. 고객지원을 통해 문의하시면 신속히 조치하겠습니다.