API Synthèse par lots pour la synthèse vocale

Article
04/11/2024

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.

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 est asynchrone et ne retourne pas l’audio synthétisé en temps réel. Vous envoyez des fichiers texte à synthétiser, interrogez l’état et téléchargez la sortie audio lorsque l’état indique la réussite de l’opération. Les entrées de texte doivent être au format texte brut ou texte SSML (Speech Synthesis Markup Language).

Le diagramme suivant donne une vue d’ensemble du workflow.

Diagramme du workflow de l’API Synthèse par lots.

Conseil

Vous pouvez également utiliser le Kit de développement logiciel (SDK) Speech pour créer un audio synthétisé de plus de 10 minutes en itérant sur le texte et en le synthétisant en blocs. Pour obtenir un exemple C#, consultez GitHub.

Vous pouvez utiliser les opérations d’API REST suivantes pour la synthèse par lots :

Opération	Méthode	Appel d’API REST
Créer une synthèse par lots	`PUT`	texttospeech/batchsyntheses/YourSynthesisId
Obtenir une synthèse par lots	`GET`	texttospeech/batchsyntheses/YourSynthesisId
Lister une synthèse par lots	`GET`	texttospeech/batchsyntheses
Supprimer une synthèse par lots	`DELETE`	texttospeech/batchsyntheses/YourSynthesisId

Pour obtenir des exemples de code, consultez GitHub.

Créer une synthèse par lots

Pour envoyer une requête de synthèse par lots, créez le chemin et le corps de la requête HTTP PUT selon les instructions suivantes :

Définissez la propriété requise inputKind.
Si la propriété inputKind est définie sur « PlainText », vous devez également définir la propriété voice dans synthesisConfig. Dans l’exemple ci-dessous, inputKind est défini sur « SSML », et synthesisConfig n’est donc pas défini.
Si vous le souhaitez, vous pouvez définir d’autres propriétés, comme description et timeToLiveInHours. Pour plus d’informations, consultez Propriétés de la synthèse par lots.

Remarque

La taille maximale de la charge utile JSON qui sera acceptée est de 2 mégaoctets. Chaque ressource Speech peut avoir jusqu’à 300 travaux de synthèse par lots qui s’exécutent simultanément.

Définissez le YourSynthesisId requis dans le chemin. Le YourSynthesisId doit être unique. Il doit comprendre entre 3 et 64 caractères, contenir uniquement des chiffres, des lettres, des traits d’union, des traits de soulignement et des points, et commencer et se terminer par une lettre ou un chiffre.

Effectuez une requête HTTP PUT en utilisant l’URI, comme illustré dans l’exemple suivant. Remplacez YourSpeechKey par votre clé de ressource Speech, remplacez YourSpeechRegion par votre région de ressource Speech et définissez les propriétés du corps de la requête comme décrit précédemment.

curl -v -X PUT -H "Ocp-Apim-Subscription-Key: YourSpeechKey" -H "Content-Type: application/json" -d '{
    "description": "my ssml test",
    "inputKind": "SSML",
    "inputs": [
        {
            "content": "<speak version=\"1.0\" xml:lang=\"en-US\"><voice name=\"en-US-JennyNeural\">The rainbow has seven colors.</voice></speak>"
        }
    ],
    "properties": {
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false,
        "concatenateResult": false,
        "decompressOutputFiles": false
    }
}'  "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01"

Vous devriez recevoir un corps de réponse au format suivant :

{
  "id": "YourSynthesisId",
  "internalId": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
  "status": "NotStarted",
  "createdDateTime": "2024-03-12T07:23:18.0097387Z",
  "lastActionDateTime": "2024-03-12T07:23:18.0097388Z",
  "inputKind": "SSML",
  "customVoices": {},
  "properties": {
    "timeToLiveInHours": 744,
    "outputFormat": "riff-24khz-16bit-mono-pcm",
    "concatenateResult": false,
    "decompressOutputFiles": false,
    "wordBoundaryEnabled": false,
    "sentenceBoundaryEnabled": false
  }
}

La propriété status doit passer de l’état NotStarted à Running, puis à l’état final Succeeded ou Failed. Vous pouvez appeler régulièrement l’API Synthèse par lots GET jusqu’à ce que l’état retourné soit Succeeded ou Failed.

Obtenir une synthèse par lots

