Metin okuma REST API'si

Konuşma tanıma hizmeti, rest API kullanarak metni sentezlenmiş konuşmaya dönüştürmenize ve bölge için desteklenen seslerin listesini almanıza olanak tanır. Bu makalede yetkilendirme seçenekleri, sorgu seçenekleri, isteği yapılandırma ve yanıtı yorumlama hakkında bilgi ediniyorsunuz.

Konuşmayı metne dönüştürme REST API'si birçok yerel ayarda nöral metinden konuşma seslerine desteği sağlar. Kullanılabilir her uç nokta bir bölgeyle ilişkilendirilir. Kullanmayı planladığınız uç nokta veya bölge için Konuşma kaynak anahtarı gereklidir. Daha fazla bilgi için bağlantılar aşağıdadır:

• Seslerin tam listesi için bkz . Konuşma hizmeti için dil ve ses desteği.
• Bölgesel kullanılabilirlik hakkında bilgi için bkz . Konuşma hizmeti tarafından desteklenen bölgeler.
• 21Vianet uç noktaları tarafından sağlanan Azure Kamu ve Microsoft Azure için bağımsız bulutlar hakkındaki bu makaleye bakın.

REST API'sini konuşmak için metni kullanmadan önce, hizmete erişmek için kimlik doğrulamasının bir parçası olarak belirteç değişimini tamamlamanız gerektiğini anlayın. Daha fazla bilgi için bkz. Kimlik doğrulaması.

Seslerin listesini alma

Belirli bir bölge veya uç nokta için seslerin tam listesini almak için uç noktayı kullanabilirsiniz tts.speech.microsoft.com/cognitiveservices/voices/list . Bu bölgenin ses listesini almak için ses listesi uç noktasına bir bölge öneki ekleyin. Örneğin, bölgenin ses listesini almak için westus uç noktayı kullanın https://westus.tts.speech.microsoft.com/cognitiveservices/voices/list . Desteklenen tüm bölgelerin listesi için bölgeler belgelerine bakın.

İstek üst bilgileri

Bu tabloda metin okuma istekleri için gerekli ve isteğe bağlı üst bilgiler listeleniyor:

Request body

Bu uç noktaya yönelik istekler için GET gövde gerekli değildir.

Örnek isteği

Bu istek yalnızca bir yetkilendirme üst bilgisi gerektirir:

GET /cognitiveservices/voices/list HTTP/1.1

Host: westus.tts.speech.microsoft.com
Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY

Aşağıda örnek bir curl komutu verilmişti:

curl --location --request GET 'https://YOUR_RESOURCE_REGION.tts.speech.microsoft.com/cognitiveservices/voices/list' \
--header 'Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY'

Örnek yanıt

Desteklenen tüm yerel ayarları, sesleri, cinsiyeti, stilleri ve diğer ayrıntıları içeren bir JSON gövdesine sahip bir yanıt almanız gerekir. WordsPerMinute Her ses için özelliği, çıkış konuşmasının uzunluğunu tahmin etmek için kullanılabilir. Bu JSON örneği, yanıtın yapısını göstermek için kısmi sonuçları gösterir:

