Event klien untuk Qwen-Audio Realtime API - Alibaba Cloud Model Studio

Referensi event klien untuk Qwen-Audio Realtime API.

Panduan pengguna: Realtime Audio Chat (Qwen-Audio-Realtime). Untuk urutan interaksi event, lihat WebSocket API.

session.update

Deskripsi: Setelah koneksi terbentuk, kirim event ini untuk memperbarui konfigurasi sesi default. Sertakan hanya bidang yang ingin diubah; bidang yang dihilangkan mempertahankan nilai saat ini. Jika terdapat parameter tidak valid, server mengembalikan error. Jika semua parameter valid, server menerapkan perubahan dan mengembalikan konfigurasi lengkap.

Catatanturn_detection hanya dapat dimodifikasi sebelum audio pertama dikirim (status IDLE).

typestring(required)

Jenis event. Nilai tetap: session.update.

sessionobject (optional)

Konfigurasi sesi.

Properti

modalitiesarray (optional)

Modalitas output untuk model. Nilai yang valid:

["text"]

Hanya teks.
["audio", "text"] (default)

Teks dan audio.

voicestring (optional)

Nama suara TTS. Default: longanqian. Dua jenis didukung. Hanya dapat diatur pada session.update pertama; diabaikan pada pemanggilan berikutnya.

Suara sistem: Nilai yang tersedia: longanqian, longanlingxin, longanlingxi, longanxiaoxin, longanlufeng.
Suara kloning: dibuat melalui Voice Cloning API. Masukkan voice_id yang dikembalikan sebagai nilai parameter ini. Untuk detailnya, lihat Voice configuration.

enable_speech_emotionboolean (optional)

Menentukan apakah peningkatan emosi suara diaktifkan. Saat diaktifkan, suara respons menunjukkan variasi emosi yang lebih jelas. Default: true. Nilai yang valid: true dan false.

instructionsstring (optional)

Instruksi sistem yang menentukan peran model, gaya respons, dan preferensi perilaku. Berlaku untuk seluruh sesi.

input_audio_formatstring (optional)

Format audio input. Saat ini hanya pcm (16 kHz, 16-bit, mono) yang didukung dan merupakan default. Hanya dapat dimodifikasi sebelum audio pertama dikirim (status IDLE).

output_audio_formatstring (optional)

Format audio output. Saat ini hanya pcm (24 kHz, 16-bit, mono) yang didukung dan merupakan default.

max_history_turnsinteger (optional)

Jumlah maksimum giliran percakapan (pasangan pertanyaan-jawaban) yang disertakan dalam satu permintaan. Nilai yang valid: 1 hingga 50. Default: 20.

toolsarray (optional)

Definisi tool untuk Function Calling. Setelah dikonfigurasi, model menentukan apakah akan memanggil tool berdasarkan input pengguna.

Properti

typestring(required)

Nilai tetap: function.

function.namestring(required)

Nama fungsi tool.

function.descriptionstring (optional)

Deskripsi fungsi tool. Model menggunakan ini untuk menentukan apakah akan memanggil tool.

function.parametersobject (optional)

Deskripsi parameter input fungsi tool. Model menggunakan ini untuk mengekstrak parameter yang diperlukan. Abaikan bidang ini jika fungsi tidak memiliki parameter.

Properti

typestring(required)

Nilai tetap: object.

propertiesobject (optional)

Menjelaskan nama, tipe data, dan deskripsi setiap parameter.

requiredarray (optional)

Menentukan parameter mana yang wajib diisi.

turn_detectionobject|null (optional)

Konfigurasi deteksi giliran. Untuk beralih ke mode push-to-talk, atur bidang ini ke null. Dalam mode push-to-talk, audio harus dikomit secara manual dan inferensi dipicu secara manual. Jika bidang ini tidak disediakan, VAD diaktifkan dengan parameter default-nya.

Properti

typestring (optional)

Jenis VAD. Nilai yang valid:

server_vad (default): Mendeteksi awal dan akhir ucapan berdasarkan fitur akustik dan secara otomatis memicu inferensi.
smart_turn: Mode deteksi giliran cerdas yang menggabungkan persepsi akustik dan pemahaman semantik untuk menentukan batas giliran. Suara pengisi seperti "um" atau "uh" tidak memicu giliran baru atau mengganggu pemutaran model.

thresholdfloat (optional)

Sensitivitas VAD. Hanya berlaku dalam mode server_vad (diabaikan dalam mode smart_turn). Nilai yang lebih rendah meningkatkan sensitivitas VAD, sehingga suara pelan (termasuk kebisingan latar) lebih mudah terdeteksi sebagai ucapan. Nilai yang lebih tinggi menurunkan sensitivitas, sehingga diperlukan ucapan yang lebih jelas dan keras untuk memicu deteksi.

