API de REST de Texto a voz
El servicio de voz le permite convertir texto en voz sintetizada y obtener una lista de voces admitidas para una región con un conjunto de API de REST. En este artículo, obtendrá información sobre las opciones de autorización, las opciones de consulta, cómo estructurar una solicitud y cómo interpretar una respuesta.
Sugerencia
Los casos de uso para la API de REST de texto a voz son limitados. Úsese solo en los casos en los que no se pueda usar el SDK de Voz. Por ejemplo, con el SDK de Voz, puede suscribirse a eventos para obtener más información sobre el procesamiento de texto a voz y los resultados.
La API REST de texto a voz admite texto neuronal a voces de voz en muchas configuraciones regionales. Cada punto de conexión disponible se asocia con una región. Se requiere una clave de recurso de Voz para el punto de conexión o la región que tiene previsto usar. A continuación se incluyen vínculos a más información:
- Para obtener una lista completa de las voces, consulte Compatibilidad con idiomas y voces en el servicio de voz.
- Para obtener información sobre la disponibilidad regional, consulte Regiones admitidas por el servicio de voz.
- Para los puntos de conexión de Azure Government y Microsoft Azure operado por 21Vianet, consulte este artículo sobre las nubes soberanas.
Importante
Los costos varían para las voces neuronales pregeneradas (denominadas neuronales en la página de precios) y las voces neuronales personalizadas (denominadas neuronales personalizadas en la página de precios). Para más información, consulte Precios del servicio de voz.
Antes de usar la API de REST de texto a voz, debe completar un intercambio de tokens como parte de la autenticación para acceder al servicio. Para más información, consulte Autenticación.
Obtener una lista de voces
Puede usar el punto de conexión tts.speech.microsoft.com/cognitiveservices/voices/list para obtener una lista completa de las voces de una región o un punto de conexión específicos. Use una región como prefijo del punto de conexión de lista de voces para obtener una lista de voces para esa región. Por ejemplo, para obtener una lista de voces para la región westus, use el punto de conexión https://westus.tts.speech.microsoft.com/cognitiveservices/voices/list. Para obtener una lista de todas las regiones admitidas, consulte la documentación de regiones.
Nota
La versión preliminar de Voces y estilos solo está disponible en tres regiones del servicio: Este de EE. UU., Oeste de Europa y Sudeste de Asia.
Encabezados de solicitud
En esta tabla se enumeran los encabezados obligatorios y opcionales para las solicitudes de texto a voz:
| Encabezado | Descripción | Obligatorio u opcional |
|---|---|---|
Ocp-Apim-Subscription-Key |
Clave del recurso de Voz. | Se necesita este encabezado, o bien Authorization. |
Authorization |
Un token de autorización precedido por la palabra Bearer. Para más información, consulte Autenticación. |
Se necesita este encabezado, o bien Ocp-Apim-Subscription-Key. |
Cuerpo de la solicitud
No es necesario un cuerpo para las solicitudes GET a este punto de conexión.
Solicitud de ejemplo
Esta solicitud solo requiere un encabezado de autorización:
GET /cognitiveservices/voices/list HTTP/1.1
Host: westus.tts.speech.microsoft.com
Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY
Este es un comando curl de ejemplo:
curl --location --request GET 'https://YOUR_RESOURCE_REGION.tts.speech.microsoft.com/cognitiveservices/voices/list' \
--header 'Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY'
Respuesta de muestra
Debería recibir una respuesta con un cuerpo JSON que incluya todas las configuraciones regionales, voces, género, estilos y otros detalles admitidos. La propiedad WordsPerMinute de cada voz se puede usar para calcular la longitud de la voz de salida. En este ejemplo JSON se muestran resultados parciales para ilustrar la estructura de una respuesta:
[
// 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 estado HTTP
El estado HTTP de cada respuesta indica estados de corrección o error comunes.
| Código de estado HTTP | Descripción | Posible motivo |
|---|---|---|
| 200 | Aceptar | La solicitud fue correcta. |
| 400 | Solicitud incorrecta | Falta un parámetro requerido, está vacío o es nulo. O bien, el valor pasado a un parámetro obligatorio u opcional no es válido. Una razón común es un encabezado demasiado largo. |
| 401 | No autorizado | La solicitud no está autorizada. Asegúrese de que la clave o el token de recurso sea válido y esté en la región correcta. |
| 429 | Demasiadas solicitudes | Superó la cuota o tasa de solicitudes permitidas para el recurso. |
| 502 | Puerta de enlace incorrecta | Hay un problema de red o del servidor. Este estado también puede indicar encabezados no válidos. |
Conversión de texto en voz
El punto de conexión cognitiveservices/v1 le permite convertir texto a voz usando el lenguaje de marcado de síntesis de voz (SSML).
Regiones y puntos de conexión
Estas regiones son compatibles con la conversión de texto a voz mediante la API de REST. Asegúrese de que selecciona el punto de conexión que coincide con la región de su recurso de Voz.
Voces neuronales pregeneradas
Utilice esta tabla para determinar la disponibilidad de las voces neuronales por región o punto de conexión:
| Region | Punto de conexión |
|---|---|
| Este de Australia | https://australiaeast.tts.speech.microsoft.com/cognitiveservices/v1 |
| Sur de Brasil | https://brazilsouth.tts.speech.microsoft.com/cognitiveservices/v1 |
| Centro de Canadá | https://canadacentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| Centro de EE. UU. | https://centralus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Este de Asia | https://eastasia.tts.speech.microsoft.com/cognitiveservices/v1 |
| Este de EE. UU. | https://eastus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Este de EE. UU. 2 | https://eastus2.tts.speech.microsoft.com/cognitiveservices/v1 |
| Centro de Francia | https://francecentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| Centro-oeste de Alemania | https://germanywestcentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| India central | https://centralindia.tts.speech.microsoft.com/cognitiveservices/v1 |
| Japón Oriental | https://japaneast.tts.speech.microsoft.com/cognitiveservices/v1 |
| Japón Occidental | https://japanwest.tts.speech.microsoft.com/cognitiveservices/v1 |
| JIO del Oeste de la India | https://jioindiawest.tts.speech.microsoft.com/cognitiveservices/v1 |
| Centro de Corea del Sur | https://koreacentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| Centro-Norte de EE. UU | https://northcentralus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Norte de Europa | https://northeurope.tts.speech.microsoft.com/cognitiveservices/v1 |
| Este de Noruega | https://norwayeast.tts.speech.microsoft.com/cognitiveservices/v1 |
| Centro-sur de EE. UU. | https://southcentralus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Sudeste de Asia | https://southeastasia.tts.speech.microsoft.com/cognitiveservices/v1 |
| Centro de Suecia | https://swedencentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| Norte de Suiza | https://switzerlandnorth.tts.speech.microsoft.com/cognitiveservices/v1 |
| Oeste de Suiza | https://switzerlandwest.tts.speech.microsoft.com/cognitiveservices/v1 |
| Norte de Emiratos Árabes Unidos | https://uaenorth.tts.speech.microsoft.com/cognitiveservices/v1 |
| US Gov: Arizona | https://usgovarizona.tts.speech.azure.us/cognitiveservices/v1 |
| US Gov - Virginia | https://usgovvirginia.tts.speech.azure.us/cognitiveservices/v1 |
| Sur de Reino Unido | https://uksouth.tts.speech.microsoft.com/cognitiveservices/v1 |
| Centro-Oeste de EE. UU. | https://westcentralus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Oeste de Europa | https://westeurope.tts.speech.microsoft.com/cognitiveservices/v1 |
| Oeste de EE. UU. | https://westus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Oeste de EE. UU. 2 | https://westus2.tts.speech.microsoft.com/cognitiveservices/v1 |
| Oeste de EE. UU. 3 | https://westus3.tts.speech.microsoft.com/cognitiveservices/v1 |
Sugerencia
Las voces en versión preliminar solo están disponibles en estas tres regiones: Este de EE. UU., Oeste de Europa y Sudeste Asiático.
Voces neuronales personalizadas
Si ha creado una fuente de voz neuronal personalizada, use el punto de conexión que ha creado. También puede utilizar los puntos de conexión siguientes. Reemplace {deploymentId} por el id. de implementación de su modelo de voz neuronal.
| Region | Cursos | Implementación | Punto de conexión |
|---|---|---|---|
| Este de Australia | Sí | Sí | https://australiaeast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Sur de Brasil | No | Sí | https://brazilsouth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Centro de Canadá | No | Sí | https://canadacentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Centro de EE. UU. | No | Sí | https://centralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Este de Asia | No | Sí | https://eastasia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Este de EE. UU. | Sí | Sí | https://eastus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Este de EE. UU. 2 | Sí | Sí | https://eastus2.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Centro de Francia | No | Sí | https://francecentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Centro-oeste de Alemania | No | Sí | https://germanywestcentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| India central | Sí | Sí | https://centralindia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Japón Oriental | Sí | Sí | https://japaneast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Japón Occidental | No | Sí | https://japanwest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| JIO del Oeste de la India | No | Sí | https://jioindiawest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Centro de Corea del Sur | Sí | Sí | https://koreacentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Centro-Norte de EE. UU | No | Sí | https://northcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Norte de Europa | Sí | Sí | https://northeurope.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Este de Noruega | No | Sí | https://norwayeast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Norte de Sudáfrica | No | Sí | https://southafricanorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Centro-sur de EE. UU. | Sí | Sí | https://southcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Sudeste de Asia | Sí | Sí | https://southeastasia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Norte de Suiza | No | Sí | https://switzerlandnorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Oeste de Suiza | No | Sí | https://switzerlandwest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Norte de Emiratos Árabes Unidos | No | Sí | https://uaenorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Sur de Reino Unido 2 | Sí | Sí | https://uksouth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Centro-Oeste de EE. UU. | No | Sí | https://westcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Oeste de Europa | Sí | Sí | https://westeurope.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Oeste de EE. UU. | Sí | Sí | https://westus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Oeste de EE. UU. 2 | Sí | Sí | https://westus2.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Oeste de EE. UU. 3 | No | Sí | https://westus3.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
Nota
Las regiones anteriores están disponibles para el hospedaje del modelo de voz neuronal y la síntesis en tiempo real. El entrenamiento de voz neuronal personalizada solo está disponible en algunas regiones. Pero los usuarios pueden copiar fácilmente un modelo de voz neuronal de estas regiones a otras de la lista anterior.
Long Audio API
Long Audio API está disponible en varias regiones con puntos de conexión únicos:
| Region | Punto de conexión |
|---|---|
| Este de Australia | https://australiaeast.customvoice.api.speech.microsoft.com |
| Este de EE. UU. | https://eastus.customvoice.api.speech.microsoft.com |
| India central | https://centralindia.customvoice.api.speech.microsoft.com |
| Centro-sur de EE. UU. | https://southcentralus.customvoice.api.speech.microsoft.com |
| Sudeste de Asia | https://southeastasia.customvoice.api.speech.microsoft.com |
| Sur de Reino Unido 2 | https://uksouth.customvoice.api.speech.microsoft.com |
| Oeste de Europa | https://westeurope.customvoice.api.speech.microsoft.com |
Encabezados de solicitud
En esta tabla se enumeran los encabezados obligatorios y opcionales para las solicitudes de texto a voz:
| Encabezado | Descripción | Obligatorio u opcional |
|---|---|---|
Authorization |
Un token de autorización precedido por la palabra Bearer. Para más información, consulte Autenticación. |
Obligatorio |
Content-Type |
Especifica el tipo de contenido para el texto proporcionado. Valor aceptable: application/ssml+xml. |
Obligatorio |
X-Microsoft-OutputFormat |
Especifica el formato de salida del audio. Para obtener una lista completa de los valores aceptados, consulte Salidas de audio. | Obligatorio |
User-Agent |
Nombre de la aplicación. El valor proporcionado debe tener menos de 255 caracteres. | Obligatorio |
Cuerpo de la solicitud
Si usa una voz neuronal personalizada, el cuerpo de una solicitud se puede enviar como texto sin formato (ASCII o UTF-8). De lo contrario, el cuerpo de cada solicitud POST se envía como SSML. SSML le permite elegir la voz y el idioma de la voz sintetizada que devuelve el servicio de texto a voz. Para obtener una lista completa de las voces admitidas, consulte Compatibilidad con idiomas y voces en el servicio de voz.
Solicitud de ejemplo
Esta solicitud HTTP utiliza SSML para especificar el idioma y la voz. Si la longitud del cuerpo es larga y el audio resultante supera los 10 minutos, se trunca a 10 minutos. En otras palabras, la longitud del audio no puede superar los 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 Content-Length, debe usar sus propios valores de longitud de contenido. En la mayoría de los casos, este valor se calcula automáticamente.
Códigos de estado HTTP
El código de estado HTTP de cada respuesta indica estados de corrección o error comunes:
| Código de estado HTTP | Descripción | Posible motivo |
|---|---|---|
| 200 | Aceptar | La solicitud fue correcta. El cuerpo de la respuesta es un archivo de audio. |
| 400 | Solicitud incorrecta | Falta un parámetro requerido, está vacío o es nulo. O bien, el valor pasado a un parámetro obligatorio u opcional no es válido. Una razón común es un encabezado demasiado largo. |
| 401 | No autorizado | La solicitud no está autorizada. Asegúrese de que la clave o el token de recurso de Voz sea válido y de la región correcta. |
| 415 | Tipo de medio no compatible | Es posible que se haya proporcionado un valor de Content-Type incorrecto. Content-Type se debe establecer en application/ssml+xml. |
| 429 | Demasiadas solicitudes | Superó la cuota o tasa de solicitudes permitidas para el recurso. |
| 502 | Puerta de enlace incorrecta | Hay un problema de red o del servidor. Este estado también puede indicar encabezados no válidos. |
Si el estado HTTP es 200 OK, el cuerpo de la respuesta contiene un archivo de audio en el formato solicitado. Este archivo se puede reproducir mientras se transfiere o guardarse en un búfer o en un archivo.
Salidas de audio
Los formatos de audio de streaming y no streaming admitidos se envían en cada solicitud como X-Microsoft-OutputFormat encabezado. Cada formato incorpora una velocidad de bits y un tipo de codificación. El servicio de voz admite salidas de audio de 48 kHz, 24 kHz, 16 kHz y 8 kHz. Cada modelo de voz neuronal precompilado está disponible a 24 kHz y alta fidelidad de 48 kHz.
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
Nota:
Si selecciona el formato de salida de 48 kHz, se invocará el modelo de voz de alta fidelidad con 48 kHz. Las frecuencia de muestreo distintas de 24 kHz y 48 kHz se pueden obtener mediante el muestreo vertical o descendente al sintetizar, por ejemplo, 44,1 kHz se reduce a partir de 48 kHz.
Si la voz y el formato de salida seleccionados tienen velocidades de bits diferentes, se vuelve a muestrear el audio según sea necesario. Puede descodificar el formato ogg-24khz-16bit-mono-opus mediante el códec Opus.
Authentication
Cada solicitud requiere un encabezado de autorización. Esta tabla muestra qué encabezados son compatibles con cada característica:
| Encabezado de autorización compatible | Conversión de voz en texto | Texto a voz |
|---|---|---|
Ocp-Apim-Subscription-Key |
Sí | Sí |
Authorization: Bearer |
Sí | Sí |
Cuando se usa el encabezado , solo se debe proporcionar la Ocp-Apim-Subscription-Key clave de recurso. Por ejemplo:
'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
Cuando use el Authorization: Bearer encabezado , debe realizar una solicitud al issueToken punto de conexión. En esta solicitud, va a intercambiar la clave de recurso de un token de acceso que es válido durante 10 minutos.
Otra opción consiste en usar la autenticación de Microsoft Entra que también usa el Authorization: Bearer encabezado, pero con un token emitido a través de Microsoft Entra ID. Consulte Uso de la autenticación de Microsoft Entra.
Obtención de un token de acceso
Para obtener un token de acceso, tiene que realizar una solicitud al punto de conexión issueToken mediante Ocp-Apim-Subscription-Key y su clave de recurso.
El punto de conexión issueToken tiene el siguiente formato:
https://<REGION_IDENTIFIER>.api.cognitive.microsoft.com/sts/v1.0/issueToken
Reemplace <REGION_IDENTIFIER> por el identificador que coincide con la región de la suscripción.
Use los siguientes ejemplos para crear la solicitud de token de acceso.
Ejemplo de HTTP
Este ejemplo es una solicitud HTTP para obtener un token. Reemplace YOUR_SUBSCRIPTION_KEY por la clave de recurso para el servicio Voz. Si la suscripción no está en la región Oeste de EE. UU., reemplace el encabezado Host por el nombre de host de la región.
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
El cuerpo de la respuesta contiene el token de acceso en formato JSON Web Token (JWT).
Ejemplo de PowerShell
En este ejemplo se muestra un script sencillo de PowerShell para obtener un token de acceso. Reemplace YOUR_SUBSCRIPTION_KEY por la clave de recurso para el servicio Voz. Asegúrese de usar el punto de conexión correcto para la región que coincida con su suscripción. En este ejemplo la región es Oeste de EE. UU.
$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
Ejemplo de cURL
cURL es una herramienta de la línea de comandos disponible en Linux (y en el subsistema Windows para Linux). Este comando cURL muestra cómo obtener un token de acceso. Reemplace YOUR_SUBSCRIPTION_KEY por la clave de recurso para el servicio Voz. Asegúrese de usar el punto de conexión correcto para la región que coincida con su suscripción. En este ejemplo la región es Oeste de EE. UU.
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"
Ejemplo de C#
Esta clase de C# muestra cómo obtener un token de acceso. Pase la clave de recurso del servicio Voz al crear una instancia de la clase. Si su suscripción no está en la región Oeste de EE. UU., cambie el valor de FetchTokenUri para que coincida con la región de su suscripción.
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();
}
}
}
Ejemplo 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)
Uso de un token de acceso
Se debe enviar el token de acceso al servicio como encabezado Authorization: Bearer <TOKEN>. Cada token de acceso tiene una validez de 10 minutos. Puede obtener un nuevo token en cualquier momento. No obstante, para reducir el tráfico de red y la latencia, se recomienda usar el mismo token durante nueve minutos.
A continuación se muestra una solicitud HTTP de ejemplo a la API REST de conversión de voz en texto para audios de corta duración:
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...
Uso de la autenticación de Microsoft Entra
Para usar la autenticación de Microsoft Entra con speech to text REST API para audio corto, debe crear un token de acceso. Los pasos para obtener el token de acceso que consta del identificador de recurso y el token de acceso de Microsoft Entra son los mismos que cuando se usa el SDK de Voz. Siga los pasos que se indican aquí : Uso de la autenticación de Microsoft Entra
- Crear un recurso de voz.
- Configurar el recurso de voz para la autenticación de Microsoft Entra
- Obtener un token de acceso de Microsoft Entra
- Obtención del identificador de recurso de Voz
Después de obtener el identificador de recurso y el token de acceso de Microsoft Entra, el token de acceso real se puede construir siguiendo este formato:
aad#YOUR_RESOURCE_ID#YOUR_MICROSOFT_ENTRA_ACCESS_TOKEN
Debe incluir el prefijo "aad#" y el separador "#" (hash) entre el identificador de recurso y el token de acceso.
A continuación se muestra una solicitud HTTP de ejemplo a la API REST de conversión de voz en texto para audios de corta duración:
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 obtener más información sobre los tokens de acceso de Microsoft Entra, incluyendo la duración del token, visite Tokens de acceso en la Plataforma de identidad de Microsoft.