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

Article
09/12/2024

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."
  }
}

Partager via