짧은 오디오용 음성 텍스트 변환 REST API

짧은 오디오를 위한 음성 텍스트 변환 REST API의 사용 사례는 제한적입니다. 음성 SDK를 사용할 수 없는 경우에만 사용합니다.

짧은 오디오용 음성 텍스트 변환 REST API를 사용하기 전에 다음 제한 사항을 고려하세요.

짧은 오디오의 경우 음성 텍스트 변환 REST API를 사용하기 전에 서비스에 액세스하려면 인증의 일부로 토큰 교환을 완료해야 합니다. 자세한 내용은 인증을 참조 하세요.

지역 및 엔드포인트

짧은 오디오용 REST API의 엔드포인트는 다음과 같은 형식입니다.

https://<REGION_IDENTIFIER>.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1

<REGION_IDENTIFIER>를 Speech 리소스 지역과 일치하는 식별자로 바꿉니다.

참고 항목

Azure Government 및 21Vianet 엔드포인트에 의해 운영되는 Microsoft Azur 소버린 클라우드에 대한 이 문서를 참조하세요.

오디오 형식

오디오는 HTTP POST 요청 본문에서 전송됩니다. 이 테이블의 형식 중 하나여야 합니다.

형식 Codec 비트 전송률: 샘플 속도
WAV PCM 256kbps 16kHz, mono
OGG OPUS 256kbps 16kHz, mono

참고 항목

위의 형식은 Speech Service의 짧은 비디오용 REST API 및 WebSocket을 통해 지원됩니다. Speech SDK는 PCM 코덱을 사용하는 WAV 형식 및 다른 형식을 지원합니다.

요청 헤더

이 표에는 음성 텍스트 변환 요청에 대한 필수 헤더 및 선택적 헤더가 나와 있습니다.

헤더 설명 필수 또는 선택 사항
Ocp-Apim-Subscription-Key Speech Service에 대한 리소스 키입니다. 이 헤더 또는 Authorization가 필요합니다.
Authorization 단어 Bearer앞에 오는 권한 부여 토큰입니다. 자세한 내용은 인증을 참조 하세요. 이 헤더 또는 Ocp-Apim-Subscription-Key가 필요합니다.
Pronunciation-Assessment 인식 결과에 발음 점수를 표시하기 위한 매개 변수를 지정합니다. 이러한 점수는 정확도, 유창성 및 완전성과 같은 지표를 사용하여 음성 입력의 발음 품질을 평가합니다.

이 매개 변수는 여러 개의 자세한 매개 변수를 포함하는 Base64로 인코딩된 JSON입니다. 이 헤더를 빌드하는 방법에 대한 자세한 내용은 발음 평가 매개 변수를 참조하세요.
선택 사항
Content-type 제공된 오디오 데이터의 형식과 코덱을 설명합니다. 허용되는 값은 audio/wav; codecs=audio/pcm; samplerate=16000audio/ogg; codecs=opus입니다. Required
Transfer-Encoding 단일 파일이 아닌 청크 분할된 오디오 데이터를 보내게 지정합니다. 오디오 데이터를 청크 분할하는 경우에만 이 헤더를 사용합니다. 선택 사항
Expect 청크 분할 전송을 사용하는 경우 Expect: 100-continue를 보냅니다. Speech Service는 초기 요청을 승인하고 더 많은 데이터를 기다립니다. 청크 분할된 오디오 데이터를 보내는 경우에 필요합니다.
Accept 제공하는 경우 application/json이어야 합니다. Speech Service는 JSON의 결과를 제공합니다. 일부 요청 프레임워크는 호환되지 않는 기본값을 제공합니다. 항상 Accept를 포함하는 것이 좋습니다. 선택 사항이지만 권장합니다.

쿼리 매개 변수

다음 매개 변수는 REST 요청의 쿼리 문자열에 포함할 수 있습니다.

참고 항목

