Comme utiliser la synthèse par lots de l’avatar de synthèse vocale

Article
09/11/2024

L’API de synthèse par lots pour l’avatar de synthèse vocale permet la synthèse asynchrone du texte dans un avatar parlant en tant que fichier vidéo. Les éditeurs et les plateformes de contenu vidéo peuvent utiliser cette API pour créer du contenu vidéo d’avatar dans un lot. Cette approche peut convenir à différents cas d’usage tels que des supports de formation, des présentations ou des publicités.

La vidéo d’avatar synthétique sera générée de manière asynchrone une fois que le système reçoit une entrée de texte. La sortie de la vidéo générée peut être téléchargée comme synthèse en mode par lots. Vous envoyez du texte pour la synthèse, interrogez l’état de la synthèse et téléchargez la sortie vidéo 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.

Pour effectuer la synthèse par lots, vous pouvez utiliser les opérations d’API REST suivantes.

Operation	Méthode	Appel d’API REST
Créer une synthèse par lots	PUT	avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01
Obtenir une synthèse par lots	GET	avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01
Répertorier une synthèse par lots	GET	avatar/batchsyntheses/?api-version=2024-08-01
Supprimer une synthèse par lots	DELETE	avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01

Vous pouvez consulter l’exemple de code sur GitHub.

Créer une requête de synthèse par lots

Certaines propriétés au format JSON sont nécessaire 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.result contient l’emplacement à partir duquel vous pouvez télécharger un fichier vidéo contenant la vidéo de l’avatar. À partir de outputs.summary, vous pouvez accéder au résumé et aux détails du débogage.

Pour envoyer une requête de synthèse par lots, créez le corps de la requête HTTP POST 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, speechSynthesis n’est donc pas défini.
Définissez la propriété requise SynthesisId. Choisissez un attribut SynthesisId unique pour la même ressource vocale. L’attribut SynthesisId peut être une chaîne de 3 à 64 caractères, y compris des lettres, des chiffres, « - » ou « _ », qui doit commencer et se terminer par une lettre ou un chiffre.
Définissez les propriétés talkingAvatarCharacter et talkingAvatarStyle nécessaires. Vous trouverez ici les personnages et les styles d’avatar pris en charge.
Si vous le souhaitez, vous pouvez définir d’autres propriétés, comme videoFormat et backgroundColor. Pour plus d’informations, consultez Propriétés de la synthèse par lots.

Remarque

La taille maximale acceptée pour la charge utile JSON est de 500 kilo-octets.

Chaque ressource Speech peut avoir jusqu’à 200 travaux de synthèse par lots qui s’exécutent simultanément.

La durée maximale de la vidéo de sortie est actuellement de 20 minutes, avec des augmentations possibles à l’avenir.

Pour effectuer une requête HTTP PUT, utilisez le format URI indiqué dans l’exemple suivant. Remplacez YourSpeechKey par votre clé de ressource Speech, YourSpeechRegion par votre région de ressource Speech et définissez les propriétés du corps de la requête comme décrit ci-dessus.

curl -v -X PUT -H "Ocp-Apim-Subscription-Key: YourSpeechKey" -H "Content-Type: application/json" -d '{
    "inputKind": "SSML",
    "inputs": [
        {
         "content": "<speak version='\''1.0'\'' xml:lang='\''en-US'\''><voice name='\''en-US-AvaMultilingualNeural'\''>The rainbow has seven colors.</voice></speak>"
        }
    ],
    "avatarConfig": {
        "talkingAvatarCharacter": "lisa",
        "talkingAvatarStyle": "graceful-sitting"
    }
}'  "https://YourSpeechRegion.api.cognitive.microsoft.com/avatar/batchsyntheses/my-job-01?api-version=2024-08-01"

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

