Partage via

Propriétés de synthèse par lots pour la synthèse vocale

  • Article

Important

L’API Synthèse par lots est en disponibilité générale. L’API Audio long sera retirée le 1er avril 2027. Pour plus d’informations, consultez Migrer vers l’API Synthèse par lots.

L’API Synthèse par lots peut synthétiser un grand volume d’entrées de texte (longues et courtes) de manière asynchrone. Les éditeurs et les plateformes de contenu audio peuvent créer du contenu audio long dans un lot. Par exemple : livres audio, articles de presse et documents. L’API Synthèse par lots peut créer du contenu audio synthétisé d’une durée de plus de 10 minutes.

Certaines propriétés au format JSON sont requises lorsque vous créez un nouveau travail de synthèse par lots. Les autres propriétés sont facultatives. La réponse de la synthèse par lots inclut d’autres propriétés pour fournir des informations sur l’état et les résultats de la synthèse. Par exemple, la propriété outputs.resultcontient l’emplacement des fichiers de résultats de la synthèse par lots, contenant la sortie audio et les journaux.

Propriétés de la synthèse par lots

Les propriétés de la synthèse par lots sont décrites dans ce tableau.

Propriété Description
createdDateTime Date et heure de création du travail de synthèse par lots.

Cette propriété est en lecture seule.
customVoices Mappage entre un nom de voix personnalisé et son ID de déploiement.

Par exemple : "customVoices": {"your-custom-voice-name": "502ac834-6537-4bc3-9fd6-140114daa66d"}

Vous pouvez utiliser le nom de la voix dans votre synthesisConfig.voice (quand inputKind est défini sur "PlainText") ou dans le texte SSML de inputs (quand inputKind est défini sur "SSML").

Cette propriété doit obligatoirement être définie pour utiliser une voix personnalisée. Si vous essayez d’utiliser une voix personnalisée qui n’est pas définie ici, le service retourne une erreur.
description Description de la synthèse par lots.

Cette propriété est facultative.
id ID de travail de synthèse par lots que vous avez transmis dans le chemin d’accès.

Cette propriété est requise dans le chemin d'accès.
inputs Texte brut ou SSML à synthétiser.

Quand inputKind est défini sur "PlainText", fournissez le texte brut comme indiqué ici : "inputs": [{"text": "The rainbow has seven colors."}]. Quand inputKind est défini sur "SSML", fournissez le texte dans le langage SSML (Speech Synthesis Markup Language) comme illustré ici : "inputs": [{"text": "<speak version='\''1.0'\'' xml:lang='\''en-US'\''><voice xml:lang='\''en-US'\'' xml:gender='\''Female'\'' name='\''en-US-AvaMultilingualNeural'\''>The rainbow has seven colors.</voice></speak>"}].

Vous pouvez inclure jusqu’à 1 000 objets texte si vous souhaitez obtenir plusieurs fichiers de sortie audio. Voici un exemple de texte d’entrée qui doit être synthétisé vers deux fichiers de sortie audio : "inputs": [{"text": "synthesize this to a file"},{"text": "synthesize this to another file"}]. Toutefois, si la propriété properties.concatenateResult a la valeur true, chaque résultat synthétisé est écrit dans le même fichier de sortie audio.

Vous n’avez pas besoin de spécifier des entrées de texte séparées pour les nouveaux paragraphes. Dans l’une des entrées de texte (1 000 au maximum), vous pouvez spécifier de nouveaux paragraphes avec la chaîne « \r\n » (nouvelle ligne). Voici un exemple de texte d’entrée avec deux paragraphes qui doivent être synthétisés vers le même fichier de sortie audio : "inputs": [{"text": "synthesize this to a file\r\nsynthesize this to another paragraph in the same file"}]

Il n’y a pas de limites de paragraphes, mais la taille maximale de la charge utile JSON (y compris toutes les entrées de texte et autres propriétés) est de 2 mégaoctets.

Cette propriété doit obligatoirement être définie pour créer un travail de synthèse par lots. Cette propriété n’est pas incluse dans la réponse lorsque vous obtenez le travail de synthèse.
internalId ID du travail de synthèse par lots interne.

Cette propriété est en lecture seule.
lastActionDateTime Date et heure du dernier changement apporté à la valeur de la propriété status.

Cette propriété est en lecture seule.
outputs.result Emplacement des fichiers de résultats de la synthèse par lots, contenant la sortie audio et les journaux.

Cette propriété est en lecture seule.
properties Ensemble défini des paramètres facultatifs de configuration de la synthèse par lots.
properties.sizeInBytes Taille de la sortie audio, en octets.