[  
    // Redacted for brevity
    {
        "Name": "Microsoft Server Speech Text to Speech Voice (en-US, JennyNeural)",
        "DisplayName": "Jenny",
        "LocalName": "Jenny",
        "ShortName": "en-US-JennyNeural",
        "Gender": "Female",
        "Locale": "en-US",
        "LocaleName": "English (United States)",
        "StyleList": [
          "assistant",
          "chat",
          "customerservice",
          "newscast",
          "angry",
          "cheerful",
          "sad",
          "excited",
          "friendly",
          "terrified",
          "shouting",
          "unfriendly",
          "whispering",
          "hopeful"
        ],
        "SampleRateHertz": "24000",
        "VoiceType": "Neural",
        "Status": "GA",
        "ExtendedPropertyMap": {
          "IsHighQuality48K": "True"
        },
        "WordsPerMinute": "152"
    },
    // Redacted for brevity
    {
        "Name": "Microsoft Server Speech Text to Speech Voice (en-US, JennyMultilingualNeural)",
        "DisplayName": "Jenny Multilingual",
        "LocalName": "Jenny Multilingual",
        "ShortName": "en-US-JennyMultilingualNeural",
        "Gender": "Female",
        "Locale": "en-US",
        "LocaleName": "English (United States)",
        "SecondaryLocaleList": [
          "de-DE",
          "en-AU",
          "en-CA",
          "en-GB",
          "es-ES",
          "es-MX",
          "fr-CA",
          "fr-FR",
          "it-IT",
          "ja-JP",
          "ko-KR",
          "pt-BR",
          "zh-CN"
        ],
        "SampleRateHertz": "24000",
        "VoiceType": "Neural",
        "Status": "GA",
        "WordsPerMinute": "190"
    },
    // Redacted for brevity
    {
        "Name": "Microsoft Server Speech Text to Speech Voice (ga-IE, OrlaNeural)",
        "DisplayName": "Orla",
        "LocalName": "Orla",
        "ShortName": "ga-IE-OrlaNeural",
        "Gender": "Female",
        "Locale": "ga-IE",
        "LocaleName": "Irish (Ireland)",
        "SampleRateHertz": "24000",
        "VoiceType": "Neural",
        "Status": "GA",
        "WordsPerMinute": "139"
    },
    // Redacted for brevity
    {
        "Name": "Microsoft Server Speech Text to Speech Voice (zh-CN, YunxiNeural)",
        "DisplayName": "Yunxi",
        "LocalName": "云希",
        "ShortName": "zh-CN-YunxiNeural",
        "Gender": "Male",
        "Locale": "zh-CN",
        "LocaleName": "Chinese (Mandarin, Simplified)",
        "StyleList": [
          "narration-relaxed",
          "embarrassed",
          "fearful",
          "cheerful",
          "disgruntled",
          "serious",
          "angry",
          "sad",
          "depressed",
          "chat",
          "assistant",
          "newscast"
        ],
        "SampleRateHertz": "24000",
        "VoiceType": "Neural",
        "Status": "GA",
        "RolePlayList": [
          "Narrator",
          "YoungAdultMale",
          "Boy"
        ],
        "WordsPerMinute": "293"
    },
    // Redacted for brevity
]

HTTP durum kodu

Her yanıtın HTTP durum kodu başarılı veya yaygın hataları gösterir.

Metni konuşmaya dönüştürme

Uç nokta, cognitiveservices/v1 Konuşma Sentezi biçimlendirme dilini (SSML) kullanarak metni konuşmaya dönüştürmenizi sağlar.

Bölgeler ve uç noktalar

Bu bölgeler, REST API aracılığıyla metin okuma için desteklenir. Konuşma kaynak bölgenizle eşleşen uç noktayı seçtiğinizden emin olun.

Önceden oluşturulmuş sinir sesleri

Sinir seslerinin bölgeye veya uç noktaya göre kullanılabilirliğini belirlemek için bu tabloyu kullanın:

Özel nöral sesler

Özel bir nöral ses yazı tipi oluşturduysanız, oluşturduğunuz uç noktayı kullanın. Aşağıdaki uç noktaları da kullanabilirsiniz. değerini nöral ses modelinizin dağıtım kimliğiyle değiştirin {deploymentId} .

Uzun Ses API'si

Uzun Ses API'sini benzersiz uç noktaları olan birden çok bölgede kullanabilirsiniz:

İstek üst bilgileri

Bu tabloda metin okuma istekleri için gerekli ve isteğe bağlı üst bilgiler listeleniyor:

Request body

Özel bir sinir sesi kullanıyorsanız, isteğin gövdesi düz metin (ASCII veya UTF-8) olarak gönderilebilir. Aksi takdirde, her POST isteğin gövdesi SSML olarak gönderilir. SSML, konuşma metni özelliğinin döndürdüğü sentezlenmiş konuşmanın sesini ve dilini seçmenize olanak tanır. Desteklenen seslerin tam listesi için bkz . Konuşma hizmeti için dil ve ses desteği.

Örnek isteği

Bu HTTP isteği, sesi ve dili belirtmek için SSML kullanır. Gövde uzunluğu uzunsa ve sonuçta elde edilen ses 10 dakikayı aşarsa, 10 dakikaya kesilir. Başka bir deyişle ses uzunluğu 10 dakikayı aşamaz.

POST /cognitiveservices/v1 HTTP/1.1

