Skip to main content

Peristiwa klien Qwen-Audio-TTS

Referensi peristiwa klien Qwen-Audio-TTS: bidang run-task, continue-task, dan finish-task, urutan pengiriman, serta peristiwa server terkait.

Alur peristiwa

  1. Kirim run-task untuk memulai dan mengonfigurasi tugas, lalu tunggu task-started.
  2. Setelah menerima task-started, kirim teks melalui continue-task sambil menerima result-generated dan audio hasil sintesis.
  3. Setelah semua teks terkirim, kirim finish-task dan terus terima sisa hasil serta audio hingga task-finished diterima. Tugas yang gagal mengembalikan task-failed.
result-generated mengembalikan metadata kalimat. Audio dikirim secara terpisah melalui frame biner WebSocket atau Audio Track AOQ. Untuk koneksi, autentikasi, dan transmisi audio, lihat API WebSocket atau akses AOQ.

run-task

Segera setelah koneksi terbentuk, klien mengirim run-task untuk memulai tugas sintesis ucapan dan mengatur model, suara, laju sampel, serta parameter lainnya.
Tunggu task-started sebelum mengirim continue-task. run-task hanya memulai dan mengonfigurasi tugas. Kirim teks yang akan disintesis melalui continue-task.
headerobjectWajib
actionstringWajib
Jenis perintah. Atur ke run-task.
task_idstringWajib
ID tugas yang dihasilkan klien dalam format UUID. ID ini menghubungkan event-event berikutnya dan harus sesuai dengan task_id pada perintah continue-task dan finish-task.
streamingstringWajib
Atur ke duplex.
payloadobjectWajib
task_groupstringWajib
Kelompok tugas. Atur ke audio.
taskstringWajib
Jenis tugas. Atur ke tts.
functionstringWajib
Jenis fungsi. Atur ke SpeechSynthesizer.
modelstringWajib
Nama model.
parametersobjectWajib
Parameter sintesis suara.
text_typestringWajib
Atur ke PlainText.
voicestringWajib
Voice yang digunakan untuk sintesis suara.
  • System voices: Lihat Daftar voice Qwen-Audio-TTS
  • Cloned voices: Voice kustom yang dibuat melalui voice cloning
  • Custom voices: Voice kustom yang dibuat melalui voice design
formatstringOpsional
Format encoding audio.Nilai yang valid:
  • pcm
  • wav
  • mp3 (default)
  • opus