Cette propriété est en lecture seule.
properties.billingDetails Nombre de mots qui ont été traités et facturés par customNeuralCharacters par rapport aux voix (prédéfinies) neuralCharacters.

Cette propriété est en lecture seule.
properties.concatenateResult Détermine s’il faut concaténer le résultat. Cette valeur bool facultative (« true » ou « false ») est « false » par défaut.
properties.decompressOutputFiles Détermine s’il faut décompresser les fichiers de résultats de la synthèse dans le conteneur de destination. Cette propriété peut uniquement être définie quand destinationContainerUrl est défini. Cette valeur bool facultative (« true » ou « false ») est « false » par défaut.
properties.destinationContainerUrl Les résultats de la synthèse par lots peuvent être stockés dans un conteneur Azure accessible en écriture. Si vous ne spécifiez pas d’URI de conteneur avec le jeton des signatures d'accès partagé (SAS), le service Speech stocke les résultats dans un conteneur géré par Microsoft. Les signatures SAS avec des stratégies d’accès stockées ne sont pas prises en charge. Quand le travail de synthèse est supprimé, les données de résultats sont supprimées également.

Cette propriété facultative n’est pas incluse dans la réponse lorsque vous obtenez le travail de synthèse.
properties.destinationPath Chemin d’accès de préfixe dans lequel les résultats de synthèse par lots peuvent être stockés. Si vous ne spécifiez pas de chemin de préfixe, le chemin de préfixe par défaut est YourSpeechResourceId/YourSynthesisId.

Cette propriété facultative peut uniquement être définie quand destinationContainerUrl est défini.
properties.durationInMilliseconds Durée de la sortie audio en millisecondes.

Cette propriété est en lecture seule.
properties.failedAudioCount Nombre d’entrées de synthèse par lots dans la sortie audio qui ont échoué.

Cette propriété est en lecture seule.
properties.outputFormat Format de la sortie audio.

Pour plus d’informations sur les valeurs acceptées, consultez Formats de sortie audio. Le format de sortie par défaut est riff-24khz-16bit-mono-pcm.
properties.sentenceBoundaryEnabled Détermine s’il faut générer des données de limite de phrase. Cette valeur bool facultative (« true » ou « false ») est « false » par défaut.

Si des données de limite de phrase sont demandées, un fichier [nnnn].sentence.json correspondant est inclus dans le fichier ZIP des résultats.
properties.succeededAudioCount Nombre d’entrées de synthèse par lots dans la sortie audio qui ont réussi.

Cette propriété est en lecture seule.
properties.timeToLiveInHours Durée en heures entre la fin de la création du travail de synthèse et la suppression automatique des résultats de la synthèse. Ce paramètre facultatif est 744 (31 jours) par défaut. La durée de conservation maximale est de 31 jours. La date et l’heure de la suppression automatique (pour les travaux de synthèse ayant l’état « Réussite » ou « Échec ») sont celles définies par les propriétés lastActionDateTime + timeToLiveInHours.

Sinon, vous pouvez appeler la méthode delete pour supprimer le travail de synthèse plus tôt.
properties.wordBoundaryEnabled Détermine s’il faut générer des données de limite de mot. Cette valeur bool facultative (« true » ou « false ») est « false » par défaut.

Si des données de limite de mot sont demandées, un fichier [nnnn].word.json correspondant est inclus dans le fichier ZIP des résultats.
status État du traitement de la synthèse par lots.

L’état doit passer de « NotStarted » à « Running », et enfin à « Succeeded » ou « Failed ».

Cette propriété est en lecture seule.
synthesisConfig Paramètres de configuration à utiliser pour la synthèse par lots de texte brut.

Cette propriété s'applique uniquement quand inputKind est défini à "PlainText".
synthesisConfig.backgroundAudio Audio d’arrière-plan pour chaque sortie audio.

Cette propriété facultative s’applique uniquement quand inputKind est défini à "PlainText".
synthesisConfig.backgroundAudio.fadein Durée de l’apparition en fondu du fond sonore, en millisecondes. La valeur par défaut est 0, ce qui équivaut à aucune apparition en fondu audio. Valeurs acceptées : 0 à 10000 inclus.

Pour plus d’informations, consultez le tableau des attributs sous Ajouter des audios d’arrière-plan dans la documentation Speech Synthesis Markup Language (SSML). Les valeurs non valides sont ignorées.

Cette propriété facultative s’applique uniquement quand inputKind est défini à "PlainText".
synthesisConfig.backgroundAudio.fadeout Spécifie la durée de la disparition en fondu du fond sonore, en millisecondes. La valeur par défaut est 0, ce qui équivaut à aucune disparition en fondu. Valeurs acceptées : 0 à 10000, inclus.

