Udostępnij za pośrednictwem

Jak używać syntezy wsadowej do zamiany tekstu na mowę awatara

  • Artykuł

Interfejs API syntezy wsadowej tekstu na mowę awatar umożliwia asynchroniczną syntezę tekstu w mówiący awatar jako plik wideo. Wydawcy i platformy zawartości wideo mogą używać tego interfejsu API do tworzenia zawartości wideo awatara w partii. Takie podejście może być odpowiednie dla różnych przypadków użycia, takich jak materiały szkoleniowe, prezentacje lub reklamy.

Syntetyczny film awatara zostanie wygenerowany asynchronicznie po otrzymaniu przez system tekstu. Wygenerowane dane wyjściowe wideo można pobrać w trybie wsadowym syntezy. Przesyłasz tekst do syntezy, sonduj stan syntezy i pobierasz dane wyjściowe wideo, gdy stan wskazuje powodzenie. Formaty wprowadzania tekstu muszą być zwykłym tekstem lub tekstem języka SSML (Speech Synthesis Markup Language).

Ten diagram zawiera ogólne omówienie przepływu pracy.

Zrzut ekranu przedstawiający ogólny przegląd przepływu pracy syntezy wsadowej.

Do przeprowadzenia syntezy wsadowej można użyć następujących operacji interfejsu API REST.

Operacja Method Wywołanie interfejsu API REST
Tworzenie syntezy wsadowej ODŁÓŻ avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01
Pobieranie syntezy wsadowej GET avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01
Lista syntezy wsadowej GET avatar/batchsyntheses/?api-version=2024-08-01
Usuwanie syntezy wsadowej DELETE avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01

Przykłady kodu można znaleźć w witrynie GitHub.

Tworzenie żądania syntezy wsadowej

Niektóre właściwości w formacie JSON są wymagane podczas tworzenia nowego zadania syntezy wsadowej. Inne właściwości są opcjonalne. Odpowiedź syntezy wsadowej zawiera inne właściwości zapewniające informacje o stanie syntezy i wynikach. Na przykład outputs.result właściwość zawiera lokalizację, z której można pobrać plik wideo zawierający wideo awatara. Z outputs.summaryprogramu możesz uzyskać dostęp do podsumowania i szczegółów debugowania.

Aby przesłać żądanie syntezy wsadowej, skonstruuj treść żądania HTTP POST, wykonując następujące instrukcje:

  • Ustaw wymaganą inputKind właściwość.
  • Jeśli właściwość jest ustawiona inputKind na PlainText, należy również ustawić voice właściwość w obiekcie synthesisConfig. W poniższym inputKind przykładzie parametr jest ustawiony na SSMLwartość , więc speechSynthesis parametr nie jest ustawiony.
  • Ustaw wymaganą SynthesisId właściwość. Wybierz unikatowy dla SynthesisId tego samego zasobu mowy. Może SynthesisId to być ciąg o długości od 3 do 64 znaków, w tym litery, cyfry, "-" lub "_", z warunkiem, że musi zaczynać się i kończyć literą lub cyfrą.
  • Ustaw wymagane właściwości talkingAvatarCharacter i talkingAvatarStyle . Obsługiwane znaki awatara i style można znaleźć tutaj.
  • Opcjonalnie można ustawić videoFormatwłaściwości , backgroundColori inne. Aby uzyskać więcej informacji, zobacz właściwości syntezy wsadowej.

Uwaga

Maksymalny akceptowany rozmiar ładunku JSON to 500 kilobajtów.

Każdy zasób usługi Mowa może mieć maksymalnie 200 zadań syntezy wsadowej uruchomionych współbieżnie.

Maksymalna długość wyjściowego wideo wynosi obecnie 20 minut, a w przyszłości potencjalny wzrost.

Aby wykonać żądanie HTTP PUT, użyj formatu identyfikatora URI pokazanego w poniższym przykładzie. Zastąp YourSpeechKey ciąg kluczem zasobu usługi Mowa regionem YourSpeechRegion zasobu usługi Mowa i ustaw właściwości treści żądania zgodnie z powyższym opisem.

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"

Treść odpowiedzi powinna zostać wyświetlona w następującym formacie:

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

Właściwość status powinna przechodzić od NotStarted stanu do Running i na koniec do Succeeded lub Failed. Interfejs API syntezy wsadowej GET można okresowo wywoływać do momentu, gdy zwrócony stan to Succeeded lub Failed.

Pobieranie syntezy wsadowej