sample_rateintegerOpsional
Laju sampel audio dalam Hz.Nilai yang valid: 8000, 16000, 22050 (default), 24000, 44100, 48000.
volumeintegerOpsional
Tingkat volume.Nilai default: 50.Nilai yang valid: [0, 100].
ratefloatOpsional
Laju bicara.Nilai default: 1.0.Nilai yang valid: [0.5, 2.0].
pitchfloatOpsional
Pitch.Nilai default: 1.0.Nilai yang valid: [0.5, 2.0].
bit_rateintegerOpsional
Laju bit audio dalam kbps. Saat format audio adalah mp3 atau opus, gunakan bit_rate untuk menyesuaikan laju bit.Nilai default: 32.Nilai yang valid: [6, 510].
enable_ssmlbooleanOpsional
Menentukan apakah SSML diaktifkan.Nilai default: false.
Saat diatur ke true, hanya satu perintah continue-task yang diperbolehkan.
Untuk batasan penggunaan SSML (model, voice, dan API yang didukung), lihat Batasan.
word_timestamp_enabledbooleanOpsional
Menentukan apakah timestamp tingkat kata diaktifkan.Nilai default: false.
Hanya tersedia dalam mode keluaran streaming. Suara hasil kloning didukung. Untuk suara sistem yang didukung, lihat Daftar voice Qwen-Audio-TTS.
seedintegerOpsional
Seed acak untuk mengontrol variasi dalam output sintesis. Saat versi model, teks, voice, dan parameter lainnya tidak berubah, penggunaan seed yang sama menghasilkan output identik.Nilai default: 0.Nilai yang valid: [0, 65535].
language_hintsarray[string]Opsional
Untuk suara multibahasa dan dialek pada qwen-audio-3.1-tts-flash, parameter ini menentukan bahasa atau dialek. Lihat pengaturan suara multibahasa dan dialek untuk detailnya.
Menentukan bahasa target untuk sintesis suara guna meningkatkan kualitas output.Saat pronunciation digit, ekspansi singkatan, pembacaan simbol, atau sintesis bahasa minoritas tidak sesuai harapan, gunakan parameter ini. Contohnya:
  • pronunciation digit yang tidak diharapkan: "hello, this is 110" dibaca sebagai "hello, this is one one zero" alih-alih pronunciation Mandarin yang diharapkan
  • pronunciation simbol tidak akurat: "@" dibaca sebagai ekuivalen Mandarin alih-alih "at"
  • Kualitas sintesis bahasa minoritas buruk dengan hasil tidak alami
  • zh: Tionghoa
  • en: Inggris
  • fr: Prancis
  • de: Jerman
  • ja: Jepang
  • ko: Korea
  • ru: Rusia
  • pt: Portugis
  • th: Thai
  • id: Bahasa Indonesia
  • vi: Vietnam
  • es: Spanyol
  • it: Italia
  • ms: Malaysia
  • fil: Filipino
  • ar: Arab
  • other: Bahasa lain (didukung oleh qwen-audio-3.1-tts-flash) Bulgaria, Belanda, Hungaria, Rumania, Denmark, Kroasia, Yunani, Ceko, Norwegia, Swedia, Hindi, Slovak, Finlandia, Urdu, Serbia, Spanyol (Meksiko), Lituania, Latvia, Turki, Persia, Ibrani, Mongolia, Slovenia, Azerbaijan, Polandia, Katalan, Khmer, Portugis (Brasil), Lao, Georgia, Afrikaans, Nepali, Belarusia, Malayalam, Luksemburg, Albania, Tamil, Sinhala, Telugu, Estonia, Cebuano, Bosnia, Burma, Armenia, Latin, Islandia, Malta, Swahili, Kazakh, Seselwa Kreol Prancis, Ukraina.
  • Parameter ini berupa array, tetapi versi saat ini hanya memproses elemen pertama. Kirim satu nilai saja.
  • Parameter ini menentukan bahasa target untuk sintesis suara. Parameter ini tidak terkait dengan bahasa sampel audio yang digunakan dalam voice cloning. Untuk mengatur bahasa sumber pada tugas cloning, lihat referensi API voice cloning.
instructionstringOpsional
Mengatur instruksi untuk mengontrol dialek, emosi, atau karakter suara selama sintesis. Untuk penggunaan detail, lihat Kontrol instruksi.
enable_aigc_tagbooleanOpsional
Menentukan apakah watermark AIGC disematkan ke dalam audio yang dihasilkan. Saat diatur ke true, watermark disematkan ke file audio dengan format yang didukung (wav/mp3/opus).Nilai default: false.
aigc_propagatorstringOpsional
Mengatur bidang ContentPropagator dalam watermark AIGC, yang mengidentifikasi propagator konten. Hanya berlaku saat enable_aigc_tag bernilai true.Nilai default: UID Alibaba Cloud.
aigc_propagate_idstringOpsional
Mengatur bidang PropagateID dalam watermark AIGC, yang secara unik mengidentifikasi aksi propagasi tertentu. Hanya berlaku saat enable_aigc_tag bernilai true.Nilai default: ID permintaan dari permintaan sintesis suara saat ini.
hot_fixobjectOpsional
Mengonfigurasi koreksi pelafalan dan penggantian teks yang diterapkan sebelum sintesis.Parameter:
  • pronunciation: Pelafalan kustom. Menentukan anotasi pinyin untuk kata-kata guna memperbaiki pelafalan default yang tidak akurat.
  • replace: Penggantian teks. Mengganti kata-kata tertentu dengan teks target sebelum sintesis. Teks yang diganti digunakan sebagai input sintesis sebenarnya.
