API REST de conversão de texto em fala
O serviço de Fala permite que você converta o texto em fala sintetizada e obtenha uma lista de vozes com suporte para uma região usando uma API REST. Neste artigo, você aprenderá sobre opções de autorização, opções de consulta, como estruturar uma solicitação e como interpretar uma resposta.
Dica
Os casos de uso da API REST da conversão de texto em fala são limitados. Use-os somente quando não puder usar o SDK de Fala. Por exemplo, com o SDK de Fala, você pode assinar eventos para obter mais informações sobre o processamento de conversão de texto em fala e os resultados.
A API REST de conversão de texto em fala dá suporte a vozes neurais de conversão de texto em fala em muitas localidades. Cada ponto de extremidade disponível está associado a uma região. É necessária uma chave do recurso de Fala para o ponto de extremidade ou região que você planeja usar. Aqui estão os links para mais informações:
- Para obter uma lista completa de vozes, consulte Suporte a idiomas e voz para o serviço de Fala.
- Para obter informações sobre a disponibilidade regional, consulte Regiões com suporte do Speech Service.
- Para os pontos de extremidade do Azure Government e do Microsoft Azure operado pela 21Vianet, consulte esse artigo sobre nuvens soberanas.
Importante
Os custos variam para vozes neurais predefinidas (chamadas como Neural na página de preços) e vozes neurais personalizadas (chamadas como Neural Personalizada na página de preços). Para obter mais informações, confira Preços do serviço de Fala.
Antes de usar a API REST de conversão de texto em fala, saiba que você precisa concluir uma troca de token como parte da autenticação para acessar o serviço. Para obter mais informações, consulte Autenticação.
Obter uma lista de vozes
É possível usar o ponto de extremidade tts.speech.microsoft.com/cognitiveservices/voices/list para obter uma lista completa de vozes para uma região ou ponto de extremidade específico. Prefixe o ponto de extremidade de lista de vozes com uma região para obter uma lista de vozes para essa região. Por exemplo, para obter uma lista de vozes para a região westus, use o ponto de extremidade https://westus.tts.speech.microsoft.com/cognitiveservices/voices/list. Para obter uma lista de todas as regiões com suporte, consulte a documentação das regiões.
Observação
As vozes/estilos em versão prévia estão disponíveis somente em três regiões de serviço: Leste dos EUA, Oeste da Europa e Sudeste da Ásia.
Cabeçalhos da solicitação
Esta tabela lista os cabeçalhos obrigatórios e opcionais para solicitações de conversão de texto em fala:
| parâmetro | Descrição | Obrigatório ou opcional |
|---|---|---|
Ocp-Apim-Subscription-Key |
A chave do seu recurso de Fala. | Esse cabeçalho ou Authorization é obrigatório. |
Authorization |
Um token de autorização precedido pela palavra Bearer. Para obter mais informações, consulte Autenticação. |
Esse cabeçalho ou Ocp-Apim-Subscription-Key é obrigatório. |
Corpo da solicitação
Um corpo não é necessário para solicitações GET para este ponto de extremidade.
Solicitação de exemplo
Essa solicitação requer apenas um cabeçalho de autorização:
GET /cognitiveservices/voices/list HTTP/1.1
Host: westus.tts.speech.microsoft.com
Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY
Aqui está um exemplo de comando curl:
curl --location --request GET 'https://YOUR_RESOURCE_REGION.tts.speech.microsoft.com/cognitiveservices/voices/list' \
--header 'Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY'
Resposta de exemplo
Você deve receber uma resposta com um corpo JSON que inclua todas as localidades, vozes, gênero, estilos e outros detalhes com suporte. A propriedade WordsPerMinute para cada voz poderá ser utilizada para estimar a duração da fala de saída. Este exemplo JSON mostra resultados parciais para ilustrar a estrutura de uma resposta:
[
// 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
]
Códigos de status HTTP
O código de status HTTP para cada resposta indica sucesso ou erros comuns.
| Código de status HTTP | Descrição | Possível motivo |
|---|---|---|
| 200 | OK | A solicitação foi bem-sucedida. |
| 400 | Solicitação incorreta | Um parâmetro obrigatório está ausente, vazio ou nulo. Ou então, o valor passado como um parâmetro obrigatório ou opcional é inválido. Um motivo comum é um cabeçalho muito longo. |
| 401 | Não Autorizado | A solicitação não está autorizada. Verifique se a chave do recurso ou o token são válidos e se estão na região correta. |
| 429 | Número excessivo de solicitações | Você excedeu a cota ou a taxa de solicitações permitidas para seu recurso. |
| 502 | Gateway inválido | Há um problema de rede ou do lado do servidor. Esse status também pode indicar os cabeçalhos inválidos. |
Converter texto em fala
O ponto de extremidade cognitiveservices/v1 permite a conversão de texto em fala usando a SSML (Linguagem de Marcação de Síntese de Fala).
Regiões e endpoints
Essas regiões são suportadas para conversão de texto em fala através da API REST. Verifique se você selecionou o ponto de extremidade que corresponde à região do seu recurso de Fala.
Sintetização de Vozes predefinida
Use esta tabela para determinar a disponibilidade de vozes neurais por região ou ponto de extremidade:
| Região | Ponto de extremidade |
|---|---|
| Leste da Austrália | https://australiaeast.tts.speech.microsoft.com/cognitiveservices/v1 |
| Brazil South | https://brazilsouth.tts.speech.microsoft.com/cognitiveservices/v1 |
| Canadá Central | https://canadacentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| Centro dos EUA | https://centralus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Leste da Ásia | https://eastasia.tts.speech.microsoft.com/cognitiveservices/v1 |
| Leste dos EUA | https://eastus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Leste dos EUA 2 | https://eastus2.tts.speech.microsoft.com/cognitiveservices/v1 |
| França Central | https://francecentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| Centro-Oeste da Alemanha | https://germanywestcentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| Centro da Índia | https://centralindia.tts.speech.microsoft.com/cognitiveservices/v1 |
| Leste do Japão | https://japaneast.tts.speech.microsoft.com/cognitiveservices/v1 |
| Oeste do Japão | https://japanwest.tts.speech.microsoft.com/cognitiveservices/v1 |
| Jio Oeste da Índia | https://jioindiawest.tts.speech.microsoft.com/cognitiveservices/v1 |
| Coreia Central | https://koreacentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| Centro-Norte dos EUA | https://northcentralus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Norte da Europa | https://northeurope.tts.speech.microsoft.com/cognitiveservices/v1 |
| Leste da Noruega | https://norwayeast.tts.speech.microsoft.com/cognitiveservices/v1 |
| Centro-Sul dos Estados Unidos | https://southcentralus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Sudeste Asiático | https://southeastasia.tts.speech.microsoft.com/cognitiveservices/v1 |
| Suécia Central | https://swedencentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| Norte da Suíça | https://switzerlandnorth.tts.speech.microsoft.com/cognitiveservices/v1 |
| Oeste da Suíça | https://switzerlandwest.tts.speech.microsoft.com/cognitiveservices/v1 |
| Norte dos EAU | https://uaenorth.tts.speech.microsoft.com/cognitiveservices/v1 |
| Governo dos EUA do Arizona | https://usgovarizona.tts.speech.azure.us/cognitiveservices/v1 |
| Gov. dos EUA – Virgínia | https://usgovvirginia.tts.speech.azure.us/cognitiveservices/v1 |
| Sul do Reino Unido | https://uksouth.tts.speech.microsoft.com/cognitiveservices/v1 |
| Centro-Oeste dos EUA | https://westcentralus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Europa Ocidental | https://westeurope.tts.speech.microsoft.com/cognitiveservices/v1 |
| Oeste dos EUA | https://westus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Oeste dos EUA 2 | https://westus2.tts.speech.microsoft.com/cognitiveservices/v1 |
| Oeste dos EUA 3 | https://westus3.tts.speech.microsoft.com/cognitiveservices/v1 |
Dica
As vozes em versão prévia estão disponíveis somente nestas três regiões: Leste dos EUA, Oeste da Europa e Sudeste da Ásia.
Vozes neurais personalizadas
Caso tenha criado uma fonte de voz neural personalizada, use o ponto de extremidade que você criou. Você também pode usar os pontos de extremidade a seguir. Substitua {deploymentId} pela ID de implantação do seu modelo de voz neural.
| Região | Treinamento | Implantação | Ponto de extremidade |
|---|---|---|---|
| Leste da Austrália | Sim | Sim | https://australiaeast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Brazil South | Não | Sim | https://brazilsouth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Canadá Central | Não | Sim | https://canadacentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Centro dos EUA | Não | Sim | https://centralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Leste da Ásia | Não | Sim | https://eastasia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Leste dos EUA | Sim | Sim | https://eastus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Leste dos EUA 2 | Sim | Yes | https://eastus2.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| França Central | Não | Sim | https://francecentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Centro-Oeste da Alemanha | Não | Sim | https://germanywestcentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Centro da Índia | Yes | Sim | https://centralindia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Japan East | Sim | Sim | https://japaneast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Oeste do Japão | Não | Sim | https://japanwest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Oeste da Índia JIO | Não | Sim | https://jioindiawest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Coreia Central | Sim | Sim | https://koreacentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Centro-Norte dos EUA | Não | Sim | https://northcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Norte da Europa | Sim | Sim | https://northeurope.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Leste da Noruega | Não | Sim | https://norwayeast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Norte da África do Sul | Não | Sim | https://southafricanorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Centro-Sul dos Estados Unidos | Sim | Sim | https://southcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Sudeste Asiático | Sim | Sim | https://southeastasia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Norte da Suíça | Não | Sim | https://switzerlandnorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Oeste da Suíça | Não | Sim | https://switzerlandwest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Norte dos EAU | Não | Yes | https://uaenorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Sul do Reino Unido | Sim | Sim | https://uksouth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Centro-Oeste dos EUA | Não | Sim | https://westcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Europa Ocidental | Sim | Sim | https://westeurope.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Oeste dos EUA | Sim | Sim | https://westus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Oeste dos EUA 2 | Sim | Sim | https://westus2.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Oeste dos EUA 3 | Não | Sim | https://westus3.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
Observação
As regiões anteriores estão disponíveis para hospedagem de modelo de voz neural e sintetização em tempo real. O treinamento da sintetização de voz personalizada só está disponível em algumas regiões. Mas os usuários podem facilmente copiar um modelo de voz neural dessas três regiões para outras regiões na lista anterior.
API de áudio longo
A API de Áudio Longo está disponível em várias regiões com pontos de extremidade exclusivos:
| Região | Ponto de extremidade |
|---|---|
| Leste da Austrália | https://australiaeast.customvoice.api.speech.microsoft.com |
| Leste dos EUA | https://eastus.customvoice.api.speech.microsoft.com |
| Centro da Índia | https://centralindia.customvoice.api.speech.microsoft.com |
| Centro-Sul dos Estados Unidos | https://southcentralus.customvoice.api.speech.microsoft.com |
| Sudeste Asiático | https://southeastasia.customvoice.api.speech.microsoft.com |
| Sul do Reino Unido | https://uksouth.customvoice.api.speech.microsoft.com |
| Europa Ocidental | https://westeurope.customvoice.api.speech.microsoft.com |
Cabeçalhos da solicitação
Esta tabela lista os cabeçalhos obrigatórios e opcionais para solicitações de conversão de texto em fala:
| parâmetro | Descrição | Obrigatório ou opcional |
|---|---|---|
Authorization |
Um token de autorização precedido pela palavra Bearer. Para obter mais informações, consulte Autenticação. |
Obrigatório |
Content-Type |
Especifica o tipo de conteúdo para o texto fornecido. Aceita o valor: application/ssml+xml. |
Obrigatório |
X-Microsoft-OutputFormat |
Especifica o formato de saída de áudio. Para obter uma lista completa dos valores aceitos, consulte Saídas de áudio. | Obrigatório |
User-Agent |
O nome do aplicativo. O valor fornecido deve ter menos de 255 caracteres. | Obrigatório |
Corpo da solicitação
Se estiver usando uma voz neural personalizada, o corpo de uma solicitação poderá ser enviado como texto sem formatação (ASCII ou UTF-8). Caso contrário, o corpo de cada solicitação POST será enviado como SSML. A SSML permite que você escolha o idioma e a voz da fala sintetizada que o recurso de conversão de texto em fala retorna. Para obter uma lista completa de vozes com suporte, consulte Suporte a idiomas e voz para o serviço de Fala.
Solicitação de exemplo
Esta solicitação HTTP usa SSML para especificar a voz e o idioma. Se o comprimento do corpo for longo e o áudio resultante tiver mais que 10 minutos, ele será truncado para 10 minutos. Em outras palavras, o tamanho do áudio não pode ser maior que 10 minutos.
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>
* Para o Content-Length, você deve usar o seu comprimento de conteúdo. Na maioria dos casos, esse valor é calculado automaticamente.
Códigos de status HTTP
O código de status HTTP para cada resposta indica sucesso ou erros comuns:
| Código de status HTTP | Descrição | Possível motivo |
|---|---|---|
| 200 | OK | A solicitação foi bem-sucedida. O corpo da resposta é um arquivo de áudio. |
| 400 | Solicitação incorreta | Um parâmetro obrigatório está ausente, vazio ou nulo. Ou então, o valor passado como um parâmetro obrigatório ou opcional é inválido. Um motivo comum é um cabeçalho muito longo. |
| 401 | Não Autorizado | A solicitação não está autorizada. Verifique se a chave do recurso de Fala ou o token são válidos e se estão na região correta. |
| 415 | Tipo de mídia não suportado | É possível que o valor tenha sido fornecido o Content-Type incorreto. Content-Type deve ser definido como application/ssml+xml. |
| 429 | Número excessivo de solicitações | Você excedeu a cota ou a taxa de solicitações permitidas para seu recurso. |
| 502 | Gateway inválido | Há um problema de rede ou do lado do servidor. Esse status também pode indicar os cabeçalhos inválidos. |
Se o status HTTP for 200 OK, o corpo da resposta conterá um arquivo de áudio no formato solicitado. Este arquivo pode ser reproduzido enquanto é transferido, salvo em um buffer ou salvo em um arquivo.
Saídas de áudio
Os formatos de áudio de streaming e não streaming com suporte são enviados em cada solicitação como o X-Microsoft-OutputFormat cabeçalho. Cada formato incorpora uma taxa de bits e um tipo de codificação. O Serviço de Fala dá suporte a saídas de áudio de 48 kHz, 24 kHz, 16 kHz e 8 kHz. Cada modelo de voz neural predefinido está disponível em 24 kHz e em 48 kHz de alta fidelidade.
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
Observação
Se você selecionar o formato de saída de 48 kHz, o modelo de voz de alta fidelidade com 48 kHz será invocado adequadamente. As taxas de amostragem diferentes de 24 kHz e 48 kHz podem ser obtidas por meio de aumento ou redução da taxa de amostragem ao sintetizar, por exemplo, 44,1 kHz é obtida pela redução da taxa de amostragem de 48 kHz.
Se sua voz selecionada e o formato de saída tiverem diferentes taxas de bits, o áudio é aumentado conforme necessário. Você pode decodificar o formato ogg-24khz-16bit-mono-opus usando o Opus codec.
Autenticação
Cada solicitação precisa de um cabeçalho de autorização. Esta tabela ilustra os cabeçalhos compatíveis em cada recurso:
| Cabeçalho de autorização compatível | Conversão de fala em texto | Texto em fala |
|---|---|---|
Ocp-Apim-Subscription-Key |
Sim | Sim |
Authorization: Bearer |
Sim | Sim |
Quando você estiver usando o Ocp-Apim-Subscription-Key cabeçalho, somente sua chave de recurso deve ser fornecida. Por exemplo:
'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
Ao usar o Authorization: Bearer cabeçalho, você precisa fazer uma solicitação ao issueToken ponto de extremidade. Nesta solicitação, você troca sua chave de recurso por um token de acesso válido por dez minutos.
Outra opção é usar a autenticação do Microsoft Entra que também usa o cabeçalho, mas com um token emitido por meio da Authorization: Bearer ID do Microsoft Entra. Consulte Usar a autenticação do Microsoft Entra.
Como obter um token de acesso
Para obter um token de acesso, você precisa fazer uma solicitação ao ponto de extremidade issueToken usando a Ocp-Apim-Subscription-Key e sua chave de recurso.
O ponto de extremidade issueToken apresenta o seguinte formato:
https://<REGION_IDENTIFIER>.api.cognitive.microsoft.com/sts/v1.0/issueToken
Substitua <REGION_IDENTIFIER> pelo identificador que corresponde à região da sua assinatura.
Use os exemplos a seguir para criar sua solicitação de token de acesso.
Exemplo de HTTP
Este exemplo é uma solicitação HTTP simples para obter um token. Substitua YOUR_SUBSCRIPTION_KEY pela sua chave de recurso para o serviço de Fala. Se sua assinatura não se encontra na região Oeste dos EUA, substitua o cabeçalho Host pelo nome de host da sua região.
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
O corpo da resposta contém o token de acesso no formato JSON Web Token (JWT).
Exemplo do PowerShell
Este exemplo é um script simples do PowerShell para obter um token de acesso. Substitua YOUR_SUBSCRIPTION_KEY pela sua chave de recurso para o serviço de Fala. Certifique-se de usar o endpoint correto para a região que corresponde à sua assinatura. Este exemplo está atualmente definido para o oeste dos EUA.
$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
exemplo de cURL
cURL é uma ferramenta de linha de comando no Linux (e no Subsistema do Windows para Linux). Este comando cURL ilustra como obter um token de acesso. Substitua YOUR_SUBSCRIPTION_KEY pela sua chave de recurso para o serviço de Fala. Certifique-se de usar o endpoint correto para a região que corresponde à sua assinatura. Este exemplo está atualmente definido para o oeste dos EUA.
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"
Exemplo de C#
Esta classe C# ilustra como obter um token de acesso. Transmita sua chave de recurso para o serviço de Fala quando você criar uma instância da classe. Se a sua assinatura não estiver na região Oeste dos EUA, altere o valor de FetchTokenUri para que corresponda à região da sua assinatura.
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();
}
}
}
Exemplo de 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)
Como usar um token de acesso
O token de acesso deve ser enviado para o serviço como o cabeçalho Authorization: Bearer <TOKEN>. Cada token de acesso é válido por 10 minutos. É possível obter um novo token a qualquer momento, mas para minimizar o tráfego de rede e a latência, recomendamos usar o mesmo token por nove minutos.
Aqui está um exemplo de solicitação HTTP para a API REST de conversão de fala em texto para áudio curto:
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...
Use a autenticação do Microsoft Entra
Para usar a autenticação do Microsoft Entra com a API REST de fala para texto para áudio curto, você precisa criar um token de acesso. As etapas para obter o token de acesso que consiste na ID do Recurso e no token de acesso do Microsoft Entra são as mesmas que ao usar o SDK de Fala. Siga as etapas aqui Usar a autenticação do Microsoft Entra
- Criar um recurso de Fala
- Configurar o recurso de Fala para autenticação do Microsoft Entra
- Obter um token de acesso do Microsoft Entra
- Obter a ID do recurso de Fala
Depois que a ID do recurso e o token de acesso do Microsoft Entra forem obtidos, o token de acesso real poderá ser construído seguindo este formato:
aad#YOUR_RESOURCE_ID#YOUR_MICROSOFT_ENTRA_ACCESS_TOKEN
Você precisa incluir o prefixo "aad#" e o separador "#" (hash) entre a ID do recurso e o token de acesso.
Aqui está um exemplo de solicitação HTTP para a API REST de conversão de fala em texto para áudio curto:
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...
Para saber mais sobre os tokens de acesso do Microsoft Entra, incluindo o tempo de vida do token, visite tokens do Access na plataforma de identidade da Microsoft.