API sintesis batch untuk teks ke ucapan

  • Artikel

API sintesis Batch dapat mensintesis volume besar input teks (panjang dan pendek) secara asinkron. Penerbit dan platform konten audio dapat membuat konten audio panjang dalam batch. Misalnya: buku audio, artikel berita, dan dokumen. API sintesis batch dapat membuat audio yang disintesis lebih dari 10 menit.

Penting

API sintesis Batch umumnya tersedia. API Long Audio akan dihentikan pada 1 April 2027. Untuk informasi selengkapnya, lihat Migrasi ke API sintesis batch.

API sintesis batch bersifat asinkron dan tidak mengembalikan audio yang disintesis secara real time. Anda akan mengirimkan file yang akan disintesis, polling status, dan mengunduh output audio saat status menunjukkan keberhasilan. Input teks harus teks biasa atau teks Speech Synthesis Markup Language (SSML).

Diagram ini menyediakan ringkasan tingkat tinggi alur kerja.

Diagram alur kerja API Sintesis Batch.

Tip

Anda juga dapat menggunakan Speech SDK untuk membuat audio yang disintesis lebih dari 10 menit dengan mengurutkan teks dan mensintesisnya dalam gugus. Untuk contoh C#, lihat GitHub.

Anda dapat menggunakan operasi REST API berikut untuk sintesis batch:

Operasi Metode Panggilan REST API
Membuat sintesis batch PUT texttospeech/batchsyntheses/YourSynthesisId
Dapatkan sintesis batch GET texttospeech/batchsyntheses/YourSynthesisId
Mencantumkan sintesis batch GET texttospeech/batchsyntheses
Menghapus sintesis batch DELETE texttospeech/batchsyntheses/YourSynthesisId

Untuk sampel kode, lihat GitHub.

Membuat sintesis batch

Untuk mengirimkan permintaan sintesis batch, buat jalur dan isi permintaan HTTP PUT sesuai dengan instruksi berikut:

  • Atur properti inputKind yang diperlukan.
  • inputKind Jika properti diatur ke "PlainText", maka Anda juga harus mengatur voice properti di synthesisConfig. Dalam contoh di bawah ini, inputKind diatur ke "SSML", sehingga synthesisConfig tidak diatur.
  • Secara opsional Anda dapat mengatur descriptionproperti , timeToLiveInHours, dan lainnya. Untuk informasi selengkapnya, lihat properti sintesis batch.

Catatan

Ukuran payload JSON maksimum yang akan diterima adalah 2 megabyte.

Atur jalur yang diperlukan YourSynthesisId . Harus YourSynthesisId unik. Panjangnya harus 3-64, hanya berisi angka, huruf, tanda hubung, garis bawah dan titik, dimulai dan diakhir dengan huruf atau angka.

Buat permintaan HTTP PUT menggunakan URI seperti yang ditunjukkan dalam contoh berikut. Ganti YourSpeechKey dengan kunci sumber daya Ucapan Anda, ganti YourSpeechRegion dengan wilayah sumber daya Ucapan Anda, dan atur properti isi permintaan seperti yang dijelaskan sebelumnya.

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"

Anda akan menerima isi respons dalam format berikut:

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

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

Dapatkan sintesis batch

Untuk mendapatkan status pekerjaan sintesis batch, buat permintaan HTTP GET menggunakan URI seperti yang ditunjukkan dalam contoh berikut. Ganti YourSpeechKey dengan kunci sumber daya Azure Cognitive Service untuk Ucapan Anda, dan ganti YourSpeechRegion dengan wilayah sumber daya Azure Cognitive Service untuk Ucapan Anda.

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

Anda akan menerima isi respons dalam format berikut:

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

Dari outputs.result, Anda dapat mengunduh file ZIP yang berisi audio (seperti 0001.wav), ringkasan, dan detail debug. Untuk informasi selengkapnya, lihat hasil sintesis batch.

Mencantumkan sintesis batch

Untuk mencantumkan semua pekerjaan sintesis batch untuk sumber daya Ucapan, buat permintaan HTTP GET menggunakan URI seperti yang ditunjukkan dalam contoh berikut. Ganti YourSpeechKey dengan kunci sumber daya Ucapan Anda dan ganti YourSpeechRegion dengan wilayah sumber daya Ucapan Anda. Secara opsional, Anda dapat mengatur skip parameter kueri dan maxpagesize (hingga 100) 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/texttospeech/batchsyntheses?api-version=2024-04-01&skip=1&maxpagesize=2" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

Anda akan menerima isi respons dalam format berikut:

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

Dari outputs.result, Anda dapat mengunduh file ZIP yang berisi audio (seperti 0001.wav), 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.

Menghapus sintesis batch

Hapus riwayat pekerjaan sintesis batch setelah Anda mengambil hasil output audio. Layanan Ucapan menyimpan riwayat sintesis batch hingga 31 hari, atau durasi properti permintaan timeToLiveInHours , mana yang datang lebih cepat. Tanggal dan waktu penghapusan otomatis (untuk pekerjaan sintesis dengan status "Berhasil" atau "Gagal") sama dengan lastActionDateTime + timeToLiveInHours properti.

Untuk menghapus pekerjaan sintesis batch, buat permintaan HTTP DELETE menggunakan URI seperti yang ditunjukkan dalam contoh berikut. Ganti YourSynthesisId dengan ID sintesis batch Anda, ganti YourSpeechKey dengan kunci sumber daya Ucapan Anda, dan ganti YourSpeechRegion dengan wilayah sumber daya Ucapan Anda.

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

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

