REST API를 이용한 음성 인식 시작하기 (PowerShell, cUrl, C#)

클라우드 기반의 음성 서비스를 이용하면 REST API를 사용해서 음성 오디오를 텍스트로 변환하는 응용 프로그램을 개발할 수 있습니다.

요구 사항

Speech API 구독 및 무료 평가판 구독 키 발급받기

Speech API는 Microsoft Cognitive Services의 (구 프로젝트 Oxford) 일부분입니다. 무료 평가판 구독 키는 Cognitive Services 체험하기 페이지에서 발급받을 수 있습니다. 음성 탭에서 Bing Speech API를 선택한 다음, API 키 가져오기(Get API Key) 버튼을 클릭합니다. 그러면 기본 키와 보조 키가 발급됩니다. 두 키 모두 동일한 할당량에 연결되어 있으므로 두 키 중 아무 키나 사용해도 무방합니다.

미리 녹음된 오디오 파일

본문의 예제에서는 미리 녹음된 오디오 파일을 이용해서 REST API를 사용하는 방법을 살펴봅니다. 직접 짧은 문장을 말해서 오디오 파일로 녹음해도 무방합니다. 가령, "오늘 날씨는 어때?" 또는 "볼만한 재미있는 영화를 찾아줘."라고 말하면 됩니다. 음성 인식 API는 외부 마이크 입력도 지원합니다.

인식 요청을 만들고 음성 인식 서비스로 전송하기

음성 인식을 위한 다음 단계는, 올바른 요청 헤더와 본문을 사용해서 Speech HTTP 끝점에 POST 요청을 전송하는 것입니다.

서비스 URI

음성 인식 서비스의 URI는 인식 모드 및 인식 언어를 기반으로 정의됩니다:

https://speech.platform.bing.com/speech/recognition/<RECOGNITION_MODE>/cognitiveservices/v1?language=<LANGUAGE_TAG>&format=<OUTPUT_FORMAT>

<RECOGNITION_MODE>는 인식 모드를 지정하며, 그 값은 interactive, conversation, 또는 dictation 중 하나이어야 합니다. 이 값은 URI의 필수 자원 경로입니다. 보다 자세한 정보는 Recognition modes 절을 참고하시기 바랍니다.

<LANGUAGE_TAG>는 쿼리 문자열의 필수 매개 변수입니다. 이 값은 오디오를 변환하기 위한 대상 언어를 정의하는데, 가령 en-US는 영어(미국)을 뜻합니다. 보다 자세한 정보는 Recognition languages 절을 참고하시기 바랍니다.

<OUTPUT_FORMAT>는 쿼리 문자열의 선택적 매개 변수입니다. 값으로는 simple 및 detailed를 지정할 수 있습니다. 기본적으로 서비스는 simple 형식으로 결과를 반환합니다. 보다 자세한 정보는 Output format 절을 참고하시기 바랍니다.

다음 표는 서비스 URI의 몇 가지 사례를 보여줍니다.

요청 헤더

요청 헤더에는 반드시 다음 필드들이 설정되어 있어야 합니다:

• Ocp-Apim-Subscription-Key: 서비스를 호출할 때마다 Ocp-Apim-Subscription-Key 헤더에 구독 키를 전달해야 합니다. 음성 서비스는 구독 키 대신 인증 토큰을 전달하는 기능도 지원합니다. 더 자세한 정보는 Authentication 문서를 참고하시기 바랍니다.

• Content-type: Content-type 필드는 오디오 스트림의 형식과 코덱을 기술합니다. 현재는 WAV 파일 및 PCM 모노 16000 인코딩만 지원됩니다. 이 형식에 대한 Content-type 값은 audio/wav; codec=audio/pcm; samplerate=16000 입니다.

Transfer-Encoding 필드는 선택 사항입니다. 이 필드를 chunked로 설정하면 오디오를 작은 청크로 자를 수 있습니다. 보다 자세한 정보는 Chunked transfer 문서를 참고하시기 바랍니다.

다음은 요청 헤더의 사례입니다:

POST https://speech.platform.bing.com/speech/recognition/interactive/cognitiveservices/v1?language=en-US&format=detailed HTTP/1.1
Accept: application/json;text/xml
Content-Type: audio/wav; codec=audio/pcm; samplerate=16000
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
Host: speech.platform.bing.com
Transfer-Encoding: chunked
Expect: 100-continue

서비스에 요청 전송하기

다음 예제는 Speech REST 끝점에 음성 인식 요청을 전송하는 방법을 보여줍니다. 이 예제는 interactive 인식 모드를 사용합니다.

$SpeechServiceURI =
'https://speech.platform.bing.com/speech/recognition/interactive/cognitiveservices/v1?language=en-us&format=detailed'

# $OAuthToken is the authorization token returned by the token service.
$RecoRequestHeader = @{
  'Ocp-Apim-Subscription-Key' = 'YOUR_SUBSCRIPTION_KEY';
  'Transfer-Encoding' = 'chunked'
  'Content-type' = 'audio/wav; codec=audio/pcm; samplerate=16000'
}

# Read audio into byte array
$audioBytes = [System.IO.File]::ReadAllBytes("YOUR_AUDIO_FILE")

$RecoResponse = Invoke-RestMethod -Method POST -Uri $SpeechServiceURI -Headers $RecoRequestHeader -Body $audioBytes

# Show the result
$RecoResponse

curl -v -X POST "https://speech.platform.bing.com/speech/recognition/interactive/cognitiveservices/v1?language=en-us&format=detailed" -H "Transfer-Encoding: chunked" -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" -H "Content-type: audio/wav; codec=audio/pcm; samplerate=16000" --data-binary @YOUR_AUDIO_FILE

HttpWebRequest request = null;
request = (HttpWebRequest)HttpWebRequest.Create(requestUri);
request.SendChunked = true;
request.Accept = @"application/json;text/xml";
request.Method = "POST";
request.ProtocolVersion = HttpVersion.Version11;
request.ContentType = @"audio/wav; codec=audio/pcm; samplerate=16000";
request.Headers["Ocp-Apim-Subscription-Key"] = "YOUR_SUBSCRIPTION_KEY";

// Send an audio file by 1024 byte chunks
using (fs = new FileStream(YOUR_AUDIO_FILE, FileMode.Open, FileAccess.Read))
{

    /*
    * Open a request stream and write 1024 byte chunks in the stream one at a time.
    */
    byte[] buffer = null;
    int bytesRead = 0;
    using (Stream requestStream = request.GetRequestStream())
    {
        /*
        * Read 1024 raw bytes from the input audio file.
        */
        buffer = new Byte[checked((uint)Math.Min(1024, (int)fs.Length))];
        while ((bytesRead = fs.Read(buffer, 0, buffer.Length)) != 0)
        {
            requestStream.Write(buffer, 0, bytesRead);
        }

        // Flush
        requestStream.Flush();
    }
}

음성 인식 응답 처리하기

Speech Service는 요청을 처리한 다음, 그 결과를 JSON 형식의 응답으로 반환합니다.

다음 코드 스니핏은 스트림에서 응답을 읽는 방법을 보여줍니다.

# show the response in JSON format
ConvertTo-Json $RecoResponse

curl -X POST "https://speech.platform.bing.com/speech/recognition/interactive/cognitiveservices/v1?language=en-us&format=detailed" -H "Transfer-Encoding: chunked" -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" -H "Content-type: audio/wav; codec=audio/pcm; samplerate=16000" --data-binary @YOUR_AUDIO_FILE | jq

/*
* Get the response from the service.
*/
Console.WriteLine("Response:");
using (WebResponse response = request.GetResponse())
{
    Console.WriteLine(((HttpWebResponse)response).StatusCode);

    using (StreamReader sr = new StreamReader(response.GetResponseStream()))
    {
        responseString = sr.ReadToEnd();
    }

    Console.WriteLine(responseString);
    Console.ReadLine();
}

다음은 JSON 응답 예제입니다:

OK
{
  "RecognitionStatus": "Success",
  "Offset": 22500000,
  "Duration": 21000000,
  "NBest": [{
    "Confidence": 0.941552162,
    "Lexical": "find a funny movie to watch",
    "ITN": "find a funny movie to watch",
    "MaskedITN": "find a funny movie to watch",
    "Display": "Find a funny movie to watch."
  }]
}

제한사항

REST API에는 몇 가지 제한사항이 존재합니다:

• 최대 15 초까지만 오디오 스트림을 지원합니다.
• 인식 중간에 중간 결과를 지원하지 않습니다. 사용자는 최종 인식 결과만 반환받습니다.

이런 제한사항을 해소하기 위해서는 음성 클라이언트 라이브러리를 사용해야 합니다. 또는 Speech WebSocket 프로토콜을 사용해서 직접 작업을 수행할 수도 있습니다.

다음 단계

• C#, Java 등의 언어로 REST API를 사용하는 방법을 살펴보려면, 예제 응용 프로그램들을 참고하시기 바랍니다.
• 오류를 찾고 수정하려면 Troubleshooting 문서를 참고하시기 바랍니다.
• 고급 기능을 사용하려면 Speech 클라이언트 라이브러리의 사용 방법을 참고하시기 바랍니다.

라이센스

모든 Cognitive Services SDK 및 예제는 MIT 라이센스가 적용됩니다. 보다 자세한 정보는 라이센스를 참고하시기 바랍니다.