X-Microsoft-OutputFormat: riff-24khz-16bit-mono-pcm
Content-Type: application/ssml+xml
Host: westus.tts.speech.microsoft.com
Content-Length: <Length>
Authorization: Bearer [Base64 access_token]
User-Agent: <Your application name>

<speak version='1.0' xml:lang='en-US'><voice xml:lang='en-US' xml:gender='Male'
    name='en-US-ChristopherNeural'>
        I'm excited to try text to speech!
</voice></speak>

^* İçerik Uzunluğu için kendi içerik uzunluğunuzu kullanmanız gerekir. Çoğu durumda, bu değer otomatik olarak hesaplanır.

HTTP durum kodu

Her yanıtın HTTP durum kodu başarılı veya yaygın hataları gösterir:

HTTP durumu ise 200 OK, yanıtın gövdesi istenen biçimde bir ses dosyası içerir. Bu dosya aktarıldıkçe, arabelleğe kaydedildikçe veya bir dosyaya kaydedildikçe oynatılabilir.

Ses çıkışları

Desteklenen akış ve akışsız ses biçimleri her istekte üst bilgi olarak X-Microsoft-OutputFormat gönderilir. Her biçim bir bit hızı ve kodlama türü içerir. Konuşma hizmeti 48 kHz, 24 kHz, 16 kHz ve 8 kHz ses çıkışlarını destekler. Önceden oluşturulmuş her nöral ses modeli 24kHz ve yüksek doğrulukta 48kHz olarak kullanılabilir.

amr-wb-16000hz
audio-16khz-16bit-32kbps-mono-opus
audio-16khz-32kbitrate-mono-mp3
audio-16khz-64kbitrate-mono-mp3
audio-16khz-128kbitrate-mono-mp3
audio-24khz-16bit-24kbps-mono-opus
audio-24khz-16bit-48kbps-mono-opus
audio-24khz-48kbitrate-mono-mp3
audio-24khz-96kbitrate-mono-mp3
audio-24khz-160kbitrate-mono-mp3
audio-48khz-96kbitrate-mono-mp3
audio-48khz-192kbitrate-mono-mp3
ogg-16khz-16bit-mono-opus
ogg-24khz-16bit-mono-opus
ogg-48khz-16bit-mono-opus
raw-8khz-8bit-mono-alaw
raw-8khz-8bit-mono-mulaw
raw-8khz-16bit-mono-pcm
raw-16khz-16bit-mono-pcm
raw-16khz-16bit-mono-truesilk
raw-22050hz-16bit-mono-pcm
raw-24khz-16bit-mono-pcm
raw-24khz-16bit-mono-truesilk
raw-44100hz-16bit-mono-pcm
raw-48khz-16bit-mono-pcm
webm-16khz-16bit-mono-opus
webm-24khz-16bit-24kbps-mono-opus
webm-24khz-16bit-mono-opus

riff-8khz-8bit-mono-alaw
riff-8khz-8bit-mono-mulaw
riff-8khz-16bit-mono-pcm
riff-22050hz-16bit-mono-pcm
riff-24khz-16bit-mono-pcm
riff-44100hz-16bit-mono-pcm
riff-48khz-16bit-mono-pcm

Kimlik Doğrulaması

Her istek için bir yetkilendirme üst bilgisi gerekir. Bu tabloda her özellik için hangi üst bilgilerin desteklendiği gösterilmektedir:

Üst bilgiyi kullanırken Ocp-Apim-Subscription-Key yalnızca kaynak anahtarınız sağlanmalıdır. Örneğin:

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

Üst bilgiyi kullanırken Authorization: Bearer uç noktaya bir istekte issueToken bulunmanız gerekir. Bu istekte, kaynak anahtarınızı 10 dakika boyunca geçerli olan bir erişim belirteci ile değiştirirsiniz.

Bir diğer seçenek de üst bilgiyi kullanan ancak Microsoft Entra Kimliği aracılığıyla verilen bir belirteçle Microsoft Entra kimlik doğrulamasını Authorization: Bearer kullanmaktır. Bkz . Microsoft Entra kimlik doğrulamayı kullanma.

Erişim belirteci alma

