빠른 시작: Bing Speech Recognition REST API 사용Quickstart: Use the Bing Speech recognition REST API

참고

Speech Service 및 SDK는 2019년 10월 15일부터 더 이상 작동하지 않는 Bing Speech를 대체합니다.The new Speech Service and SDK is replacing Bing Speech, which will no longer work starting October 15, 2019. Speech Service로 전환하는 방법에 대한 내용은 Bing Speech에서 Speech Service로 마이그레이션을 참조하세요.For information on switching to the Speech Service, see Migrating from Bing Speech to the Speech Service.

클라우드 기반 Bing Speech Service를 사용하여 REST API를 통해 음성 오디오를 텍스트로 변환함으로써 응용 프로그램을 개발할 수 있습니다.With the cloud-based Bing Speech Service, you can develop applications by using the REST API to convert spoken audio to text.

필수 조건Prerequisites

Speech API 구독 및 평가판 구독 키 가져오기Subscribe to the Speech API, and get a free trial subscription key

Speech API는 Cognitive Services(이전의 Project Oxford)의 일부입니다.The Speech API is part of Cognitive Services (previously Project Oxford). Cognitive Services 구독 페이지에서 평가판 구독 키를 가져올 수 있습니다.You can get free trial subscription keys from the Cognitive Services subscription page. Speech API를 선택한 후에 API 키 가져오기를 선택하여 키를 가져옵니다.After you select the Speech API, select Get API Key to get the key. 기본 및 보조 키를 반환합니다.It returns a primary and secondary key. 두 키는 모두 동일한 할당량에 연결되므로 두 키 중 하나를 사용할 수 있습니다.Both keys are tied to the same quota, so you can use either key.

중요

  • 구독 키를 가져오세요.Get a subscription key. REST API에 액세스하려면 먼저 구독 키가 있어야 합니다.Before you can access the REST API, you must have a subscription key.

  • 구독 키를 사용하세요.Use your subscription key. 다음 REST 샘플에서 YOUR_SUBSCRIPTION_KEY를 사용자 고유의 구독 키로 바꿉니다.In the following REST samples, replace YOUR_SUBSCRIPTION_KEY with your own subscription key.

  • 구독 키를 가져오는 방법은 인증 페이지를 참조하세요.Refer to the authentication page for how to get a subscription key.

미리 녹음된 오디오 파일Prerecorded audio file

여기서는 녹음된 오디오 파일을 사용하여 REST API를 사용하는 방법을 보여 줍니다.In this example, we use a recorded audio file to illustrate how to use the REST API. 짧은 구를 말하면서 자신의 오디오 파일을 기록합니다.Record an audio file of yourself saying a short phrase. 예를 들어 "오늘 날씨는 어떤가요?"For example, say "What is the weather like today?" 또는 "감상하려는 재미 있는 영화를 찾아보세요."라고 말합니다.or "Find funny movies to watch." 음성 인식 API는 외부 마이크 입력도 지원합니다.The speech recognition API also supports external microphone input.

참고

이 예에서는 오디오가 PCM 단일 채널(모노), 16KHz의 WAV 파일로 기록되어야 합니다.The example requires that audio is recorded as a WAV file with PCM single channel (mono), 16 KHz.

인식 요청 작성 및 음성 인식 서비스로 보내기Build a recognition request, and send it to the speech recognition service

음성 인식에 대한 다음 단계는 적절한 요청 헤더와 본문을 사용하여 Speech HTTP 엔드포인트에 POST 요청을 보내는 것입니다.The next step for speech recognition is to send a POST request to the Speech HTTP endpoints with the proper request header and body.

서비스 URIService URI

음성 인식 서비스 URI는 인식 모드인식 언어를 기반으로 하여 정의됩니다.The speech recognition service URI is defined based on recognition modes and recognition languages:

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

<RECOGNITION_MODE>는 인식 모드를 지정하며, interactive, conversation 또는 dictation 값 중 하나여야 합니다.<RECOGNITION_MODE> specifies the recognition mode and must be one of the following values: interactive, conversation, or dictation. URI에 필요한 리소스 경로입니다.It's a required resource path in the URI. 자세한 내용은 인식 모드를 참조하세요.For more information, see Recognition modes.

<LANGUAGE_TAG>는 쿼리 문자열의 필수 매개 변수입니다.<LANGUAGE_TAG> is a required parameter in the query string. 오디오 변환에 대한 대상 언어를 정의합니다(예: 영어(미국)의 경우 en-US).It defines the target language for audio conversion: for example, en-US for English (United States). 자세한 내용은 인식 언어를 참조하세요.For more information, see Recognition languages.

<OUTPUT_FORMAT>은 쿼리 문자열의 선택적 매개 변수입니다.<OUTPUT_FORMAT> is an optional parameter in the query string. 허용되는 값은 simpledetailed입니다.Its allowed values are simple and detailed. 기본적으로 서비스는 결과를 simple 형식으로 반환합니다.By default, the service returns results in simple format. 자세한 내용은 출력 형식을 참조하세요.For more information, see Output format.

다음 표에는 서비스 URI에 대한 몇 가지 예가 나와 있습니다.Some examples of service URIs are listed in the following table.