4xx HTTP 오류를 받지 않으려면 언어 매개 변수를 URL에 추가해야 합니다. 예를 들어 미국 서부 엔드포인트를 통해 미국 영어로 설정된 언어는 https://westus.stt.speech.microsoft.com/speech/recognition/conversation/cognitiveservices/v1?language=en-US입니다.

매개 변수 설명 필수 또는 선택 사항
language 인식되는 음성 언어를 식별합니다. 지원되는 언어를 참조 하세요. Required
format 결과 형식을 지정합니다. 허용되는 값은 simpledetailed입니다. 간단한 결과에는 ,DisplayText, Offset및 .가 포함됩니다RecognitionStatusDuration. 자세한 응답에는 표시 텍스트의 네 가지 표현이 포함되어 있습니다. 기본 설정은 simple입니다. 선택 사항
profanity 인식 결과에서 욕설을 처리하는 방법을 지정합니다. 허용되는 값은 다음과 같습니다.

masked - 불경한 언어를 별표로 바꿉니다.
removed - 모든 불경한 언어를 결과에서 제거합니다.
raw - 불경한 언어를 결과에 포함합니다.

기본 설정은 masked입니다.
선택 사항
cid Speech Studio를 사용하여 사용자 지정 모델을 만드는 경우 배포 페이지의 엔드포인트 ID 값을 활용할 수 있습니다. 엔드포인트 ID 값을 cid 쿼리 문자열 매개 변수에 대한 인수로 사용합니다. 선택 사항

발음 평가 매개 변수

다음 표에는 발음 평가에 대한 필수 및 선택적 매개 변수가 나와 있습니다.

매개 변수 설명 필수 또는 선택 사항
ReferenceText 발음을 평가하는 기준 텍스트입니다. Required
GradingSystem 점수 보정을 위한 지점 시스템입니다. 시스템은 FivePoint 0-5 부동 소수점 점수를 HundredMark 제공하고 0-100 부동 소수점 점수를 제공합니다. 기본값: FivePoint. 선택 사항
Granularity 평가 세분성입니다. 허용되는 값은 다음과 같습니다.

Phoneme - 전체 텍스트, 단어 및 음소 수준의 점수를 표시합니다.
Word - 전체 텍스트 및 단어 수준의 점수를 표시합니다.
FullText - 전체 텍스트 수준에서만 점수를 표시합니다.

기본 설정은 Phoneme입니다.
선택 사항
Dimension 출력 조건을 정의합니다. 허용되는 값은 다음과 같습니다.

Basic - 정확도 점수만 표시합니다.
Comprehensive - 더 많은 차원(예: 전체 텍스트 수준의 유창성 점수 및 완전성 점수, 단어 수준의 오류 유형)에 대한 점수를 표시합니다.

다양한 점수 차원 및 단어 오류 유형의 정의에 대한 자세한 내용은 응답 속성을 참조하세요. 기본 설정은 Basic입니다.
선택 사항
EnableMiscue 오독(miscue) 계산을 사용합니다. 이 매개 변수를 사용하면 발음된 단어가 참조 텍스트와 비교됩니다. 비교에 따라 누락 또는 삽입으로 표시됩니다. 허용되는 값은 FalseTrue입니다. 기본 설정은 False입니다. 선택 사항
ScenarioId 사용자 지정된 지점 시스템을 나타내는 GUID입니다. 선택 사항

발음 평가 매개 변수가 포함된 JSON 예제는 다음과 같습니다.

{
  "ReferenceText": "Good morning.",
  "GradingSystem": "HundredMark",
  "Granularity": "FullText",
  "Dimension": "Comprehensive"
}

다음 샘플 코드에서는 발음 평가 매개 변수를 헤더에 빌드하는 Pronunciation-Assessment 방법을 보여 줍니다.

var pronAssessmentParamsJson = $"{{\"ReferenceText\":\"Good morning.\",\"GradingSystem\":\"HundredMark\",\"Granularity\":\"FullText\",\"Dimension\":\"Comprehensive\"}}";
var pronAssessmentParamsBytes = Encoding.UTF8.GetBytes(pronAssessmentParamsJson);
var pronAssessmentHeader = Convert.ToBase64String(pronAssessmentParamsBytes);