Rentang: [-1,0–1,0]. Default: 0,5.

silence_duration_msinteger (optional)

Durasi diam minimum (dalam milidetik) setelah ucapan berakhir sebelum memicu respons model. Hanya berlaku dalam mode server_vad (diabaikan dalam mode smart_turn). Nilai yang lebih rendah menghasilkan respons lebih cepat tetapi dapat menyebabkan pemicuan salah selama jeda singkat.

Rentang: [200, 6000]. Default: 800. Rentang yang direkomendasikan untuk percakapan: 400–800.

voiceprint_audio_urlsarray (optional)

Hanya berlaku dalam mode smart_turn. Daftar URL publik yang mengarah ke sampel audio rekaman dari pengguna target, digunakan untuk peningkatan speaker. Setelah didaftarkan, model mengunci speaker target selama percakapan duplex, secara efektif mengabaikan suara lain dan kebisingan latar. Maksimal 5 URL. Persyaratan format audio: PCM atau WAV 16 kHz.

PentingParameter ini hanya dapat dikonfigurasi pada event pertama session.update. Parameter ini diabaikan pada event session.update berikutnya.

{
    "type": "session.update",
    "session": {
        "modalities": [
            "text",
            "audio"
        ],
        "voice": "longanqian",
        "turn_detection": {
            "type": "server_vad",
            "threshold": 0.5,
            "silence_duration_ms": 800
        }
    }
}

Function Calling:

{
    "type": "session.update",
    "session": {
        "modalities": [
            "text",
            "audio"
        ],
        "voice": "longanqian",
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "get_weather",
                    "description": "Get weather for a specified city",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "city": {
                                "type": "string",
                                "title": "City"
                            }
                        },
                        "required": ["city"]
                    }
                }
            }
        ],
        "turn_detection": {
            "type": "server_vad",
            "threshold": 0.5,
            "silence_duration_ms": 800
        }
    }
}

Voiceprint registration (voiceprint_audio_urls):

{
    "type": "session.update",
    "session": {
        "turn_detection": {
            "type": "smart_turn",
            "voiceprint_audio_urls": [
                "https://example.com/speaker1.pcm",
                "https://example.com/speaker2.wav"
            ]
        }
    }
}

input_audio_buffer.append

Deskripsi: Menambahkan data audio ke buffer input. Kirim event ini terus-menerus dengan frekuensi tinggi — misalnya, satu chunk setiap 20–40 ms. Server tidak mengirim acknowledgment untuk event ini.

typestring(required)

Jenis event. Nilai tetap: input_audio_buffer.append.

audiostring(required)

Data audio yang dienkode Base64.

{
    "type": "input_audio_buffer.append",
    "audio": "<Base64-encoded audio data>"
}

input_audio_buffer.commit

Deskripsi: Hanya untuk mode push-to-talk. Mengomit buffer audio sebagai pesan pengguna. Ini tidak secara otomatis memicu inferensi. Kirim response.create untuk memicu inferensi secara manual.

Event ini diabaikan dalam mode server_vad dan smart_turn.

typestring(required)

Jenis event. Nilai tetap: input_audio_buffer.commit.

{
    "type": "input_audio_buffer.commit"
}

input_audio_buffer.clear

Deskripsi: Hanya untuk mode push-to-talk. Menghapus audio yang belum dikomit dari buffer. Event ini diabaikan dalam mode server_vad dan smart_turn. Server merespons dengan event input_audio_buffer.cleared.

typestring(required)

Jenis event. Nilai tetap: input_audio_buffer.clear.

{
    "type": "input_audio_buffer.clear"
}

conversation.item.create

Deskripsi: Menyisipkan item percakapan ke dalam konteks percakapan. Gunakan event ini untuk menyuntikkan konteks historis atau menambahkan konten teks, atau untuk mengembalikan hasil Function Calling.

CatatanJika item.id sudah ada dalam percakapan, error dikembalikan dan item tidak dibuat.

typestring(required)

Jenis event. Nilai tetap: conversation.item.create.

previous_item_idstring (optional)

Menentukan item percakapan tempat item baru akan disisipkan setelahnya. Jika tidak ditentukan, item baru akan ditambahkan di akhir percakapan.

itemobject(required)

Item percakapan yang akan dibuat.

Properti

idstring (optional)

Identifier unik untuk item percakapan. Jika tidak disediakan, server menghasilkannya secara otomatis. Error dikembalikan jika ID yang ditentukan sudah ada dalam percakapan.

typestring(required)

Jenis item percakapan. Nilai yang valid:

message: Pesan percakapan biasa.
function_call: Permintaan pemanggilan fungsi. Biasanya dihasilkan oleh server, tetapi klien juga dapat menggunakannya untuk menyuntikkan konteks historis.
function_call_output: Hasil eksekusi tool. Setelah menerima function_call, klien mengeksekusi tool dan mengembalikan hasilnya menggunakan jenis ini.