Pour obtenir l’état du travail de synthèse par lots, effectuez une requête HTTP GET en utilisant l’URI comme indiqué dans l’exemple suivant. Remplacez YourSpeechKey par votre clé de ressource Speech et remplacez YourSpeechRegion par votre région de ressource Speech.

curl -v -X GET "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

Vous devriez recevoir un corps de réponse au format suivant :

{
  "id": "YourSynthesisId",
  "internalId": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
  "status": "Succeeded",
  "createdDateTime": "2024-03-12T07:23:18.0097387Z",
  "lastActionDateTime": "2024-03-12T07:23:18.7979669",
  "inputKind": "SSML",
  "customVoices": {},
  "properties": {
    "timeToLiveInHours": 744,
    "outputFormat": "riff-24khz-16bit-mono-pcm",
    "concatenateResult": false,
    "decompressOutputFiles": false,
    "wordBoundaryEnabled": false,
    "sentenceBoundaryEnabled": false,
    "sizeInBytes": 120000,
    "succeededAudioCount": 1,
    "failedAudioCount": 0,
    "durationInMilliseconds": 2500,
    "billingDetails": {
      "neuralCharacters": 29
    }
  },
  "outputs": {
    "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/YourSynthesisId/results.zip?SAS_Token"
  }
}

À partir de outputs.result, vous pouvez télécharger un fichier ZIP qui contient l’audio (0001.wav par exemple), un résumé et des détails de débogage. Pour plus d’informations, consultez Résultats de la synthèse par lots.

Lister une synthèse par lots

Pour lister tous les travaux de synthèse par lots pour la ressource Speech, effectuez une requête HTTP GET en utilisant l’URI comme indiqué dans l’exemple suivant. Remplacez YourSpeechKey par la clé de la ressource Speech et remplacez YourSpeechRegion par la région de la ressource Speech. Si vous le souhaitez, vous pouvez définir les paramètres de requête skip et maxpagesize (jusqu’à 100) dans l’URL. Les paramètres skip et maxpagesize ont les valeurs par défaut 0 et 100, respectivement.

curl -v -X GET "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses?api-version=2024-04-01&skip=1&maxpagesize=2" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

Vous devriez recevoir un corps de réponse au format suivant :

{
  "value": [
    {
      "id": "my-job-03",
      "internalId": "5f7e9ab6-2c92-4dcb-b5ee-ec0983ee4db0",
      "status": "Succeeded",
      "createdDateTime": "2024-03-12T07:28:32.5690441Z",
      "lastActionDateTime": "2024-03-12T07:28:33.0042293",
      "inputKind": "SSML",
      "customVoices": {},
      "properties": {
        "timeToLiveInHours": 744,
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "concatenateResult": false,
        "decompressOutputFiles": false,
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false,
        "sizeInBytes": 120000,
        "succeededAudioCount": 1,
        "failedAudioCount": 0,
        "durationInMilliseconds": 2500,
        "billingDetails": {
          "neuralCharacters": 29
        }
      },
      "outputs": {
        "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/my-job-03/results.zip?SAS_Token"
      }
    },
    {
      "id": "my-job-02",
      "internalId": "5577585f-4710-4d4f-aab6-162d14bd7ee0",
      "status": "Succeeded",
      "createdDateTime": "2024-03-12T07:28:29.6418211Z",
      "lastActionDateTime": "2024-03-12T07:28:30.0910306",
      "inputKind": "SSML",
      "customVoices": {},
      "properties": {
        "timeToLiveInHours": 744,
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "concatenateResult": false,
        "decompressOutputFiles": false,
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false,
        "sizeInBytes": 120000,
        "succeededAudioCount": 1,
        "failedAudioCount": 0,
        "durationInMilliseconds": 2500,
        "billingDetails": {
          "neuralCharacters": 29
        }
      },
      "outputs": {
        "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/my-job-02/results.zip?SAS_Token"
      }
    }
  ],
  "nextLink": "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses?skip=3&maxpagesize=2&api-version=2024-04-01"
}

La propriété value dans la réponse JSON liste vos requêtes de synthèse. La liste est paginée, avec une taille de page maximale de 100. La propriété "nextLink" est fournie si nécessaire pour obtenir la page suivante de la liste paginée.

Supprimer une synthèse par lots

Supprimez l’historique des travaux de synthèse par lots après avoir récupéré les résultats de sortie audio. Le service Speech conserve chaque historique de synthèse jusqu’à 31 jours, ou pendant la durée spécifiée par la propriété timeToLiveInHours de la requête, selon la première de ces éventualités. 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.