Contoh ini menggunakan pinyin untuk menentukan pengucapan kata bahasa Tionghoa dan mengganti teks sebelum sintesis.
{
  "hot_fix": {
    "pronunciation": [
      {
        "天气": "tian1 qi4"
      }
    ],
    "replace": [
      {
        "今天": "金天"
      }
    ]
  }
}
enable_markdown_filterbooleanOpsional
Menentukan apakah pemfilteran Markdown diaktifkan. Jika aktif, layanan mengubah Markdown menjadi teks yang sesuai untuk dibacakan sebelum sintesis.Nilai default: false. Tetapkan ke true untuk mengaktifkannya.
inputobjectWajib
Atur ke objek kosong {}. Kirim teks yang akan disintesis melalui perintah continue-task.
Permintaan:
{
  "header": {
    "action": "run-task",
    "task_id": "f604f46b-5329-4520-a767-4ede894e0418",
    "streaming": "duplex"
  },
  "payload": {
    "input": {},
    "task_group": "audio",
    "task": "tts",
    "function": "SpeechSynthesizer",
    "model": "qwen-audio-3.1-tts-flash",
    "parameters": {
      "text_type": "PlainText",
      "voice": "longanhuan_v3.1",
      "format": "mp3",
      "sample_rate": 22050
    }
  }
}
Respons:
{
  "header": {
    "task_id": "f604f46b-5329-4520-a767-4ede894e0418",
    "task_uuid": "573f4010c82040ad90d2a15e7d8afdbd",
    "event": "task-started",
    "attributes": {}
  },
  "payload": {}
}

continue-task

Setelah menerima task-started, klien mengirim continue-task untuk menyerahkan teks yang akan disintesis. Teks dapat dikirim sekaligus atau sebagai segmen secara berurutan.
headerobjectWajib
actionstringWajib
Jenis perintah. Atur ke continue-task.
task_idstringWajib
ID tugas dalam format UUID. Harus sesuai dengan task_id pada run-task.
streamingstringWajib
Atur ke duplex.
payloadobjectWajib
inputobjectWajib
Berisi teks yang akan disintesis.
textstringWajib
Teks yang akan disintesis. Maksimal 20.000 karakter per pesan dan 200.000 karakter secara kumulatif.
Interval pengiriman tidak boleh melebihi 23 detik; jika tidak, koneksi akan timeout.
Permintaan:
{
  "header": {
    "action": "continue-task",
    "task_id": "f604f46b-5329-4520-a767-4ede894e0418",
    "streaming": "duplex"
  },
  "payload": {
    "input": {
      "text": "Welcome to the speech synthesis service."
    }
  }
}
Respons:
{
  "header": {
    "task_id": "f604f46b-5329-4520-a767-4ede894e0418",
    "event": "result-generated",
    "attributes": {
      "x-dashscope-inner-response-type": "ws"
    }
  },
  "payload": {
    "output": {
      "sentence": {
        "index": 0,
        "words": []
      },
      "type": "sentence-begin",
      "original_text": "Welcome to the speech synthesis service.",
      "normalized_text": "Welcome to the speech synthesis service."
    }
  }
}

finish-task

Segera setelah semua teks terkirim, klien mengirim finish-task untuk memberi tahu server bahwa input teks selesai dan meminta penyelesaian tugas. Untuk membatalkan giliran sintesis saat ini, atur directive ke cancel dalam input.
Setelah mengirim finish-task, terus terima sisa hasil sintesis dan audio hingga task-finished diterima. Saat tugas dibatalkan, server menghentikan keluaran audio berikutnya dan mengembalikan task-finished.
headerobjectWajib
actionstringWajib
Jenis perintah. Atur ke finish-task.
task_idstringWajib
ID tugas dalam format UUID. Harus sesuai dengan task_id pada run-task.
streamingstringWajib
Atur ke duplex.
payloadobjectWajib
inputobjectWajib
Atur ke {} untuk penyelesaian tugas normal. Sertakan properti directive untuk membatalkan putaran sintesis saat ini.
directivestringOpsional
Mengontrol cara tugas diakhiri. Saat ini hanya nilai cancel yang didukung. Jika diatur ke cancel, putaran sintesis saat ini akan dibatalkan dan server segera mengembalikan event task-finished tanpa menghasilkan audio tambahan.Setelah pembatalan, Anda dapat memulai tugas sintesis baru pada koneksi WebSocket yang sama dengan mengirim event run-task baru tanpa perlu menyambung ulang.
  • Penyelesaian normal
  • Batalkan tugas
Permintaan:
{
  "header": {
    "action": "finish-task",
    "task_id": "f604f46b-5329-4520-a767-4ede894e0418",
    "streaming": "duplex"
  },
  "payload": {
    "input": {}
  }
}
Respons:
{
  "header": {
    "task_id": "f604f46b-5329-4520-a767-4ede894e0418",
    "event": "task-finished",
    "attributes": {
      "x-dashscope-inner-response-type": "ws"
    }
  },
  "payload": {
    "output": {},
    "usage": {
      "input_tokens": 7,
      "output_tokens": 30,
      "total_tokens": 37,
      "characters": 40
    }
  }
}