Bagikan melalui

Cara menggunakan sintesis batch untuk avatar teks ke ucapan (pratinjau)

  • Artikel

Catatan

Avatar teks ke ucapan saat ini dalam pratinjau publik. Pratinjau ini disediakan tanpa perjanjian tingkat layanan, dan tidak disarankan untuk beban kerja produksi. Fitur tertentu mungkin tidak didukung atau mungkin memiliki kemampuan terbatas. Untuk mengetahui informasi selengkapnya, lihat Ketentuan Penggunaan Tambahan untuk Pratinjau Microsoft Azure.

API sintesis batch untuk avatar teks ke ucapan (pratinjau) memungkinkan sintesis teks asinkron menjadi avatar yang berbicara sebagai file video. Penerbit dan platform konten video dapat menggunakan API ini untuk membuat konten video avatar dalam batch. Pendekatan tersebut dapat cocok untuk berbagai kasus penggunaan seperti materi pelatihan, presentasi, atau iklan.

Video avatar sintetis akan dihasilkan secara asinkron setelah sistem menerima input teks. Output video yang dihasilkan dapat diunduh dalam sintesis mode batch. Anda mengirimkan teks untuk sintesis, polling untuk status sintesis, dan mengunduh output video saat status menunjukkan keberhasilan. Format input teks harus teks biasa atau teks Speech Synthesis Markup Language (SSML).

Diagram ini menyediakan ringkasan tingkat tinggi alur kerja.

Cuplikan layar menampilkan gambaran umum tingkat tinggi dari alur kerja sintesis batch.

Untuk melakukan sintesis batch, Anda dapat menggunakan operasi REST API berikut.

Operasi Metode Panggilan REST API
Membuat sintesis batch TARUH avatar/batchsyntheses/{SynthesisId}?api-version=2024-04-15-preview
Dapatkan sintesis batch GET avatar/batchsyntheses/{SynthesisId}?api-version=2024-04-15-preview
Mencantumkan sintesis batch GET avatar/batchsyntheses/?api-version=2024-04-15-preview
Menghapus sintesis batch DELETE avatar/batchsyntheses/{SynthesisId}?api-version=2024-04-15-preview

Anda dapat merujuk ke sampel kode di GitHub.

Membuat permintaan sintesis batch

Beberapa properti dalam format JSON diperlukan saat Anda membuat pekerjaan sintesis batch baru. Properti lain bersifat opsional. Respons sintesis batch mencakup properti lain untuk memberikan informasi tentang status dan hasil sintesis. Misalnya, outputs.result properti berisi lokasi tempat Anda dapat mengunduh file video yang berisi video avatar. Dari outputs.summary, Anda dapat mengakses ringkasan dan detail debug.

Untuk mengirimkan permintaan sintesis batch, buat isi permintaan HTTP POST dengan mengikuti instruksi berikut:

  • Atur properti inputKind yang diperlukan.
  • inputKind Jika properti diatur ke PlainText, Anda juga harus mengatur voice properti di synthesisConfig. Dalam contoh di bawah ini, inputKind diatur ke SSML, sehingga speechSynthesis tidak diatur.
  • Atur properti SynthesisId yang diperlukan. Pilih yang unik SynthesisId untuk sumber daya ucapan yang sama. SynthesisId dapat berupa string 3 hingga 64 karakter, termasuk huruf, angka, '-', atau '_', dengan kondisi harus dimulai dan diakhir dengan huruf atau angka.
  • Atur properti dan talkingAvatarStyle yang diperlukantalkingAvatarCharacter. Anda dapat menemukan karakter dan gaya avatar yang didukung di sini.
  • Secara opsional, Anda dapat mengatur videoFormatproperti , backgroundColor, dan lainnya. Untuk informasi selengkapnya, lihat properti sintesis batch.

Catatan

Ukuran payload JSON maksimum yang diterima adalah 500 kilobyte.

Setiap sumber daya Ucapan dapat memiliki hingga 200 pekerjaan sintesis batch yang berjalan bersamaan.

Panjang maksimum untuk video output saat ini adalah 20 menit, dengan potensi peningkatan di masa depan.

Untuk membuat permintaan HTTP PUT, gunakan format URI yang diperlihatkan dalam contoh berikut. Ganti YourSpeechKey dengan kunci sumber daya Ucapan Anda, YourSpeechRegion dengan wilayah sumber daya Ucapan Anda, dan atur properti isi permintaan seperti yang dijelaskan di atas.

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-04-15-preview"