Pour supprimer un travail de synthèse par lots, effectuez une requête HTTP DELETE en utilisant l’URI comme indiqué dans l’exemple suivant. Remplacez YourSynthesisId par l’ID de la synthèse par lots, remplacez YourSpeechKey par la clé de la ressource Speech et remplacez YourSpeechRegion par la région de la ressource Speech.

curl -v -X DELETE "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

Les en-têtes de réponse contiennent HTTP/1.1 204 No Content si la requête de suppression a réussi.

Résultats de la synthèse par lots

Une fois que vous avez obtenu un travail de synthèse par lots avec l’état status « Réussite », vous pouvez télécharger les résultats de sortie audio. Utilisez l’URL figurant dans la propriété outputs.result de la réponse à la requête de synthèse par lots GET.

Pour obtenir le fichier de résultats de la synthèse par lots, effectuez une requête HTTP GET en utilisant l’URI comme indiqué dans l’exemple suivant. Remplacez YourOutputsResultUrl par l’URL figurant dans la propriété outputs.result de la réponse à la requête de synthèse par lots GET. Remplacez YourSpeechKey par votre clé de ressource Speech.

curl -v -X GET "YourOutputsResultUrl" -H "Ocp-Apim-Subscription-Key: YourSpeechKey" > results.zip

Les résultats sont fournis dans un fichier ZIP qui contient l’audio (0001.wav par exemple), un résumé et des détails de débogage. Le préfixe numéroté de chaque nom de fichier (illustré ci-dessous sous la forme [nnnn]) suit le même ordre que les entrées de texte que vous avez utilisées au moment de la création de la synthèse par lots.

Remarque

Le fichier [nnnn].debug.json contient l’ID du résultat de la synthèse et d’autres informations utiles pour résoudre d’éventuels problèmes. Du fait que les propriétés dans ce fichier sont susceptibles de changer, vous ne devez pas avoir de dépendances sur le format JSON.

Le fichier de résumé contient les résultats de la synthèse pour chaque entrée de texte. Voici un exemple de fichier summary.json :

{
  "jobID": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
  "status": "Succeeded",
  "results": [
    {
      "contents": [
        "<speak version=\"1.0\" xml:lang=\"en-US\"><voice name=\"en-US-JennyNeural\">The rainbow has seven colors.</voice></speak>"
      ],
      "status": "Succeeded",
      "audioFileName": "0001.wav",
      "properties": {
        "sizeInBytes": "120000",
        "durationInMilliseconds": "2500"
      }
    }
  ]
}

Quand des données de limite de phrase sont demandées ("sentenceBoundaryEnabled": true), un fichier [nnnn].sentence.json correspondant est inclus dans les résultats. De la même façon, si des données de limite de mot sont demandées ("wordBoundaryEnabled": true), un fichier [nnnn].word.json correspondant est inclus dans les résultats.

Voici un exemple de fichier de données de mot qui spécifie un décalage audio et une durée en millisecondes :

[
  {
    "Text": "The",
    "AudioOffset": 50,
    "Duration": 137
  },
  {
    "Text": "rainbow",
    "AudioOffset": 200,
    "Duration": 350
  },
  {
    "Text": "has",
    "AudioOffset": 562,
    "Duration": 175
  },
  {
    "Text": "seven",
    "AudioOffset": 750,
    "Duration": 300
  },
  {
    "Text": "colors",
    "AudioOffset": 1062,
    "Duration": 625
  },
  {
    "Text": ".",
    "AudioOffset": 1700,
    "Duration": 100
  }
]

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 PUT) 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.
Vous avez essayé de créer un travail de synthèse par lots qui dépassera la limite de 300 travaux actifs. Chaque ressource Speech prend en charge jusqu’à 300 travaux de synthèse par lots qui n’ont pas l’état « Réussite » ou « Échec ».

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

API Synthèse par lots pour la synthèse vocale

Créer une synthèse par lots

Obtenir une synthèse par lots

Lister une synthèse par lots

Supprimer une synthèse par lots

Résultats de la synthèse par lots

Latence de synthèse par lots et meilleures pratiques

Latence dans la synthèse par lots

Bonnes pratiques

Codes d’état HTTP

HTTP 200 OK

HTTP 201 Created

Erreur HTTP 204

Erreur HTTP 400

Erreur HTTP 404

Erreur HTTP 429

Erreur HTTP 500

Exemple d’erreur HTTP

Étapes suivantes

Ressources supplémentaires