오디오 데이터를 게시하는 동안 스트리밍(청크 분할 전송)을 업로드하는 것이 매우 좋습니다. 이렇게 하면 대기 시간을 크게 줄일 수 있습니다. 스트리밍을 사용하도록 설정하는 방법에 대한 자세한 내용은 다양한 프로그래밍 언어의 샘플 코드를 참조하세요.

참고 항목

자세한 내용은 발음 평가를 참조하세요.

샘플 요청

다음 샘플에는 호스트 이름과 필수 헤더가 포함되어 있습니다. 서비스에는 이 샘플에 포함되지 않은 오디오 데이터도 필요합니다. 앞에서 언급한 대로 청크 분할은 권장되지만 필수는 아닙니다.

POST speech/recognition/conversation/cognitiveservices/v1?language=en-US&format=detailed HTTP/1.1
Accept: application/json;text/xml
Content-Type: audio/wav; codecs=audio/pcm; samplerate=16000
Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY
Host: westus.stt.speech.microsoft.com
Transfer-Encoding: chunked
Expect: 100-continue

발음 평가를 사용하도록 설정하기 위해 다음 헤더를 추가할 수 있습니다. 이 헤더를 빌드하는 방법에 대한 자세한 내용은 발음 평가 매개 변수를 참조하세요.

Pronunciation-Assessment: eyJSZWZlcm...

HTTP 상태 코드

각 응답에 대한 HTTP 상태 코드는 성공 또는 일반적인 오류를 나타냅니다.

HTTP 상태 코드 설명 가능한 이유
100 계속 초기 요청이 수락됩니다. 나머지 데이터 전송을 진행합니다. (이 코드는 청크 분할 전송에 사용됩니다.)
200 OK 요청에 성공했습니다. 응답 본문은 JSON 개체입니다.
400 Bad request 언어 코드가 제공되지 않았거나, 언어가 지원되지 않거나. 오디오 파일이 잘못되었습니다.
401 Unauthorized 리소스 키 또는 권한 부여 토큰이 지정된 지역에서 잘못되었거나 엔드포인트가 잘못되었습니다.
403 금지 리소스 키 또는 권한 부여 토큰이 없습니다.

샘플 응답

simple 인식에 대한 일반적인 응답은 다음과 같습니다.

{
  "RecognitionStatus": "Success",
  "DisplayText": "Remind me to buy 5 pencils.",
  "Offset": "1236645672289",
  "Duration": "1236645672289"
}

detailed 인식에 대한 일반적인 응답은 다음과 같습니다.

{
  "RecognitionStatus": "Success",
  "Offset": "1236645672289",
  "Duration": "1236645672289",
  "NBest": [
    {
      "Confidence": 0.9052885,
      "Display": "What's the weather like?",
      "ITN": "what's the weather like",
      "Lexical": "what's the weather like",
      "MaskedITN": "what's the weather like"
    },
    {
      "Confidence": 0.92459863,
      "Display": "what is the weather like",
      "ITN": "what is the weather like",
      "Lexical": "what is the weather like",
      "MaskedITN": "what is the weather like"
    }
  ]
}

발음 평가를 사용하는 인식에 대한 일반적인 응답은 다음과 같습니다.

{
  "RecognitionStatus": "Success",
  "Offset": "400000",
  "Duration": "11000000",
  "NBest": [
      {
        "Confidence" : "0.87",
        "Lexical" : "good morning",
        "ITN" : "good morning",
        "MaskedITN" : "good morning",
        "Display" : "Good morning.",
        "PronScore" : 84.4,
        "AccuracyScore" : 100.0,
        "FluencyScore" : 74.0,
        "CompletenessScore" : 100.0,
        "Words": [
            {
              "Word" : "Good",
              "AccuracyScore" : 100.0,
              "ErrorType" : "None",
              "Offset" : 500000,
              "Duration" : 2700000
            },
            {
              "Word" : "morning",
              "AccuracyScore" : 100.0,
              "ErrorType" : "None",
              "Offset" : 5300000,
              "Duration" : 900000
            }
        ]
      }
  ]
}