Anda akan menerima isi respons dalam format berikut:

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

Properti status harus maju dari NotStarted status ke Running dan akhirnya ke Succeeded atau Failed. Anda dapat secara berkala memanggil GET batch synthesis API hingga status yang dikembalikan adalah Succeeded atau Failed.

Dapatkan sintesis batch

Untuk mengambil status pekerjaan sintesis batch, buat permintaan HTTP GET menggunakan URI seperti yang ditunjukkan dalam contoh berikut.

Ganti YourSynthesisId dengan ID sintesis batch Anda, YourSpeechKey dengan kunci sumber daya Ucapan Anda, dan YourSpeechRegion dengan wilayah sumber daya Ucapan Anda.

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

Anda akan menerima isi respons dalam format berikut:

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

Dari outputs.result bidang , Anda dapat mengunduh file video yang berisi video avatar. Bidang ini outputs.summary memungkinkan Anda mengunduh ringkasan dan detail debug. Untuk informasi selengkapnya tentang hasil sintesis batch, lihat hasil sintesis batch.

Mencantumkan sintesis batch

Untuk mencantumkan semua pekerjaan sintesis batch untuk sumber daya Ucapan Anda, buat permintaan HTTP GET menggunakan URI seperti yang ditunjukkan dalam contoh berikut.

Ganti YourSpeechKey dengan kunci sumber daya Ucapan Anda dan YourSpeechRegion dengan wilayah sumber daya Ucapan Anda. Secara opsional, Anda dapat mengatur skip parameter kueri dan top (ukuran halaman) di URL. Nilai default untuk skip adalah 0, dan nilai default untuk maxpagesize adalah 100.

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

Anda menerima isi respons dalam format berikut:

{
    "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-04-15-preview&skip=2&maxpagesize=2"
}

Dari outputs.result, Anda dapat mengunduh file video yang berisi video avatar. Dari outputs.summary, Anda dapat mengakses ringkasan dan detail debug. Untuk informasi selengkapnya, lihat hasil sintesis batch.

Properti value dalam respons JSON mencantumkan permintaan sintesis Anda. Daftar ini diberi nomor halaman, dengan ukuran halaman maksimum 100. Properti nextLink disediakan sesuai kebutuhan untuk mendapatkan halaman berikutnya dari daftar paginated.

Mendapatkan file hasil sintesis batch

Setelah Anda mendapatkan pekerjaan sintesis batch dengan status "Berhasil", Anda dapat mengunduh hasil output video. Gunakan URL dari outputs.result properti dapatkan respons sintesis batch.

Untuk mendapatkan file hasil sintesis batch, buat permintaan HTTP GET menggunakan URI seperti yang ditunjukkan dalam contoh berikut. Ganti YourOutputsResultUrl dengan URL dari outputs.result properti dapatkan respons sintesis batch. Ganti YourSpeechKey dengan kunci sumber daya Ucapan Anda.

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

Untuk mendapatkan file ringkasan sintesis batch, buat permintaan HTTP GET menggunakan URI seperti yang ditunjukkan dalam contoh berikut. Ganti YourOutputsResultUrl dengan URL dari outputs.summary properti dapatkan respons sintesis batch. Ganti YourSpeechKey dengan kunci sumber daya Ucapan Anda.

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

File ringkasan berisi hasil sintesis untuk setiap input teks. Berikut adalah contoh file 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"
    }
  ]
}

Menghapus sintesis batch

Setelah Anda mengambil hasil output audio dan tidak lagi memerlukan riwayat pekerjaan sintesis batch, Anda dapat menghapusnya. Layanan Ucapan mempertahankan setiap riwayat sintesis hingga 31 hari atau durasi yang ditentukan oleh properti permintaan timeToLiveInHours , mana yang datang lebih cepat. Tanggal dan waktu penghapusan otomatis, untuk pekerjaan sintesis dengan status "Berhasil" atau "Gagal" dihitung sebagai jumlah lastActionDateTime properti dan timeToLive .

Untuk menghapus pekerjaan sintesis batch, buat permintaan HTTP DELETE menggunakan format URI berikut. Ganti YourSynthesisId dengan ID sintesis batch Anda, YourSpeechKey dengan kunci sumber daya Ucapan Anda, dan YourSpeechRegion dengan wilayah sumber daya Ucapan Anda.

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

Header respons menyertakan HTTP/1.1 204 No Content jika permintaan penghapusan berhasil.

Langkah berikutnya