Erişim belirteci almak için issueToken ve kaynak anahtarınızı kullanarak Ocp-Apim-Subscription-Key uç noktaya bir istekte bulunmanız gerekir.

Uç issueToken nokta şu biçime sahiptir:

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

değerini aboneliğinizin bölgesiyle eşleşen tanımlayıcıyla değiştirin<REGION_IDENTIFIER>.

Erişim belirteci isteğinizi oluşturmak için aşağıdaki örnekleri kullanın.

HTTP örneği

Bu örnek, belirteç almak için basit bir HTTP isteğidir. değerini Konuşma hizmeti için kaynak anahtarınızla değiştirin YOUR_SUBSCRIPTION_KEY . Aboneliğiniz Batı ABD bölgesinde değilse üst bilgiyi bölgenizin ana bilgisayar adıyla değiştirin 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

Yanıtın gövdesi, erişim belirtecini JSON Web Belirteci (JWT) biçiminde içerir.

PowerShell örneği

Bu örnek, erişim belirteci almak için basit bir PowerShell betiğidir. değerini Konuşma hizmeti için kaynak anahtarınızla değiştirin YOUR_SUBSCRIPTION_KEY . Aboneliğinizle eşleşen bölge için doğru uç noktayı kullandığınızdan emin olun. Bu örnek şu anda Batı ABD olarak ayarlanmıştır.

$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 örneği

cURL, Linux'ta (ve Linux için Windows Alt Sistemi) kullanılabilen bir komut satırı aracıdır. Bu cURL komutu, erişim belirtecinin nasıl alınacaklarını gösterir. değerini Konuşma hizmeti için kaynak anahtarınızla değiştirin YOUR_SUBSCRIPTION_KEY . Aboneliğinizle eşleşen bölge için doğru uç noktayı kullandığınızdan emin olun. Bu örnek şu anda Batı ABD olarak ayarlanmıştır.

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# örneği

Bu C# sınıfı, erişim belirtecinin nasıl alınıyor olduğunu gösterir. Sınıfın örneğini oluştururken Konuşma hizmeti için kaynak anahtarınızı geçirin. Aboneliğiniz Batı ABD bölgesinde değilse değerini aboneliğinizin bölgesiyle eşleşecek şekilde değiştirin 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 örneği

# 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)

Erişim belirtecini kullanma

Erişim belirteci, hizmete üst bilgi olarak Authorization: Bearer <TOKEN> gönderilmelidir. Her erişim belirteci 10 dakika boyunca geçerlidir. İstediğiniz zaman yeni bir belirteç alabilirsiniz, ancak ağ trafiğini ve gecikme süresini en aza indirmek için aynı belirteci dokuz dakika boyunca kullanmanızı öneririz.

Kısa ses için Konuşmayı metne dönüştürme REST API'sine yönelik örnek bir HTTP isteği aşağıda verilmiştir:

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...

Microsoft Entra doğrulamasını kullanın

Kısa ses için Konuşmayı metne dönüştürme REST API'siyle Microsoft Entra kimlik doğrulamasını kullanmak için bir erişim belirteci oluşturmanız gerekir. Kaynak Kimliği ve Microsoft Entra erişim belirtecini içeren erişim belirtecini alma adımları, Konuşma SDK'sı kullanılırken gerçekleştirilir. Microsoft Entra kimlik doğrulamasını kullanma buradaki adımları izleyin

Kaynak kimliği ve Microsoft Entra erişim belirteci alındıktan sonra gerçek erişim belirteci şu biçimde oluşturulabilir:

aad#YOUR_RESOURCE_ID#YOUR_MICROSOFT_ENTRA_ACCESS_TOKEN

Kaynak kimliği ile erişim belirteci arasında "aad#" ön ekini ve "#" (karma) ayırıcısını eklemeniz gerekir.

Kısa ses için Konuşmayı metne dönüştürme REST API'sine yönelik örnek bir HTTP isteği aşağıda verilmiştir:

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...

Belirteç ömrü de dahil olmak üzere Microsoft Entra erişim belirteçleri hakkında daha fazla bilgi edinmek için Microsoft kimlik platformu Access belirteçleri'ni ziyaret edin.

Sonraki adımlar

• Ücretsiz bir Azure hesabı oluşturun
• Özel nöral ses ile çalışmaya başlama
• Toplu sentez