{
    "id": "my-job-01",
    "internalId": "5a25b929-1358-4e81-a036-33000e788c46",
    "status": "NotStarted",
    "createdDateTime": "2024-03-06T07:34:08.9487009Z",
    "lastActionDateTime": "2024-03-06T07:34:08.9487012Z",
    "inputKind": "SSML",
    "customVoices": {},
    "properties": {
        "timeToLiveInHours": 744,
    },
    "avatarConfig": {
        "talkingAvatarCharacter": "lisa",
        "talkingAvatarStyle": "graceful-sitting",
        "videoFormat": "Mp4",
        "videoCodec": "hevc",
        "subtitleType": "soft_embedded",
        "bitrateKbps": 2000,
        "customized": 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 récupérer l’état d’une travail de synthèse par lots, effectuez une requête HTTP GET en utilisant l’URI comme indiqué dans l’exemple suivant.

Remplacez YourSynthesisId par l’ID de la synthèse par lots, YourSpeechKey par la clé de la ressource Speech et YourSpeechRegion par la région de la ressource Speech.

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

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

{
    "id": "my-job-01",
    "internalId": "5a25b929-1358-4e81-a036-33000e788c46",
    "status": "Succeeded",
    "createdDateTime": "2024-03-06T07:34:08.9487009Z",
    "lastActionDateTime": "2024-03-06T07:34:12.5698769",
    "inputKind": "SSML",
    "customVoices": {},
    "properties": {
        "timeToLiveInHours": 744,
        "sizeInBytes": 344460,
        "durationInMilliseconds": 2520,
        "succeededCount": 1,
        "failedCount": 0,
        "billingDetails": {
            "neuralCharacters": 29,
            "talkingAvatarDurationSeconds": 2
        }
    },
    "avatarConfig": {
        "talkingAvatarCharacter": "lisa",
        "talkingAvatarStyle": "graceful-sitting",
        "videoFormat": "Mp4",
        "videoCodec": "hevc",
        "subtitleType": "soft_embedded",
        "bitrateKbps": 2000,
        "customized": false
    },
    "outputs": {
        "result": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/0001.mp4?SAS_Token",
        "summary": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/summary.json?SAS_Token"
    }
}

Depuis le champ outputs.result, vous pouvez télécharger un fichier vidéo contenant la vidéo d’avatar. Le champ outputs.summary vous permet de télécharger le résumé et les détails du débogage. Pour plus d’informations sur les résultats de synthèse par lots, consultez les résultats de synthèse par lots.

Lister une synthèse par lots

Pour répertorier tous les travaux de synthèse par lots pour votre 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 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 top (taille de page) 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/avatar/batchsyntheses?skip=0&maxpagesize=2&api-version=2024-08-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

Vous recevez un corps de réponse au format suivant :

{
    "value": [
        {
            "id": "my-job-02",
            "internalId": "14c25fcf-3cb6-4f46-8810-ecad06d956df",
            "status": "Succeeded",
            "createdDateTime": "2024-03-06T07:52:23.9054709Z",
            "lastActionDateTime": "2024-03-06T07:52:29.3416944",
            "inputKind": "SSML",
            "customVoices": {},
            "properties": {
                "timeToLiveInHours": 744,
                "sizeInBytes": 502676,
                "durationInMilliseconds": 2950,
                "succeededCount": 1,
                "failedCount": 0,
                "billingDetails": {
                    "neuralCharacters": 32,
                    "talkingAvatarDurationSeconds": 2
                }
            },
            "avatarConfig": {
                "talkingAvatarCharacter": "lisa",
                "talkingAvatarStyle": "casual-sitting",
                "videoFormat": "Mp4",
                "videoCodec": "h264",
                "subtitleType": "soft_embedded",
                "bitrateKbps": 2000,
                "customized": false
            },
            "outputs": {
                "result": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/0001.mp4?SAS_Token",
                "summary": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/summary.json?SAS_Token"
            }
        },
        {
            "id": "my-job-01",
            "internalId": "5a25b929-1358-4e81-a036-33000e788c46",
            "status": "Succeeded",
            "createdDateTime": "2024-03-06T07:34:08.9487009Z",
            "lastActionDateTime": "2024-03-06T07:34:12.5698769",
            "inputKind": "SSML",
            "customVoices": {},
            "properties": {
                "timeToLiveInHours": 744,
                "sizeInBytes": 344460,
                "durationInMilliseconds": 2520,
                "succeededCount": 1,
                "failedCount": 0,
                "billingDetails": {
                    "neuralCharacters": 29,
                    "talkingAvatarDurationSeconds": 2
                }
            },
            "avatarConfig": {
                "talkingAvatarCharacter": "lisa",
                "talkingAvatarStyle": "graceful-sitting",
                "videoFormat": "Mp4",
                "videoCodec": "hevc",
                "subtitleType": "soft_embedded",
                "bitrateKbps": 2000,
                "customized": false
            },
            "outputs": {
                "result": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/0001.mp4?SAS_Token",
                "summary": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/summary.json?SAS_Token"
            }
        }
    ],
    "nextLink": "https://YourSpeechRegion.api.cognitive.microsoft.com/avatar/batchsyntheses/?api-version=2024-08-01&skip=2&maxpagesize=2"
}

Depuis outputs.result, vous pouvez télécharger un fichier vidéo contenant la vidéo d’avatar. À partir de outputs.summary, vous pouvez accéder au résumé et aux détails du débogage. Pour plus d’informations, consultez Résultats de la synthèse par lots.

La propriété value dans la réponse JSON répertorie 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.

Obtenir le fichier de résultats de synthèse par lots

Une fois un travail de synthèse par lots avec status en tant que « Réussite » obtenu, 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" > output.mp4

Pour obtenir le fichier de résumé 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.summary 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 "YourOutputsSummaryUrl" -H "Ocp-Apim-Subscription-Key: YourSpeechKey" > summary.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": "5a25b929-1358-4e81-a036-33000e788c46",
  "status": "Succeeded",
  "results": [
    {
      "texts": [
        "<speak version='1.0' xml:lang='en-US'><voice name='en-US-AvaMultilingualNeural'>The rainbow has seven colors.</voice></speak>"
      ],
      "status": "Succeeded",
      "videoFileName": "244a87c294b94ddeb3dbaccee8ffa7eb/5a25b929-1358-4e81-a036-33000e788c46/0001.mp4",
      "TalkingAvatarCharacter": "lisa",
      "TalkingAvatarStyle": "graceful-sitting"
    }
  ]
}

Supprimer une synthèse par lots

Après avoir récupéré les résultats de sortie audio et une fois que vous n’avez plus besoin de l’historique des travaux de synthèse par lots, vous pouvez le supprimer. 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 suppression automatique, pour les travaux de synthèse avec l’état « Réussite » ou « Échec », sont calculées comme la somme des propriétés lastActionDateTime et timeToLive.

Pour supprimer un travail de synthèse par lots, effectuez une requête HTTP DELETE à l’aide du format URI suivant. Remplacez YourSynthesisId par l’ID de la synthèse par lots, YourSpeechKey par la clé de la ressource Speech et YourSpeechRegion par la région de la ressource Speech.

curl -v -X DELETE "https://YourSpeechRegion.api.cognitive.microsoft.com/avatar/batchsyntheses/YourSynthesisId?api-version=2024-08-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.

Partager via

Comme utiliser la synthèse par lots de l’avatar de synthèse vocale

Créer une requête de synthèse par lots

Obtenir une synthèse par lots

Lister une synthèse par lots

Obtenir le fichier de résultats de synthèse par lots

Supprimer une synthèse par lots

Étapes suivantes

Commentaires

Ressources supplémentaires