API REST de synthèse vocale
Le service Speech vous permet de convertir du texte en synthèse vocale et d’obtenir une liste de voix prises en charge pour une région à l’aide d’un API REST. Dans cet article, vous allez découvrir les options d’autorisation, les options de requête, la structure d’une requête et l’interprétation d’une réponse.
Conseil
Les cas d’usage pour l’API REST de synthèse vocale sont limités. Utilisez-la uniquement si vous ne pouvez pas utiliser le Kit de développement logiciel (SDK) Speech. Par exemple, avec le SDK Speech, vous pouvez vous abonner à des événements pour obtenir plus d’insights sur le traitement et les résultats de la synthèse vocale.
L’API REST de synthèse vocale prend en charge les voix de synthèse vocale dans de nombreux paramètres régionaux. Chaque point de terminaison disponible est associé à une région. Une clé de ressource Speech pour le point de terminaison ou la région que vous prévoyez d’utiliser est nécessaire. Voici des liens vers des informations supplémentaires :
- Pour obtenir une liste complète des voix, consultez Prise en charge des langues et de la voix pour le service Speech.
- Pour plus d’informations sur la disponibilité régionale, consultez Régions prises en charge pour le service Speech.
- Consultez cet article à propos des clouds souverains pour les points de terminaison Azure Government et Microsoft Azure géré par 21Vianet.
Important
Les coûts varient pour les voix neuronales prédéfinies (appelées Neuronales sur la page de tarification) et les voix neuronales personnalisées (appelées Neuronales personnalisées sur la page de tarification). Pour plus d’informations, consultez les tarifs du service Speech.
Avant d’utiliser l’API REST de synthèse vocale, vous devez effectuer un échange de jetons dans le cadre de l’authentification pour accéder au service. Pour en savoir plus, consultez Authentification.
Obtenir une liste de voix
Vous pouvez utiliser le point de terminaison tts.speech.microsoft.com/cognitiveservices/voices/list pour obtenir une liste complète de voix pour une région ou un point de terminaison spécifique. Préfixez le point de terminaison de liste des voix avec une région pour obtenir une liste de voix pour cette région. Par exemple, pour obtenir la liste de voix pour la région westus, utilisez le point de terminaison https://westus.tts.speech.microsoft.com/cognitiveservices/voices/list. Pour obtenir la liste de toutes les régions prises en charge, consultez la documentation des régions.
Notes
Les voix et styles en préversion sont uniquement disponibles dans trois régions de service : USA Est, Europe Ouest et Asie Sud-Est.
En-têtes de requête
Le tableau ci-dessous répertorie les en-têtes obligatoires et facultatifs pour les demandes de synthèse vocale :
| En-tête | Description | Obligatoire ou facultatif |
|---|---|---|
Ocp-Apim-Subscription-Key |
Clé de votre ressource Speech. | Cet en-tête ou Authorization est requis. |
Authorization |
Un jeton d’autorisation précédé du mot Bearer. Pour en savoir plus, consultez Authentification. |
Cet en-tête ou Ocp-Apim-Subscription-Key est requis. |
Corps de la demande
Les demandes GET à ce point de terminaison ne nécessitent pas de corps.
Exemple de requête
Chaque demande nécessite uniquement un en-tête d’autorisation :
GET /cognitiveservices/voices/list HTTP/1.1
Host: westus.tts.speech.microsoft.com
Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY
Voici un exemple de commande curl :
curl --location --request GET 'https://YOUR_RESOURCE_REGION.tts.speech.microsoft.com/cognitiveservices/voices/list' \
--header 'Ocp-Apim-Subscription-Key: YOUR_RESOURCE_KEY'
Exemple de réponse
Vous devez recevoir une réponse avec un corps JSON qui inclut tous les paramètres régionaux, voix, sexe, styles et autres détails pris en charge. La propriété WordsPerMinute de chaque voix peut être utilisée pour estimer la longueur de la voix de sortie. Cet exemple JSON montre des résultats partiels pour illustrer la structure d’une réponse :
[
// 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
]
Codes d’état HTTP
Le code d’état HTTP de chaque réponse indique la réussite ou des erreurs courantes.
| Code d'état HTTP | Description | Raison possible |
|---|---|---|
| 200 | OK | La demande a abouti. |
| 400 | Demande incorrecte | Un paramètre obligatoire est manquant, vide ou présente une valeur Null. Il est également possible que la valeur transmise à un paramètre obligatoire ou facultatif ne soit pas valide. Ce problème est généralement dû à un en-tête trop long. |
| 401 | Non autorisé | La requête n’est pas autorisée. Vérifiez que votre jeton ou clé de ressource est valide et se trouve dans la région appropriée. |
| 429 | Trop de demandes | Vous avez dépassé le quota ou le taux de requêtes autorisés pour votre ressource. |
| 502 | Passerelle incorrecte | Il y a un problème au niveau du réseau ou côté serveur. Cet état peut également signaler des en-têtes non valides. |
Convertir du texte en parole
Le point de terminaison cognitiveservices/v1 vous permet de convertir du texte en parole à l’aide de SSML (Speech Synthesis Markup Langage).
Régions et points de terminaison
Ces régions sont prises en charge pour la synthèse vocale via l’API REST. Veillez à sélectionner le point de terminaison correspondant à votre région de ressource Speech.
Voix neuronales prédéfinies
Servez-vous de ce tableau pour connaître la disponibilité des voix neuronales par région ou point de terminaison :
| Région | Point de terminaison |
|---|---|
| Australie Est | https://australiaeast.tts.speech.microsoft.com/cognitiveservices/v1 |
| Brésil Sud | https://brazilsouth.tts.speech.microsoft.com/cognitiveservices/v1 |
| Centre du Canada | https://canadacentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| USA Centre | https://centralus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Asie Est | https://eastasia.tts.speech.microsoft.com/cognitiveservices/v1 |
| USA Est | https://eastus.tts.speech.microsoft.com/cognitiveservices/v1 |
| USA Est 2 | https://eastus2.tts.speech.microsoft.com/cognitiveservices/v1 |
| France Centre | https://francecentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| Allemagne Centre-Ouest | https://germanywestcentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| Inde Centre | https://centralindia.tts.speech.microsoft.com/cognitiveservices/v1 |
| Japon Est | https://japaneast.tts.speech.microsoft.com/cognitiveservices/v1 |
| OuJapon Est | https://japanwest.tts.speech.microsoft.com/cognitiveservices/v1 |
| Inde Ouest Jio | https://jioindiawest.tts.speech.microsoft.com/cognitiveservices/v1 |
| Centre de la Corée | https://koreacentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| Centre-Nord des États-Unis | https://northcentralus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Europe Nord | https://northeurope.tts.speech.microsoft.com/cognitiveservices/v1 |
| Norvège Est | https://norwayeast.tts.speech.microsoft.com/cognitiveservices/v1 |
| États-Unis - partie centrale méridionale | https://southcentralus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Asie Sud-Est | https://southeastasia.tts.speech.microsoft.com/cognitiveservices/v1 |
| Suède Centre | https://swedencentral.tts.speech.microsoft.com/cognitiveservices/v1 |
| Suisse Nord | https://switzerlandnorth.tts.speech.microsoft.com/cognitiveservices/v1 |
| Suisse Ouest | https://switzerlandwest.tts.speech.microsoft.com/cognitiveservices/v1 |
| Émirats arabes unis Nord | https://uaenorth.tts.speech.microsoft.com/cognitiveservices/v1 |
| Gouvernement des États-Unis – Arizona | https://usgovarizona.tts.speech.azure.us/cognitiveservices/v1 |
| Gouvernement américain - Virginie | https://usgovvirginia.tts.speech.azure.us/cognitiveservices/v1 |
| Sud du Royaume-Uni | https://uksouth.tts.speech.microsoft.com/cognitiveservices/v1 |
| Centre-USA Ouest | https://westcentralus.tts.speech.microsoft.com/cognitiveservices/v1 |
| Europe Ouest | https://westeurope.tts.speech.microsoft.com/cognitiveservices/v1 |
| USA Ouest | https://westus.tts.speech.microsoft.com/cognitiveservices/v1 |
| USA Ouest 2 | https://westus2.tts.speech.microsoft.com/cognitiveservices/v1 |
| USA Ouest 3 | https://westus3.tts.speech.microsoft.com/cognitiveservices/v1 |
Conseil
Des voix en préversion sont disponibles uniquement dans les trois régions suivantes : USA Est, Europe Ouest et Asie Sud-Est.
Voix neurales personnalisées
Si vous avez créé une police de voix neurale personnalisée, utilisez le point de terminaison que vous avez créé. Vous pouvez également utiliser les points de terminaison suivants. Remplacez {deploymentId} par l’ID de déploiement de votre modèle de voix neuronale.
| Région | Entrainement | Déploiement | Point de terminaison |
|---|---|---|---|
| Australie Est | Oui | Oui | https://australiaeast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Brésil Sud | Non | Oui | https://brazilsouth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Centre du Canada | Non | Oui | https://canadacentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| USA Centre | Non | Oui | https://centralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Asie Est | Non | Oui | https://eastasia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| USA Est | Oui | Oui | https://eastus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| USA Est 2 | Oui | Oui | https://eastus2.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| France Centre | Non | Oui | https://francecentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Allemagne Centre-Ouest | Non | Oui | https://germanywestcentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Inde Centre | Oui | Oui | https://centralindia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Japon Est | Oui | Oui | https://japaneast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| OuJapon Est | Non | Oui | https://japanwest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Inde Ouest Jio | Non | Oui | https://jioindiawest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Centre de la Corée | Oui | Oui | https://koreacentral.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Centre-Nord des États-Unis | Non | Oui | https://northcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Europe Nord | Oui | Oui | https://northeurope.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Norvège Est | Non | Oui | https://norwayeast.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Afrique du Sud Nord | Non | Oui | https://southafricanorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| États-Unis - partie centrale méridionale | Oui | Oui | https://southcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Asie Sud-Est | Oui | Oui | https://southeastasia.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Suisse Nord | Non | Oui | https://switzerlandnorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Suisse Ouest | Non | Oui | https://switzerlandwest.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Émirats arabes unis Nord | Non | Oui | https://uaenorth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Sud du Royaume-Uni | Oui | Oui | https://uksouth.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Centre-USA Ouest | Non | Oui | https://westcentralus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| Europe Ouest | Oui | Oui | https://westeurope.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| USA Ouest | Oui | Oui | https://westus.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| USA Ouest 2 | Oui | Oui | https://westus2.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
| USA Ouest 3 | Non | Oui | https://westus3.voice.speech.microsoft.com/cognitiveservices/v1?deploymentId={deploymentId} |
Notes
Les régions précédentes sont disponibles pour l’hébergement du modèle de voix neuronale et la synthèse vocale en temps réel. L’apprentissage vocal neural personnalisé n’est disponible que dans certaines régions. Toutefois, les utilisateurs peuvent facilement copier un modèle de voix neurale de ces régions dans d’autres régions figurant dans la liste précédente.
API Audio long
L’API Audio long est disponible dans plusieurs régions avec des points de terminaison uniques :
| Région | Point de terminaison |
|---|---|
| Australie Est | https://australiaeast.customvoice.api.speech.microsoft.com |
| USA Est | https://eastus.customvoice.api.speech.microsoft.com |
| Inde Centre | https://centralindia.customvoice.api.speech.microsoft.com |
| États-Unis - partie centrale méridionale | https://southcentralus.customvoice.api.speech.microsoft.com |
| Asie Sud-Est | https://southeastasia.customvoice.api.speech.microsoft.com |
| Sud du Royaume-Uni | https://uksouth.customvoice.api.speech.microsoft.com |
| Europe Ouest | https://westeurope.customvoice.api.speech.microsoft.com |
En-têtes de requête
Le tableau ci-dessous répertorie les en-têtes obligatoires et facultatifs pour les demandes de synthèse vocale :
| En-tête | Description | Obligatoire ou facultatif |
|---|---|---|
Authorization |
Un jeton d’autorisation précédé du mot Bearer. Pour en savoir plus, consultez Authentification. |
Obligatoire |
Content-Type |
Spécifie le type de contenu pour le texte fourni. Valeur acceptée : application/ssml+xml. |
Obligatoire |
X-Microsoft-OutputFormat |
Spécifie le format de la sortie audio. Pour obtenir une liste complète des valeurs acceptées, consultez Sorties audio. | Obligatoire |
User-Agent |
Nom d'application. La valeur fournie doit être inférieure à 255 caractères. | Obligatoire |
Corps de la demande
Si vous utilisez une voix neuronale personnalisée, le corps d’une demande peut être envoyé sous forme de texte brut (ASCII ou UTF-8). Sinon, le corps de chaque demande POST est envoyé en tant que SSML. SSML vous permet de choisir la voix et la langue de la synthèse vocale renvoyée par la fonctionnalité de synthèse vocale. Pour obtenir une liste complète des voix prises en charge, consultez Prise en charge des langues et de la voix pour le service Speech.
Exemple de requête
Cette requête HTTP utilise SSML pour spécifier la voix et la langue. Si la longueur du corps est grande et que le contenu audio obtenu dépasse 10 minutes, il est tronqué à 10 minutes. En d’autres termes, la durée du contenu audio ne peut pas dépasser 10 minutes.
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>
* Pour la longueur du contenu, vous devez utiliser votre propre longueur de contenu. Dans la plupart des cas, cette valeur est calculée automatiquement.
Codes d’état HTTP
Le code d’état HTTP de chaque réponse indique la réussite ou des erreurs courantes :
| Code d’état HTTP | Description | Raison possible |
|---|---|---|
| 200 | OK | La demande a abouti. Le corps de la réponse est un fichier audio. |
| 400 | Demande incorrecte | Un paramètre obligatoire est manquant, vide ou présente une valeur Null. Il est également possible que la valeur transmise à un paramètre obligatoire ou facultatif ne soit pas valide. Ce problème est généralement dû à un en-tête trop long. |
| 401 | Non autorisé | La requête n’est pas autorisée. Vérifiez que votre jeton ou clé de ressource Speech est valide et se trouve dans la région appropriée. |
| 415 | Type de média non pris en charge | Il est possible que la valeur Content-Type indiquée était incorrecte. Content-Type doit être définie sur application/ssml+xml. |
| 429 | Trop de demandes | Vous avez dépassé le quota ou le taux de requêtes autorisés pour votre ressource. |
| 502 | Passerelle incorrecte | Il y a un problème au niveau du réseau ou côté serveur. Cet état peut également signaler des en-têtes non valides. |
| 503 | Service indisponible | Il existe un problème côté serveur pour différentes raisons. |
Si l’état HTTP est 200 OK, le corps de la réponse contient un fichier audio au format demandé. Ce fichier peut être lu pendant son transfert ou pendant son enregistrement dans une mémoire tampon ou dans un fichier.
Sorties audio
Les formats audio de streaming et de diffusion en continu pris en charge sont envoyés dans chaque requête en tant qu’en-tête X-Microsoft-OutputFormat . Chaque format incorpore une vitesse de transmission et un type d’encodage. Le service Speech prend en charge les sorties audio de 48 kHz, 24 kHz, 16 kHz et 8 kHz. Chaque modèle vocal neuronal prédéfini est disponible aux niveaux 24 kHz et 48 kHz haute fidélité.
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
Notes
Si vous sélectionnez le format de sortie 48 kHz, le modèle vocal haute fidélité avec 48 kHz est appelé en conséquence. Les taux d’échantillonnage autres que 24 kHz et 48 kHz peuvent être obtenus par le biais d’un suréchantillonnage ou d’un sous-échantillonnage lors de la synthèse ; par exemple, 44,1 kHz est sous-échantillonné de 48 kHz.
Si la voix que vous avez sélectionnée ne présente pas la même vitesse de transmission que le format de sortie spécifié, les données audio sont rééchantillonnées si nécessaire. Vous pouvez décoder le format ogg-24khz-16bit-mono-opus à l’aide du codec Opus.
Authentication
Chaque requête nécessite un en-tête d’autorisation. Ce tableau présente les en-têtes pris en charge pour chaque fonctionnalité :
| En-têtes d’autorisation pris en charge | Reconnaissance vocale | Synthèse vocale |
|---|---|---|
Ocp-Apim-Subscription-Key |
Oui | Oui |
Authorization: Bearer |
Oui | Oui |
Lorsque vous utilisez l’en-tête Ocp-Apim-Subscription-Key , seule votre clé de ressource doit être fournie. Par exemple :
'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
Lorsque vous utilisez l’en-tête Authorization: Bearer , vous devez effectuer une demande au issueToken point de terminaison. Dans cette requête, vous échangez votre clé de ressource contre un jeton d’accès valide pendant 10 minutes.
Une autre option consiste à utiliser l’authentification Microsoft Entra qui utilise également l’en-tête Authorization: Bearer , mais avec un jeton émis via l’ID Microsoft Entra. Consultez Utiliser l’authentification Microsoft Entra.
Obtenir un jeton d’accès
Pour obtenir un jeton d’accès, vous avez besoin d’envoyer une demande au point de terminaison issueToken à l’aide de Ocp-Apim-Subscription-Key et de votre clé de ressource.
Le format du point de terminaison issueToken est le suivant :
https://<REGION_IDENTIFIER>.api.cognitive.microsoft.com/sts/v1.0/issueToken
Remplacez <REGION_IDENTIFIER> par l’identificateur correspondant à la région de votre abonnement.
Utilisez les exemples suivants pour créer votre demande de jeton d’accès.
Exemple HTTP
Cet exemple est une simple requête HTTP pour obtenir un jeton. Remplacez YOUR_SUBSCRIPTION_KEY par votre clé de ressource du service Speech. Si votre abonnement n’est pas dans la région USA Ouest, remplacez l’en-tête Host par le nom d’hôte de votre région.
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
Le corps de la réponse contient le jeton d’accès au format JSON Web Token (JWT).
Exemple de code PowerShell
Cet exemple est un simple script PowerShell pour obtenir un jeton d’accès. Remplacez YOUR_SUBSCRIPTION_KEY par votre clé de ressource du service Speech. Veillez à utiliser le point de terminaison correct pour la région correspondant à votre abonnement. Cet exemple est actuellement configuré pour l’USA Ouest.
$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
Exemple cURL
cURL est un outil en ligne de commande disponible dans Linux (ainsi que dans le sous-système Windows pour Linux). Cette commande cURL montre comment obtenir un jeton d’accès. Remplacez YOUR_SUBSCRIPTION_KEY par votre clé de ressource du service Speech. Veillez à utiliser le point de terminaison correct pour la région correspondant à votre abonnement. Cet exemple est actuellement configuré pour l’USA Ouest.
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"
Exemple de code C#
La classe C# montre comment obtenir un jeton d’accès. Transmettez votre clé de ressource du service Speech quand vous instanciez la classe. Si votre abonnement ne figure pas dans la région USA Ouest, modifiez la valeur FetchTokenUri afin qu’elle corresponde à la région de votre abonnement.
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();
}
}
}
Exemple de code 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)
Utiliser un jeton d’accès
Le jeton d’accès doit être envoyé au service en tant qu’en-tête Authorization: Bearer <TOKEN>. Chaque jeton d’accès est valide pour une durée de 10 minutes. Vous pouvez à tout moment obtenir un nouveau jeton, mais pour réduire la latence et le trafic réseau, nous recommandons d’utiliser le même jeton pendant neuf minutes.
Voici un exemple de requête HTTP adressée à l’API REST de reconnaissance vocale pour audio court :
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...
Utiliser Authentification Microsoft Entra
Pour utiliser l’authentification Microsoft Entra avec l’API REST Speech to text pour un audio court, vous devez créer un jeton d’accès. Les étapes d’obtention du jeton d’accès constitué de l’ID de ressource et du jeton d’accès Microsoft Entra sont les mêmes que lors de l’utilisation du Kit de développement logiciel (SDK) Speech. Suivez les étapes ci-dessous pour utiliser l’authentification Microsoft Entra
- Créer une ressource Speech
- Configurer la ressource Speech pour l’authentification Microsoft Entra
- Obtenir un jeton d’accès Microsoft Entra
- Obtenir l’ID de ressource Speech
Une fois que l’ID de ressource et le jeton d’accès Microsoft Entra ont été obtenus, le jeton d’accès réel peut être construit au format suivant :
aad#YOUR_RESOURCE_ID#YOUR_MICROSOFT_ENTRA_ACCESS_TOKEN
Vous devez inclure le préfixe « aad# » et le séparateur « # » (hachage) entre l’ID de ressource et le jeton d’accès.
Voici un exemple de requête HTTP adressée à l’API REST de reconnaissance vocale pour audio court :
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...
Pour en savoir plus sur les jetons d’accès Microsoft Entra, notamment leur durée de vie, consultez Jetons d’accès de la plateforme d’identités Microsoft.