Pour plus d’informations, consultez le tableau des attributs sous Ajouter des audios d’arrière-plan dans la documentation Speech Synthesis Markup Language (SSML). Les valeurs non valides sont ignorées.

Cette propriété facultative s’applique uniquement quand inputKind est défini à "PlainText".
synthesisConfig.backgroundAudio.src Emplacement URI du fichier audio de fond sonore.

Pour plus d’informations, consultez le tableau des attributs sous Ajouter des audios d’arrière-plan dans la documentation Speech Synthesis Markup Language (SSML). Les valeurs non valides sont ignorées.

Cette propriété est requise quand synthesisConfig.backgroundAudio est défini.
synthesisConfig.backgroundAudio.volume Volume du fichier audio de fond sonore. Valeurs acceptées : 0 à 100 inclus. La valeur par défaut est 1.

Pour plus d’informations, consultez le tableau des attributs sous Ajouter des audios d’arrière-plan dans la documentation Speech Synthesis Markup Language (SSML). Les valeurs non valides sont ignorées.

Cette propriété facultative s’applique uniquement quand inputKind est défini à "PlainText".
synthesisConfig.pitch Tonalité de la sortie audio.

Pour plus d’informations sur les valeurs acceptées, consultez le tableau d’ajustement de la prosodie dans la documentation SSML (Speech Synthesis Markup Language). Les valeurs non valides sont ignorées.

Cette propriété facultative s’applique uniquement quand inputKind est défini à "PlainText".
synthesisConfig.rate Débit de la sortie audio.

Pour plus d’informations sur les valeurs acceptées, consultez le tableau d’ajustement de la prosodie dans la documentation SSML (Speech Synthesis Markup Language). Les valeurs non valides sont ignorées.

Cette propriété facultative s’applique uniquement quand inputKind est défini à "PlainText".
synthesisConfig.role Pour certaines voix, vous pouvez ajuster le jeu de rôle. La voix peut imiter un âge et un sexe différents, mais son nom ne change pas. Par exemple, une voix masculine peut devenir plus aiguë, puis changer d’intonation pour imiter une voix féminine, mais le nom de la voix ne change pas. Si le rôle est manquant ou non pris en charge pour votre voix, cet attribut est ignoré.

Pour plus d’informations sur les styles disponibles selon la voix, consultez Styles et rôles vocaux.

Cette propriété facultative s’applique uniquement quand inputKind est défini à "PlainText".
synthesisConfig.speakerProfileId L’ID de profil d’orateur d’une voix personnelle.

Pour plus d’informations sur les noms de modèles de base vocaux personnels disponibles, consultez intégrer une voix personnelle.
Pour plus d’informations sur l’obtention de l’ID de profil de l’orateur, consultez Prise en charge de la langue et de la voix.

Cette propriété est requise quand inputKind a la valeur "PlainText".
synthesisConfig.style Pour certaines voix, vous pouvez ajuster le style d’élocution afin d’exprimer des émotions différentes, telles que la gaieté, l’empathie et le calme. Vous pouvez optimiser la voix pour différents scénarios (service clientèle, diffusion d’actualités, assistant vocal, etc.).

Pour plus d’informations sur les styles disponibles selon la voix, consultez Styles et rôles vocaux.

Cette propriété facultative s’applique uniquement quand synthesisConfig.style est défini.
synthesisConfig.styleDegree Intensité du style d’élocution. Vous pouvez spécifier un style plus fort ou plus doux pour rendre la voix plus expressive ou feutrée. La plage de valeurs acceptées est : 0,01 à 2 inclus. La valeur par défaut est 1, ce qui correspond à l’intensité de style prédéfinie. L’unité minimale est 0,01, ce qui aboutit à une légère tendance pour le style cible. La valeur 2 produit un doublement de l’intensité de style par défaut. Si le degré de style est manquant ou non pris en charge pour votre voix, cet attribut est ignoré.

Pour plus d’informations sur les styles disponibles selon la voix, consultez Styles et rôles vocaux.

Cette propriété facultative s’applique uniquement quand inputKind est défini à "PlainText".
synthesisConfig.voice Voix qui lit la sortie audio.

Pour plus d’informations sur les voix neuronales prédéfinies disponibles, consultez Prise en charge des langues et des voix. Pour utiliser une voix personnalisée, vous devez spécifier un mappage valide entre l’ID de déploiement et la voix personnalisée dans la propriété customVoices. Pour utiliser une voix personnelle, vous devez spécifier la propriété synthesisConfig.speakerProfileId.