rolestring (required untuk jenis message)

Peran pesan. Nilai yang valid: system, user, assistant.

contentarray (required untuk jenis message)

Daftar elemen konten pesan. Setiap elemen berisi bidang type dan bidang data terkait.

Jenis konten yang didukung berdasarkan peran

system

input_text: Pesan sistem. Bidang wajib: text.

user

input_text: Input teks pengguna. Bidang wajib: text.
input_audio: Input audio pengguna. Bidang wajib: audio (dienkode Base64).

assistant

output_text: Output teks asisten. Bidang wajib: text.

call_idstring (required untuk jenis function_call / function_call_output)

Identifier unik untuk pemanggilan fungsi, digunakan untuk menghubungkan permintaan dan hasil.

namestring (required untuk jenis function_call)

Nama fungsi yang akan dipanggil.

argumentsstring (required untuk jenis function_call)

Parameter pemanggilan fungsi dalam format string JSON.

outputstring (required untuk jenis function_call_output)

Hasil eksekusi tool dalam format string JSON.

Menyuntikkan pesan teks pengguna:

{
    "type": "conversation.item.create",
    "previous_item_id": "item_xxx",
    "item": {
        "id": "my_item_001",
        "type": "message",
        "role": "user",
        "content": [
            {
                "type": "input_text",
                "text": "Please summarize our last conversation"
            }
        ]
    }
}

Mengembalikan hasil Function Calling:

{
    "type": "conversation.item.create",
    "item": {
        "type": "function_call_output",
        "call_id": "call_xxx",
        "output": "{\"temperature\":18,\"condition\":\"sunny\"}"
    }
}

conversation.item.retrieve

Deskripsi: Mengambil item percakapan yang disimpan di server. Konten bertipe audio dalam respons hanya berisi transkrip (transcript), bukan data audio aslinya.

typestring(required)

Jenis event. Nilai tetap: conversation.item.retrieve.

item_idstring(required)

ID item percakapan yang akan diambil. Server mengembalikan hasilnya dalam event conversation.item.retrieved.

{
    "type": "conversation.item.retrieve",
    "item_id": "item_xxx"
}

conversation.item.delete

Deskripsi: Menghapus item percakapan dari konteks percakapan. Server mengonfirmasi penghapusan dengan event conversation.item.deleted.

typestring(required)

Jenis event. Nilai tetap: conversation.item.delete.

item_idstring(required)

ID item percakapan yang akan dihapus.

{
    "type": "conversation.item.delete",
    "item_id": "item_xxx"
}

response.create

Deskripsi: Memicu inferensi model. Perilaku bervariasi berdasarkan mode:

Mode push-to-talk: Harus dipanggil secara manual. Komit buffer audio terlebih dahulu dengan input_audio_buffer.commit, atau kembalikan hasil function_call_output sebelum memicu. Tidak dapat dipanggil saat respons sedang dihasilkan.
Mode server_vad: Biasanya dipicu secara otomatis oleh server. Klien juga dapat memanggilnya secara manual saat tidak ada respons yang sedang dihasilkan. Tidak dapat dipanggil saat respons sedang dihasilkan.
Mode smart_turn: Dapat dipanggil saat menunggu giliran pengguna berikutnya. Tidak dapat dipanggil selama giliran aktif (antara input_audio_buffer.speech_started dan response.done).

Bidang opsional response mengganti default sesi untuk putaran inferensi saat ini. Dalam skenario Function Calling, setelah klien mengembalikan function_call_output, event ini memicu putaran inferensi kedua.

CatatanDalam mode server_vad dan smart_turn, inferensi yang dipicu secara manual masih dapat diinterupsi oleh ucapan baru.

typestring(required)

Jenis event. Nilai tetap: response.create.

responseobject (optional)

Mengganti default sesi untuk putaran inferensi saat ini. Jika tidak disediakan, konfigurasi sesi saat ini digunakan.

Properti

modalitiesarray (optional)

Mengganti modalitas output untuk putaran ini. Nilai yang valid sama dengan modalities pada session.update.

voicestring (optional)

Mengganti suara TTS untuk putaran ini.

{
    "type": "response.create",
    "response": {
        "modalities": ["audio", "text"]
    }
}

response.cancel

Deskripsi: Membatalkan inferensi yang sedang berlangsung. Teks yang telah dihasilkan disimpan ke daftar item. Server kemudian mengembalikan event response.done dengan status=cancelled.

Error dikembalikan jika tidak ada inferensi yang sedang berlangsung.

typestring(required)

Jenis event. Nilai tetap: response.cancel.

{
    "type": "response.cancel"
}