인식 모드Recognition mode 언어Language 출력 형식Output format 서비스 URIService URI
interactive pt-BRpt-BR 기본값Default https://speech.platform.bing.com/speech/recognition/interactive/cognitiveservices/v1?language=pt-BR
conversation ko-KRen-US DetailedDetailed https://speech.platform.bing.com/speech/recognition/conversation/cognitiveservices/v1?language=en-US&format=detailed
dictation fr-FRfr-FR 간단한Simple https://speech.platform.bing.com/speech/recognition/dictation/cognitiveservices/v1?language=fr-FR&format=simple

참고

서비스 URI는 응용 프로그램에서 REST API를 사용하여 음성 인식 서비스를 호출하는 경우에만 필요합니다.The service URI is needed only when your application uses REST APIs to call the speech recognition service. 클라이언트 라이브러리 중 하나를 사용하는 경우 일반적으로 사용되는 URI에 대해 알고 있을 필요가 없습니다.If you use one of the client libraries, you usually don't need to know which URI is used. 클라이언트 라이브러리에서 특정 클라이언트 라이브러리에만 적용할 수 있는 별도의 서비스 URI를 사용할 수 있습니다.The client libraries might use different service URIs, which are applicable only for a specific client library. 자세한 내용은 선택한 클라이언트 라이브러리를 참조하세요.For more information, see the client library of your choice.

헤더 요청Request headers

요청 헤더에 설정해야 하는 필드는 다음과 같습니다.The following fields must be set in the request header:

  • Ocp-Apim-Subscription-Key: 서비스를 호출할 때마다 Ocp-Apim-Subscription-Key 헤더에 구독 키를 전달해야 합니다.Ocp-Apim-Subscription-Key: Each time that you call the service, you must pass your subscription key in the Ocp-Apim-Subscription-Key header. Speech Service는 구독 키 대신 권한 부여 토큰을 전달하는 기능도 지원합니다.Speech Service also supports passing authorization tokens instead of subscription keys. 자세한 내용은 인증을 참조하세요.For more information, see Authentication.
  • Content-type: Content-type 필드는 오디오 스트림의 형식과 코덱을 설명합니다.Content-type: The Content-type field describes the format and codec of the audio stream. 현재 WAV 파일과 PCM 모노 16000 인코딩만 지원됩니다.Currently, only WAV file and PCM Mono 16000 encoding is supported. 이 형식에 대한 Content-type 값은 audio/wav; codec=audio/pcm; samplerate=16000입니다.The Content-type value for this format is audio/wav; codec=audio/pcm; samplerate=16000.

Transfer-Encoding 필드는 선택 사항입니다.The Transfer-Encoding field is optional. 이 필드가 chunked로 설정되면 오디오를 작은 청크로 분할할 수 있습니다.If you set this field to chunked, you can chop the audio into small chunks. 자세한 내용은 청크 분할 전송을 참조하세요.For more information, see Chunked transfer.

요청 헤더 샘플은 다음과 같습니다.The following is a sample request header:

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

서비스에 요청 보내기Send a request to the service

다음 예제에서는 Speech REST 엔드포인트에 음성 인식 요청을 보내는 방법을 보여 줍니다.The following example shows how to send a speech recognition request to Speech REST endpoints. interactive 인식 모드를 사용합니다.It uses the interactive recognition mode.

참고

YOUR_AUDIO_FILE을 미리 녹음된 오디오 파일의 경로로 바꾸고,Replace YOUR_AUDIO_FILE with the path to your prerecorded audio file. YOUR_SUBSCRIPTION_KEY를 사용자 고유의 구독 키로 바꾸세요.Replace YOUR_SUBSCRIPTION_KEY with your own subscription key.


$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

음성 인식 응답 처리Process the speech recognition response

요청이 처리되면 Speech Service에서 응답의 결과를 JSON 형식으로 반환합니다.After processing the request, Speech Service returns the results in a response as JSON format.

참고

앞의 코드에서 오류가 반환되면 문제 해결을 참조하여 가능한 원인을 찾습니다.If the previous code returns an error, see Troubleshooting to locate the possible cause.

다음 코드 조각에서는 스트림에서 응답을 읽는 방법에 대한 예를 보여 줍니다.The following code snippet shows an example of how you can read the response from the stream.

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

JSON 응답 샘플은 다음과 같습니다.The following sample is a JSON response:

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."
  }]
}

제한 사항Limitations

REST API에는 몇 가지 제한 사항이 있습니다.The REST API has some limitations:

  • 최대 15초의 오디오 스트림만 지원합니다.It supports audio stream only up to 15 seconds.
  • 인식하는 동안 중간 결과를 지원하지 않습니다.It doesn't support intermediate results during recognition. 사용자가 최종 인식 결과만 받습니다.Users receive only the final recognition result.

이러한 제한 사항을 제거하려면 Speech 클라이언트 라이브러리를 사용합니다.To remove these limitations, use Speech client libraries. 또는 Speech WebSocket 프로토콜을 직접 사용할 수도 있습니다.Or you can work directly with the Speech WebSocket protocol.

다음 단계What's next

라이선스License

Cognitive Services SDK 및 샘플은 모두 MIT 라이선스를 통해 사용이 허가됩니다.All Cognitive Services SDKs and samples are licensed with the MIT License. 자세한 내용은 라이선스를 참조하세요.For more information, see License.