응답 속성

결과는 JSON으로 제공됩니다. simple 형식에 포함되는 최상위 필드는 다음과 같습니다.

속성 설명
RecognitionStatus 상태(예: 인식 성공에 Success)입니다. 다음 표를 참조하세요.
DisplayText 대문자 표시, 문장 부호, 역 텍스트 정규화 및 불경한 언어 마스킹 후에 인식된 텍스트입니다. 성공에만 존재합니다. 역 텍스트 정규화는 "two hundred"의 경우 200 또는 "doctor smith"의 경우 "Dr. Smith"와 같이 음성 텍스트를 더 짧은 형식으로 변환하는 것입니다.
Offset 인식된 음성이 오디오 스트림에서 시작되는 시간(100나노초 단위)입니다.
Duration 오디오 스트림에서 인식된 음성의 기간(100나노초 단위)입니다.

RecognitionStatus 필드에 포함될 수 있는 값은 다음과 같습니다.

상태 설명
Success 성공적으로 인식했고 DisplayText 필드가 있습니다.
NoMatch 오디오 스트림에서 음성이 감지되었지만 대상 언어의 단어가 일치하지 않습니다. 이 상태는 일반적으로 인식 언어가 사용자가 말하는 언어와 다르다는 것을 의미합니다.
InitialSilenceTimeout 오디오 스트림의 시작 부분에는 무음만 포함되었으며, 음성을 기다리는 동안 서비스 시간이 초과되었습니다.
BabbleTimeout 오디오 스트림의 시작 부분에는 소음만 포함되었으며, 음성을 기다리는 동안 서비스 시간이 초과되었습니다.
Error 인식 서비스에 내부 오류가 발생하여 계속할 수 없습니다. 가능하면 다시 시도하세요.

참고 항목

오디오가 욕설로만 구성되어 있고 profanity 쿼리 매개 변수가 remove로 설정되어 있는 경우 서비스는 음성 결과를 변환하지 않습니다.

형식에는 detailed 더 많은 형식의 인식된 결과가 포함됩니다. detailed 형식을 사용하는 경우NBest 목록의 각 결과에 대해 DisplayTextDisplay로 제공됩니다.

목록의 개체에는 다음이 NBest 포함될 수 있습니다.

속성 설명
Confidence 항목의 신뢰도 점수(0.0(신뢰 안 함)~1.0(완전 신뢰))입니다.
Lexical 인식된 텍스트의 어휘 형태, 즉 인식된 실제 단위입니다.
ITN 전화 번호, 숫자, 약어("doctor smith"에서 "dr smith"로) 및 기타 변환이 ​​적용된 인식된 텍스트의 ITN(역 텍스트 정규화) 또는 정규형입니다.
MaskedITN 요청된 경우 욕설 마스킹이 적용된 ITN 양식입니다.
Display 문장 부호와 대문자가 추가된 인식된 텍스트의 표시 형식입니다. 이 매개 변수는 형식이 simple로 설정된 경우 DisplayText에서 제공하는 것과 동일합니다.
AccuracyScore 음성의 발음 정확도입니다. 정확도는 음소가 원어민의 발음과 얼마나 일치하는지를 나타냅니다. 단어 및 전체 텍스트 수준의 정확도 점수는 음소 수준의 정확도 점수에서 집계됩니다.
FluencyScore 제공된 음성의 유창성입니다. 유창성은 음성이 원어민의 단어 간 자동 중단 사용과 얼마나 밀접하게 일치하는지를 나타냅니다.
CompletenessScore 텍스트 입력을 참조하는 발음 단어의 비율을 계산하여 결정되는 음성의 완전성입니다.
PronScore 제공된 음성의 발음 품질을 나타내는 전체 점수입니다. 이 점수는 가중치를 사용하여 AccuracyScore, FluencyScoreCompletenessScore에서 집계됩니다.
ErrorType ReferenceText와 비교하여 단어가 생략되었거나, 삽입되었거나, 잘못 발음되었는지 여부를 나타내는 값입니다. 가능한 값은 None(이 단어에 오류가 없음을 의미함), Omission, InsertionMispronunciation입니다.