Cette propriété est requise quand inputKind a la valeur "PlainText".
synthesisConfig.volume Volume de la sortie audio.

Pour plus d’informations sur les valeurs acceptées, consultez le tableau d’ajustement de la prosodie dans la documentation SSML (Speech Synthesis Markup Language). Les valeurs non valides sont ignorées.

Cette propriété facultative s’applique uniquement quand inputKind est défini à "PlainText".
inputKind Indique si la propriété de texte inputs doit être texte brut ou SSML. Les valeurs possibles (sans respect de la casse) sont « PlainText » et « SSML ». Lorsque inputKind est défini sur "PlainText", vous devez également définir la propriété de voix synthesisConfig.

Cette propriété est requise.

Latence de synthèse par lots et meilleures pratiques

Lorsque vous utilisez la synthèse par lots pour générer des paroles synthétisées, il est important de tenir compte de la latence impliquée et de suivre les meilleures pratiques pour obtenir des résultats optimaux.

Latence dans la synthèse par lots

La latence dans la synthèse par lots dépend de différents facteurs, notamment la complexité du texte d’entrée, le nombre d’entrées dans le lot et les capacités de traitement du matériel sous-jacent.

La latence pour la synthèse par lots est la suivante (approximativement) :

  • La latence de 50 % des sorties vocales synthétisées est de 10 à 20 secondes.

  • La latence de 95 % des sorties vocales synthétisées est de 120 secondes.

Bonnes pratiques

Lorsque vous envisagez la synthèse par lots pour votre application, il est recommandé d’évaluer si la latence répond à vos besoins. Si la latence s’aligne sur les performances souhaitées, la synthèse par lots peut être un choix approprié. Toutefois, si la latence ne répond pas à vos besoins, vous pouvez envisager d’utiliser l’API en temps réel.

Codes d’état HTTP

La section détaille les codes de réponse HTTP et les messages envoyés par l’API Synthèse par lots.

HTTP 200 OK

HTTP 200 OK indique que la requête a réussi.

HTTP 201 Created

HTTP 201 Created indique que la requête de création de la synthèse par lots (via HTTP POST) a réussi.

Erreur HTTP 204

Une erreur HTTP 204 indique que la requête a réussi, mais que la ressource n’existe pas. Par exemple :

  • Vous avez essayé d’obtenir ou de supprimer un travail de synthèse qui n’existe pas.
  • Vous avez réussi à supprimer un travail de synthèse.

Erreur HTTP 400

Voici des exemples qui peuvent générer l’erreur 400 :

  • Le paramètre outputFormat n’est pas pris en charge ou n’est pas valide. Fournissez une valeur de format valide, ou laissez outputFormat vide pour utiliser le paramètre par défaut.
  • Le nombre d’entrées de texte demandées a dépassé la limite de 10 000.
  • Vous avez essayé d’utiliser un ID de déploiement non valide ou une voix personnalisée qui n’est pas correctement déployée. Vérifiez que la ressource Speech a accès à la voix personnalisée et que la voix personnalisée est correctement déployée. Vous devez également vous assurer que le mappage de {"your-custom-voice-name": "your-deployment-ID"} est correct dans votre requête de synthèse par lots.
  • Vous avez essayé d’utiliser une ressource Speech F0, mais la région prend uniquement en charge le niveau tarifaire Standard pour la ressource Speech.

Erreur HTTP 404

L’entité spécifiée est introuvable. Vérifiez que l’ID de synthèse est correct.

Erreur HTTP 429

Il y a trop de requêtes récentes. Chaque application cliente peut envoyer jusqu’à 100 requêtes toutes les 10 secondes pour chaque ressource Speech. Réduisez le nombre de requêtes par seconde.

Erreur HTTP 500

L’erreur serveur interne HTTP 500 indique que la requête a échoué. Le corps de la réponse contient le message d’erreur.

Exemple d’erreur HTTP

Voici un exemple de requête qui aboutit à une erreur HTTP 400, car la propriété inputs est obligée de créer un travail.

curl -v -X PUT -H "Ocp-Apim-Subscription-Key: YourSpeechKey" -H "Content-Type: application/json" -d '{
    "inputKind": "SSML"
}'  "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01"

Dans ce cas, les en-têtes de réponse incluent HTTP/1.1 400 Bad Request.

Le corps de la réponse ressemble à l’exemple JSON suivant :

{
  "error": {
    "code": "BadRequest",
    "message": "The inputs is required."
  }
}

Étapes suivantes