Aby pobrać stan zadania syntezy wsadowej, utwórz żądanie HTTP GET przy użyciu identyfikatora URI, jak pokazano w poniższym przykładzie.

Zastąp YourSynthesisId ciąg identyfikatorem YourSpeechKey syntezy wsadowej, kluczem zasobu usługi Mowa i YourSpeechRegion regionem zasobu usługi Mowa.

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

Treść odpowiedzi powinna zostać wyświetlona w następującym formacie:

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

outputs.result W polu możesz pobrać plik wideo zawierający wideo z awatarem. Pole outputs.summary umożliwia pobranie podsumowania i szczegółów debugowania. Aby uzyskać więcej informacji na temat wyników syntezy wsadowej, zobacz wyniki syntezy wsadowej.

Lista syntezy wsadowej

Aby wyświetlić listę wszystkich zadań syntezy wsadowej dla zasobu usługi Mowa, utwórz żądanie HTTP GET przy użyciu identyfikatora URI, jak pokazano w poniższym przykładzie.

Zastąp YourSpeechKey ciąg kluczem zasobu usługi Mowa i YourSpeechRegion regionem zasobu usługi Mowa. Opcjonalnie możesz ustawić skip parametry zapytania i top (rozmiar strony) w adresie URL. Wartość domyślna parametru skip to 0, a wartość maxpagesize domyślna to 100.

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"

Treść odpowiedzi zostanie wyświetlona w następującym formacie:

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

Z outputs.resultwitryny możesz pobrać plik wideo zawierający wideo z awatarem. Z outputs.summaryprogramu możesz uzyskać dostęp do podsumowania i szczegółów debugowania. Aby uzyskać więcej informacji, zobacz wyniki syntezy wsadowej.

Właściwość value w odpowiedzi JSON zawiera listę żądań syntezy. Lista jest podzielony na strony z maksymalnym rozmiarem strony 100. Właściwość nextLink jest udostępniana zgodnie z potrzebami, aby uzyskać następną stronę listy podzielonej na strony.

Pobieranie pliku wyników syntezy wsadowej

Po uzyskaniu zadania syntezy wsadowej z komunikatem status "Powodzenie" możesz pobrać wyniki wyjściowe wideo. Użyj adresu URL z outputs.result właściwości get batch syntezy odpowiedzi.

Aby uzyskać plik wyników syntezy wsadowej, utwórz żądanie HTTP GET przy użyciu identyfikatora URI, jak pokazano w poniższym przykładzie. Zastąp YourOutputsResultUrl ciąg adresem URL właściwości outputs.result odpowiedzi get batch syntezy . Zastąp YourSpeechKey ciąg kluczem zasobu usługi Mowa.

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

Aby uzyskać plik podsumowania syntezy wsadowej, utwórz żądanie HTTP GET przy użyciu identyfikatora URI, jak pokazano w poniższym przykładzie. Zastąp YourOutputsResultUrl ciąg adresem URL właściwości outputs.summary odpowiedzi get batch syntezy . Zastąp YourSpeechKey ciąg kluczem zasobu usługi Mowa.

curl -v -X GET "YourOutputsSummaryUrl" -H "Ocp-Apim-Subscription-Key: YourSpeechKey" > summary.json

Plik podsumowania zawiera wyniki syntezy dla każdego wejściowego tekstu. Oto przykładowy plik 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"
    }
  ]
}

Usuwanie syntezy wsadowej

Po pobraniu wyników wyjściowych dźwięku i nie potrzebujesz już historii zadania syntezy wsadowej, możesz go usunąć. Usługa rozpoznawania mowy zachowuje każdą historię syntezy przez maksymalnie 31 dni lub czas trwania określony przez właściwość żądania timeToLiveInHours , w zależności od tego, co nastąpi wcześniej. Data i godzina automatycznego usuwania dla zadań syntezy ze stanem "Powodzenie" lub "Niepowodzenie" jest obliczana jako suma lastActionDateTime właściwości i timeToLive .

Aby usunąć zadanie syntezy wsadowej, utwórz żądanie HTTP DELETE przy użyciu następującego formatu identyfikatora URI. Zastąp YourSynthesisId ciąg identyfikatorem YourSpeechKey syntezy wsadowej, kluczem zasobu usługi Mowa i YourSpeechRegion regionem zasobu usługi Mowa.

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

Nagłówki odpowiedzi zawierają HTTP/1.1 204 No Content informację, czy żądanie usunięcia zakończyło się pomyślnie.

Następne kroki