청크 분할 전송

청크 분할 전송(Transfer-Encoding: chunked)은 인식 대기 시간을 줄이는 데 도움이 될 수 있습니다. 이를 통해 Speech Service에서 오디오 파일이 전송되는 동안 해당 파일의 처리를 시작할 수 있습니다. 짧은 오디오용 REST API는 부분 또는 중간 결과를 제공하지 않습니다.

다음 코드 샘플에서는 오디오를 청크로 분할하여 보내는 방법을 보여 줍니다. 오직 첫 번째 청크만 오디오 파일의 헤더를 포함해야 합니다. request는 적절한 REST 엔드포인트에 연결된 HttpWebRequest 개체입니다. audioFile 는 디스크의 오디오 파일 경로입니다.

var request = (HttpWebRequest)HttpWebRequest.Create(requestUri);
request.SendChunked = true;
request.Accept = @"application/json;text/xml";
request.Method = "POST";
request.ProtocolVersion = HttpVersion.Version11;
request.Host = host;
request.ContentType = @"audio/wav; codecs=audio/pcm; samplerate=16000";
request.Headers["Ocp-Apim-Subscription-Key"] = "YOUR_RESOURCE_KEY";
request.AllowWriteStreamBuffering = false;

using (var fs = new FileStream(audioFile, FileMode.Open, FileAccess.Read))
{
    // Open a request stream and write 1,024-byte chunks in the stream one at a time.
    byte[] buffer = null;
    int bytesRead = 0;
    using (var requestStream = request.GetRequestStream())
    {
        // Read 1,024 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);
        }

        requestStream.Flush();
    }
}

인증

각 요청에는 권한 부여 헤더가 필요합니다. 이 표에서는 각 기능에 대해 지원되는 헤더를 보여줍니다.

지원되는 인증 헤더 음성 텍스트 변환 텍스트 음성 변환
Ocp-Apim-Subscription-Key
Authorization: Bearer

Ocp-Apim-Subscription-Key 헤더를 사용하는 경우 리소스 키만 제공하면 됩니다. 예시:

'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'

Authorization: Bearer 헤더를 사용하는 경우 issueToken 엔드포인트에 요청해야 합니다. 이 요청에서는 10분 동안 유효한 액세스 토큰에 대한 리소스 키를 교환합니다.

액세스 토큰을 가져오는 방법

액세스 토큰을 가져오려면 Ocp-Apim-Subscription-Key 및 리소스 키를 사용하여 issueToken 엔드포인트에 요청해야 합니다.

issueToken 엔드포인트의 형식은 다음과 같습니다.

https://<REGION_IDENTIFIER>.api.cognitive.microsoft.com/sts/v1.0/issueToken

<REGION_IDENTIFIER>를 구독 지역과 일치하는 식별자로 바꿉니다.

다음 샘플을 사용하여 액세스 토큰 요청을 만듭니다.

HTTP 샘플

이 예제는 토큰을 가져오는 간단한 HTTP 요청입니다. YOUR_SUBSCRIPTION_KEY를 Speech Service에 대한 리소스 키로 바꿉니다. 구독이 미국 서부 지역에 없는 경우 헤더를 Host 해당 지역의 호스트 이름으로 바꿉시다.

POST /sts/v1.0/issueToken HTTP/1.1
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
Host: eastus.api.cognitive.microsoft.com
Content-type: application/x-www-form-urlencoded
Content-Length: 0

