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 découvrirez les options d’autorisation, les options de requête, comment structurer une demande et comment interpréter 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é API pour le point de terminaison ou la région que vous prévoyez d’utiliser est requise. 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.
Pour Azure Government et Microsoft Azure managé par des points de terminaison 21Vianet, consultez cet article sur les clouds souverains.

Important

Les coûts varient pour les voix standard et les voix personnalisées. Pour plus d’informations, consultez la tarification de la synthèse vocale.

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.

Remarque

Les voix et les styles en préversion ne sont disponibles que dans un sous-ensemble de régions. Pour obtenir la liste actuelle des régions qui prennent en charge les voix et les styles en version préliminaire publique, consultez le tableau des régions du service de Synthèse vocale.

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	Descriptif	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	Descriptif	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é 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 standard

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`
Canada Centre	`https://canadacentral.tts.speech.microsoft.com/cognitiveservices/v1`
Canada Est	`https://canadaeast.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`
Italie Nord	`https://italynorth.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`
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`
Qatar Central	`https://qatarcentral.tts.speech.microsoft.com/cognitiveservices/v1`
Afrique du Sud Nord	`https://southafricanorth.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`
Sud du Royaume-Uni	`https://uksouth.tts.speech.microsoft.com/cognitiveservices/v1`
UK West	`https://ukwest.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`
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

Pour obtenir la liste actuelle des régions qui prennent en charge les voix en préversion, consultez la table des régions du service Speech.

Voix personnalisées

Si vous avez créé une voix 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 vocal personnalisé.

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}`
Canada Centre	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}`
Italie Nord	Non	Oui	`https://italynorth.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}`
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}`
Suède Centre	Non	Oui	`https://swedencentral.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}`

Remarque

Les régions précédentes sont disponibles pour l’hébergement de modèles vocaux standard et la synthèse en temps réel. L’entraînement vocal personnalisé n’est disponible que dans certaines régions. Toutefois, vous pouvez facilement copier un modèle vocal personnalisé de ces régions vers d’autres régions de 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	Descriptif	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 personnalisée, le corps d’une requête peut être envoyé en 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	Descriptif	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é 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 y a un problème côté serveur pour diverses 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 en streaming et non en streaming 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 standard est disponible avec une fréquence de 24 kHz et en haute fidélité à 48 kHz.

Streaming
NonStreaming

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
g722-16khz-64kbps
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

Remarque

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.

Authentification

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

'Ocp-Apim-Subscription-Key': 'YourSpeechResourceKey'

Lorsque vous utilisez l'en-tête Authorization: Bearer, vous devez envoyer une requête au point de terminaison issueToken. 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 Microsoft Entra ID. 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 ressource Speech.

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 YourSpeechResourceKey par votre clé de ressource du service Speech. Si votre ressource Speech n’est pas dans la région USA Ouest, remplacez l’en-tête par le Host nom d’hôte de votre région.

POST /sts/v1.0/issueToken HTTP/1.1
Ocp-Apim-Subscription-Key: YourSpeechResourceKey
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 YourSpeechResourceKey par votre clé de ressource du service Speech. Veillez à utiliser le point de terminaison approprié pour la région qui correspond à votre ressource Speech. Cet exemple est actuellement configuré pour l’USA Ouest.

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

$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 YourSpeechResourceKey par votre clé de ressource du service Speech. Veillez à utiliser le point de terminaison approprié pour la région qui correspond à votre ressource Speech. 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: YourSpeechResourceKey"

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 ressource Speech ne se trouve pas dans la région Ouest des États-Unis, modifiez la valeur de FetchTokenUri pour qu’elle corresponde à la région de votre ressource Speech.

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 l’authentification Microsoft Entra

Pour utiliser l’authentification Microsoft Entra avec l’API REST de reconnaissance vocale pour l’audio court, vous devez créer un jeton d’accès. Les étapes pour obtenir le jeton d’accès composé de l’ID de ressource et du jeton d’accès Microsoft Entra sont les mêmes que lors de l’utilisation du kit SDK Speech. Suivez les étapes fournies ici : Utiliser l’authentification Microsoft Entra

Créer une ressource Foundry pour 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 l’ID de ressource et le jeton d’accès Microsoft Entra 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 « # » (dièse) 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.

Étapes suivantes

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2025-10-21

Partager via

API REST de synthèse vocale

Obtenir une liste de voix

En-têtes de requête

Corps de la demande

Exemple de requête

Exemple de réponse

Codes d’état HTTP

Convertir du texte en parole

Régions et points de terminaison

Voix standard

Voix personnalisées

API Audio long

En-têtes de requête

Corps de la demande

Exemple de requête

Codes d’état HTTP

Sorties audio

Authentification

Obtenir un jeton d’accès

Exemple HTTP

Exemple de code PowerShell

Exemple cURL

Exemple de code C#

Exemple de code Python

Utiliser un jeton d’accès

Utiliser l’authentification Microsoft Entra

Étapes suivantes

Commentaires

Ressources supplémentaires