Hasil sintesis batch

Setelah Anda mendapatkan pekerjaan sintesis batch dengan status "Berhasil", Anda dapat mengunduh hasil output audio. 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" > results.zip

Hasilnya ada dalam file ZIP yang berisi audio (seperti 0001.wav), ringkasan, dan detail debug. Awalan bernomor dari setiap nama file (ditunjukkan di bawah ini sebagai [nnnn]) berada dalam urutan yang sama dengan input teks yang digunakan saat Anda membuat sintesis batch.

Catatan

File [nnnn].debug.json berisi ID hasil sintesis dan informasi lain yang mungkin membantu pemecahan masalah. Properti yang dikandungnya mungkin berubah, jadi Anda tidak boleh mengambil dependensi apa pun pada format JSON.

File ringkasan berisi hasil sintesis untuk setiap input teks. Berikut adalah contoh summary.json file:

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

Jika data batas kalimat diminta ("sentenceBoundaryEnabled": true), maka file yang sesuai [nnnn].sentence.json disertakan dalam hasilnya. Demikian juga, jika data batas kata diminta ("wordBoundaryEnabled": true), maka file yang sesuai [nnnn].word.json disertakan dalam hasilnya.

Berikut adalah contoh file data kata dengan offset audio dan durasi dalam milidetik:

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

Latensi sintesis batch dan praktik terbaik

Saat menggunakan sintesis batch untuk menghasilkan ucapan yang disintesis, penting untuk mempertimbangkan latensi yang terlibat dan mengikuti praktik terbaik untuk mencapai hasil yang optimal.

Latensi dalam sintesis batch

Latensi dalam sintesis batch tergantung pada berbagai faktor, termasuk kompleksitas teks input, jumlah input dalam batch, dan kemampuan pemrosesan perangkat keras yang mendasar.

Latensi untuk sintesis batch adalah sebagai berikut (kira-kira):

  • Latensi 50% dari output ucapan yang disintesis dalam waktu 10-20 detik.

  • Latensi 95% dari output ucapan yang disintesis dalam waktu 120 detik.

Praktik terbaik

Saat mempertimbangkan sintesis batch untuk aplikasi Anda, disarankan untuk menilai apakah latensi memenuhi kebutuhan Anda. Jika latensi selaras dengan performa yang Anda inginkan, sintesis batch dapat menjadi pilihan yang sesuai. Namun, jika latensi tidak memenuhi kebutuhan Anda, Anda mungkin mempertimbangkan untuk menggunakan API real time.

Kode status HTTP

Bagian ini merinci kode respons HTTP dan pesan dari API sintesis batch.

HTTP 200 OK

HTTP 200 OK menunjukkan bahwa permintaan berhasil.

HTTP 201 Dibuat

HTTP 201 Created menunjukkan bahwa permintaan sintesis buat batch (melalui HTTP PUT) berhasil.

Kesalahan HTTP 204

Kesalahan HTTP 204 menunjukkan bahwa permintaan berhasil, tetapi sumber daya tidak ada. Contohnya:

  • Anda mencoba mendapatkan atau menghapus pekerjaan sintesis yang tidak ada.
  • Anda berhasil menghapus pekerjaan sintesis.

Kesalahan HTTP 400

Berikut adalah contoh yang dapat mengakibatkan kesalahan 400:

  • outputFormat tidak didukung atau tidak valid. Berikan nilai format yang valid, atau biarkan outputFormat kosong untuk menggunakan pengaturan default.
  • Jumlah input teks yang diminta melebihi batas 10.000.
  • Anda mencoba menggunakan ID penyebaran yang tidak valid atau suara kustom yang tidak berhasil disebarkan. Pastikan sumber daya Ucapan memiliki akses ke suara kustom, dan suara kustom berhasil disebarkan. Anda juga harus memastikan bahwa pemetaan {"your-custom-voice-name": "your-deployment-ID"} sudah benar dalam permintaan sintesis batch Anda.
  • Anda mencoba menggunakan sumber daya Ucapan F0 , tetapi wilayah hanya mendukung tingkat harga sumber daya Ucapan Standar .
  • Anda mencoba membuat pekerjaan sintesis batch baru yang akan melebihi batas 300 pekerjaan aktif. Setiap sumber daya Ucapan dapat memiliki hingga 300 pekerjaan sintesis batch yang tidak memiliki status "Berhasil" atau "Gagal".

Kesalahan HTTP 404

Entitas yang ditentukan tidak dapat ditemukan. Pastikan ID sintesis sudah benar.

Kesalahan HTTP 429

Ada terlalu banyak permintaan terbaru. Setiap aplikasi klien dapat mengirimkan hingga 100 permintaan per 10 detik untuk setiap sumber daya Ucapan. Kurangi jumlah permintaan per detik.

Kesalahan HTTP 500

Kesalahan Server Internal HTTP 500 menunjukkan bahwa permintaan gagal. Isi respons berisi pesan kesalahan.

Contoh kesalahan HTTP

Berikut adalah contoh permintaan yang menghasilkan kesalahan HTTP 400, karena inputs properti diperlukan untuk membuat pekerjaan.

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"

Dalam hal ini, header respons menyertakan HTTP/1.1 400 Bad Request.

Isi respons menyerupai contoh JSON berikut:

{
  "error": {
    "code": "BadRequest",
    "message": "The inputs is required."
  }
}

Langkah berikutnya