응답 본문에는 JWT(JSON Web Token) 형식의 액세스 토큰이 포함됩니다.

PowerShell 샘플

이 예제는 액세스 토큰을 가져오는 간단한 PowerShell 스크립트입니다. YOUR_SUBSCRIPTION_KEY를 Speech Service에 대한 리소스 키로 바꿉니다. 구독과 일치하는 지역에 올바른 엔드포인트를 사용해야 합니다. 이 예제는 현재 미국 서부로 설정됩니다.

$FetchTokenHeader = @{
  'Content-type'='application/x-www-form-urlencoded';
  'Content-Length'= '0';
  'Ocp-Apim-Subscription-Key' = 'YOUR_SUBSCRIPTION_KEY'
}

$OAuthToken = Invoke-RestMethod -Method POST -Uri https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken
 -Headers $FetchTokenHeader

# show the token received
$OAuthToken

cURL 샘플

cURL은 Linux(및 Linux용 Windows 하위 시스템)에서 사용할 수 있는 명령줄 도구입니다. 이 cURL 명령은 액세스 토큰을 가져오는 방법을 보여 줍니다. YOUR_SUBSCRIPTION_KEY를 Speech Service에 대한 리소스 키로 바꿉니다. 구독과 일치하는 지역에 올바른 엔드포인트를 사용해야 합니다. 이 예제는 현재 미국 서부로 설정됩니다.

curl -v -X POST \
 "https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken" \
 -H "Content-type: application/x-www-form-urlencoded" \
 -H "Content-Length: 0" \
 -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY"

C# 샘플

이 C# 클래스는 액세스 토큰을 가져오는 방법을 보여 줍니다. 이 클래스를 인스턴스화할 때 Speech Service에 대한 리소스 키를 전달합니다. 구독이 미국 서부 지역에 없는 경우 구독의 FetchTokenUri 지역과 일치하도록 값을 변경합니다.

public class Authentication
{
    public static readonly string FetchTokenUri =
        "https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken";
    private string subscriptionKey;
    private string token;

    public Authentication(string subscriptionKey)
    {
        this.subscriptionKey = subscriptionKey;
        this.token = FetchTokenAsync(FetchTokenUri, subscriptionKey).Result;
    }

    public string GetAccessToken()
    {
        return this.token;
    }

    private async Task<string> FetchTokenAsync(string fetchUri, string subscriptionKey)
    {
        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
            UriBuilder uriBuilder = new UriBuilder(fetchUri);

            var result = await client.PostAsync(uriBuilder.Uri.AbsoluteUri, null);
            Console.WriteLine("Token Uri: {0}", uriBuilder.Uri.AbsoluteUri);
            return await result.Content.ReadAsStringAsync();
        }
    }
}

Python 샘플

# Request module must be installed.
# Run pip install requests if necessary.
import requests

subscription_key = 'REPLACE_WITH_YOUR_KEY'


def get_token(subscription_key):
    fetch_token_url = 'https://eastus.api.cognitive.microsoft.com/sts/v1.0/issueToken'
    headers = {
        'Ocp-Apim-Subscription-Key': subscription_key
    }
    response = requests.post(fetch_token_url, headers=headers)
    access_token = str(response.text)
    print(access_token)

액세스 토큰을 사용하는 방법

액세스 토큰은 헤더로 Authorization: Bearer <TOKEN> 서비스에 전송되어야 합니다. 각 액세스 토큰은 10분 동안 유효합니다. 언제든지 새 토큰을 가져올 수 있지만, 네트워크 트래픽 및 대기 시간을 최소화하려면 동일한 토큰을 9분 동안 사용하는 것이 좋습니다.

다음은 짧은 오디오를 위한 음성 텍스트 변환 REST API에 대한 샘플 HTTP 요청입니다.

POST /cognitiveservices/v1 HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN
Host: westus.stt.speech.microsoft.com
Content-type: application/ssml+xml
Content-Length: 199
Connection: Keep-Alive

// Message body here...

다음 단계