SDK Android pengenalan ucapan non-real-time (Qwen-Audio-3.x-ASR-Flash/Fun-ASR-Flash)

Panduan pengguna: Pengenalan ucapan non-real-time. Untuk format audio yang didukung, batas ukuran file, batas durasi, dan persyaratan input lainnya, lihat Spesifikasi audio.

Panduan cepat

Dapatkan API key: Get an API key. Untuk keamanan, kami menyarankan Anda mengonfigurasi API key di variabel lingkungan.
Unduh SDK dan jalankan kode contoh:
- Unduh bundel SDK terbaru.
- Ekstrak arsip ZIP. Dapatkan SDK dalam format AAR dari app/libs dan tambahkan ke dependensi proyek Anda. Untuk integrasi CPP Android, gunakan android_libs dan android_include di arsip ZIP untuk mendapatkan pustaka dinamis dan file header.
- Buka proyek di Android Studio. Kode contoh ada di DashFunAsrFlashFileTranscriberActivity.java. Ganti API key untuk mencoba fitur ini.

Prosedur pemanggilan

Mode sinkron

Inisialisasi SDK
Konfigurasikan parameter berdasarkan kebutuhan bisnis Anda
Panggil startFileTranscriber untuk mengirim permintaan pengenalan ucapan non-real-time dan tunggu hasilnya.
Gunakan onFileTransEventCallback untuk mendengarkan event EVENT_FILE_TRANS_RESULT dan memperoleh hasil pengenalan akhir.
Panggil release untuk melepaskan resource SDK

Parameter permintaan

Parameter koneksi dan kontrol

Berikan string JSON ke parameter parameters metode initialize untuk mengonfigurasi pengaturan ini. Contoh parameter: String JSON berikut adalah contoh dan tidak mencantumkan semua parameter. Tambahkan parameter sesuai kebutuhan di kode Anda:

{
    "url": "wss://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}

Parameter

Parameter	Tipe	Wajib	Deskripsi
`url`	`String`	Ya	Endpoint layanan: `wss://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation` Tiongkok (Beijing): `wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com`/api/v1/services/aigc/multimodal-generation/generation Singapura: `wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation` Ganti `{WorkspaceId}` dengan ID Workspace.
`apikey`	`String`	Ya	API Key.
`service_mode`	`String`	Ya	Mode operasi. Untuk pengenalan ucapan non-real-time, atur parameter ini ke `"1"`.
`device_id`	`String`	Ya	String unik yang mengidentifikasi pengguna akhir. Anda dapat menggunakan ID pengguna dalam aplikasi atau pengidentifikasi perangkat unik yang dibuat klien. ID ini terutama digunakan untuk pelacakan log dan pemecahan masalah.
`debug_path`	`String`	Tidak	Jalur untuk file log. Parameter ini hanya berlaku jika Anda memanggil initialize dengan `save_log` diatur ke true. Dalam kasus ini, Anda harus menentukan jalur file log. Jika tidak, akan terjadi error. Hingga dua file log dipertahankan secara lokal.
`max_log_file_size`	`int`	Tidak	Ukuran file log maksimum dalam byte. Parameter ini hanya berlaku ketika Anda memanggil initialize dengan `save_log` diatur ke true. Default: 104857600 (100 * 1024 * 1024 byte, atau 100 MiB).
`log_track_level`	`int`	Tidak	Tingkat pemfilteran untuk log yang dikirim melalui callback logging (`onFileTransLogTrackCallback`). Default: 2. Nilai yang valid: - 0: LOG_LEVEL_VERBOSE - 1: LOG_LEVEL_DEBUG - 2: LOG_LEVEL_INFO - 3: LOG_LEVEL_WARNING - 4: LOG_LEVEL_ERROR - 5: LOG_LEVEL_NONE (menonaktifkan fitur ini). Catatan: `log_track_level` dan `level` (dikonfigurasi melalui metode initialize) bersama-sama menentukan log mana yang dikirimkan. Tingkat numerik log harus lebih besar dari atau sama dengan `log_track_level` dan `level` agar log dapat dikirimkan. Misalnya, jika `log_track_level` diatur ke 2 (INFO) dan `level` diatur ke 3 (WARNING), hanya log WARNING dan tingkat keparahan yang lebih tinggi (tingkat numerik >= 3) yang dikirimkan.

Parameter pengenalan

Gunakan startFileTranscriber untuk mengonfigurasi semua parameter pengenalan. Contoh parameter: String JSON berikut adalah contoh dan tidak mencantumkan semua parameter. Tambahkan parameter sesuai kebutuhan di kode Anda:

{
  "apikey": "st-****",
  "messages": [
    {
      "content": [
        {
          "input_audio": {
            "data": "{YOUR_AUDIO_URL}"
          },
          "type": "input_audio"
        }
      ],
      "role": "user"
    }
  ],
  "nls_config": {
    "format": "mp3",
    "model": "qwen-audio-3.0-asr-flash"
  }
}

Parameter

Parameter	Tipe	Wajib	Deskripsi
`apikey`	`string`	Tidak	Jika Connection and control parameters `apikey` menggunakan temporary API key, Anda dapat memperbaruinya di sini untuk mencegah kedaluwarsa.
`nls_config`	`object`	Ya	Objek konfigurasi pengenalan ucapan inti, termasuk model dan parameter yang mengontrol pengenalan.
`nls_config.model`	`string`	Ya	Model yang digunakan dalam contoh. Untuk informasi model, lihat Model dan wilayah yang didukung.
`nls_config.format`	`string`	Ya	Format audio. Atur parameter ini ke format aktual. Format yang didukung meliputi `wav`, `mp3`, `opus`. Untuk detailnya, lihat Audio specifications.
`nls_config.sample_rate`	`string`	Tidak	Tingkat sampel audio dalam Hz. Misalnya, `16000` menunjukkan tingkat sampel 16 kHz. Untuk detailnya, lihat Audio specifications.
`nls_config.vocabulary_id`	`string`	Tidak	ID kosakata yang telah dikompilasi sebelumnya. Buat kosakata terlebih dahulu dan berikan ID-nya selama pengenalan untuk menggunakan kata kuncinya. Gunakan opsi ini jika kosakata sudah diketahui, relatif stabil, dan digunakan kembali di berbagai permintaan. Untuk petunjuk penggunaan, lihat Kata kunci yang telah dikompilasi sebelumnya.
`nls_config.instant_vocabulary`	`object`	Tidak	Kata kunci instan. Berikan pasangan kunci-nilai. Kuncinya adalah teks kata kunci (`string`) dan nilainya adalah bobotnya (`integer`). Anda tidak perlu membuat kosakata terlebih dahulu. Bobot yang valid adalah [1, 5] atau 50. Dalam rentang [1, 5], bobot yang lebih tinggi membuat model lebih mungkin menghasilkan kata tersebut. Bobot 50 menentukan kata kunci super dan secara signifikan meningkatkan recall. Anda dapat menentukan hingga 50 kata kunci super. Gunakan opsi ini untuk optimasi kata kunci sementara tingkat sesi. Jika kata kunci instan dan yang telah dikompilasi sebelumnya dikonfigurasi, sistem akan menggabungkannya. Jika daftar gabungan melebihi 2000 entri, sistem akan memilih 2000 entri secara acak. Untuk petunjuk penggunaan, lihat Kata kunci instan. Untuk model dan batas yang berlaku untuk hotword instan, lihat Hotword instan. `{ "张三": 5, "李四": 5 }`
`nls_config.language_hints`	`array[string]`	Tidak	Kode bahasa untuk pengenalan. Jika bahasa tidak diketahui sebelumnya, abaikan parameter ini agar model mendeteksinya secara otomatis. Untuk model Qwen-Audio-3.0-ASR-Flash, didukung hingga empat nilai. Jika lebih dari itu yang ditentukan, hanya empat pertama yang berlaku. Untuk model Fun-ASR-Flash, hanya satu nilai yang didukung. Jika beberapa nilai ditentukan, hanya nilai pertama yang berlaku. Qwen-Audio-3.x-ASR-Flash, fun-asr-flash-2026-06-15: zh: Tiongkok en: Inggris ja: Jepang ko: Korea vi: Vietnam th: Thai id: Indonesia ms: Melayu tl: Filipino hi: Hindi ar: Arab fr: Prancis de: Jerman es: Spanyol pt: Portugis ru: Rusia it: Italia nl: Belanda sv: Swedia da: Denmark fi: Finlandia no: Norwegia el: Yunani pl: Polandia cs: Ceko hu: Hungaria ro: Rumania bg: Bulgaria hr: Kroasia sk: Slovakia
messages	`array[object]`	Ya	Daftar pesan. Berisi audio yang akan dikenali dan konteks percakapan opsional untuk meningkatkan pengenalan. Lihat deskripsi berikut.

parameter messages:

Konteks meningkatkan akurasi pengenalan istilah khusus. Untuk petunjuk penggunaan, lihat Context enhancement.Batasan: Pesan konteks (tipe input_text dan text ) dibatasi masing-masing lima. Jika batas terlampaui, hanya lima pesan terbaru yang dipertahankan. Total panjang teks konteks per giliran (jumlah panjang bidang user dan assistant text ) tidak boleh melebihi 400 karakter. Setiap karakter dihitung sebagai satu. Karakter berlebih akan dipotong dari akhir.

Jika konteks disertakan, pesan messages harus mengikuti urutan tertentu. Atur pesan konteks berdasarkan giliran percakapan. Dalam setiap giliran, user (tipe input_text ) harus mendahului assistant (tipe text ) yang sesuai. Pesan input_audio user yang berisi audio input harus ditempatkan di akhir messages .

Parameter	Tipe	Wajib	Deskripsi
role	`string`	Ya	Peran pesan. Nilai yang valid: `user` (wajib): Pesan pengguna. Jika tipe adalah `input_audio`, ini mewakili audio yang akan dikenali. Jika tipe adalah `input_text`, ini mewakili hasil pengenalan dari giliran sebelumnya atau kosakata spesifik domain (konteks opsional). `assistant` (konteks opsional): Respons model bahasa besar dari percakapan sebelumnya.
content	`array[object]`	Ya	Daftar isi pesan. Lihat deskripsi berikut.

parameter content:

Parameter	Tipe	Wajib	Deskripsi
type	`string`	Ya	Tipe konten. Setiap permintaan memerlukan setidaknya satu `input_audio` pesan. Nilai yang valid: `input_audio` (wajib): Input audio yang akan dikenali (role adalah user). Anda juga harus menyediakan objek `input_audio`. `input_text` (konteks opsional): Hasil pengenalan ucapan pengguna dari percakapan sebelumnya atau kosakata khusus domain (role adalah user). Anda juga harus menyediakan bidang `text`. `text` (konteks opsional): Respons model bahasa besar dari percakapan sebelumnya (role adalah assistant). Anda juga harus menyediakan bidang `text`.
input_audio	`object`	Tidak	Wajib diisi ketika `type` adalah `input_audio`.
input_audio.data	string	Ya	Data audio yang akan dikenali. Untuk format audio yang didukung, batas ukuran file, batas durasi, dan persyaratan input lainnya, lihat Spesifikasi audio. Dua metode input berikut didukung: URL file audio: Berikan URL file audio yang dapat diakses secara publik. Base64 Data URI: Berikan audio yang dienkode Base64 sebagai Data URI. Gabungkan prefiks `data:{MIME_TYPE};base64,` dengan data audio yang dienkode Base64. Jenis MIME yang didukung meliputi `audio/wav`, `audio/mp3`. Contoh (URL): `https://example.com/audio/sample.wav` Contoh (Base64): `data:audio/wav;base64,{BASE64_ENCODED_DATA}`
text	`string`	Tidak	Wajib jika `type` adalah `input_text`, berikan hasil pengenalan ucapan pengguna dari giliran sebelumnya atau kosakata spesifik domain. Jika `type` adalah `text`, berikan respons model bahasa besar dari giliran sebelumnya. Panjang teks dihitung dalam karakter, dengan setiap karakter dihitung sebagai satu. Total panjang semua bidang `text` pesan di setiap giliran konteks tidak boleh melebihi 400 karakter. Karakter berlebih akan dipotong dari akhir.

Antarmuka utama

NativeNui

initialize

Inisialisasi instance SDK pengenalan ucapan. SDK menggunakan singleton. Jangan inisialisasi ulang sebelum memanggil release. Metode ini memblokir. Panggil dari thread non-UI. Signature metode

public synchronized int initialize(final INativeFileTransCallback callback,
                                   String parameters,
                                   final Constants.LogLevel level,
                                   final boolean save_log)

Parameter

Parameter	Tipe	Deskripsi
`callback`	`INativeFileTransCallback`	Implementasi antarmuka callback event dan data.
`parameters`	`String`	String JSON yang berisi parameter autentikasi, koneksi, dan debugging. Lihat Connection and control parameters.
`level`	`Constants.LogLevel`	Level log yang dicetak oleh SDK.
`save_log`	`boolean`	Apakah akan menyimpan log secara lokal. Jika diatur ke `true`, gunakan Connection and control parameters untuk mengatur `debug_path` guna menentukan path, dan gunakan `max_log_file_size` untuk mengatur ukuran file.

setParams

Gunakan metode ini untuk mengatur atau memperbarui nls_config secara terpisah. Anda tidak perlu memanggil metode ini jika semua parameter disediakan di startFileTranscriber dalam satu panggilan. Signature metode

public synchronized int setParams(String params);

Parameter

Parameter Tipe Deskripsi

Parameter	Tipe	Deskripsi
`params`	`String`	Parameter pengenalan di `nls_config` dan parameter messages. Contoh: `{ "messages": [ { "content": [ { "input_audio": { "data": "{YOUR_AUDIO_URL}" }, "type": "input_audio" } ], "role": "user" } ], "nls_config": { "format": "mp3", "model": "qwen-audio-3.0-asr-flash" } }`

params

String

Parameter pengenalan di nls_config dan parameter messages.
Contoh:

{
  "messages": [
    {
      "content": [
        {
          "input_audio": {
            "data": "{YOUR_AUDIO_URL}"
          },
          "type": "input_audio"
        }
      ],
      "role": "user"
    }
  ],
  "nls_config": {
    "format": "mp3",
    "model": "qwen-audio-3.0-asr-flash"
  }
}

startFileTranscriber

Mulai pengenalan. Signature metode

public synchronized int startFileTranscriber(String params, byte[ ] task_id)

Parameter

Parameter Tipe Deskripsi

Parameter	Tipe	Deskripsi
`params`	`String`	Parameter pengenalan. Contoh: `{ "apikey": "st-****", "messages": [ { "content": [ { "input_audio": { "data": "{YOUR_AUDIO_URL}" }, "type": "input_audio" } ], "role": "user" } ], "nls_config": { "format": "mp3", "model": "qwen-audio-3.0-asr-flash" } }`
`task_id`	`byte[ ]`	Anda dapat mengabaikan parameter ini dan meneruskan null.

params

String

Parameter pengenalan. Contoh:

{
  "apikey": "st-****",
  "messages": [
    {
      "content": [
        {
          "input_audio": {
            "data": "{YOUR_AUDIO_URL}"
          },
          "type": "input_audio"
        }
      ],
      "role": "user"
    }
  ],
  "nls_config": {
    "format": "mp3",
    "model": "qwen-audio-3.0-asr-flash"
  }
}

task_id byte[ ] Anda dapat mengabaikan parameter ini dan meneruskan null.

queryFileTranscriber

Fitur pengenalan ucapan non-real-time ini hanya mendukung permintaan sinkron. Anda dapat mengabaikan metode ini.

cancelFileTranscriber

Segera batalkan tugas saat ini. Signature metode

public synchronized int cancelFileTranscriber(String task_id)

Parameter

Parameter	Tipe	Deskripsi
`task_id`	`String`	ID tugas yang akan dibatalkan, diperoleh dari EVENT_FILE_TRANS_UPLOADED.

release

Lepaskan semua resource internal SDK. Setelah pemanggilan ini, instance SDK menjadi tidak tersedia. Untuk menggunakannya lagi, panggil initialize untuk menginisialisasinya kembali. Signature metode

public synchronized int release();

GetVersion

Dapatkan versi SDK saat ini. Signature metode

public synchronized String GetVersion();

Nilai kembalian Versi SDK saat ini.

INativeFileTransCallback: Callback

onFileTransEventCallback: Dengarkan event dan hasil pengenalan

Signature metode

void onFileTransEventCallback(NuiEvent event, final int resultCode, final int arg2, AsrResult asrResult, String taskId);

Parameter

Parameter	Tipe	Deskripsi
`event`	`NuiEvent`	Event callback.
`resultCode`	`int`	Hanya valid saat event `EVENT_ASR_ERROR` terjadi.
`asrResult`	`AsrResult`	Hasil pengenalan ucapan.
`taskId`	`String`	ID tugas.
`arg2`	`int`	Dicadangkan.

onFileTransLogTrackCallback: Dengarkan log pelacakan

Callback ini menerima log internal SDK yang terperinci untuk pemecahan masalah dan debugging.

default void onFileTransLogTrackCallback(Constants.LogLevel level, String log)

Jenis event

Event	Deskripsi
EVENT_FILE_TRANS_CONNECTED	Berhasil terhubung ke layanan.
EVENT_FILE_TRANS_UPLOADED	File audio berhasil diunggah. Anda dapat memperoleh task_id saat ini pada titik ini.
EVENT_FILE_TRANS_RESULT	Hasil pengenalan akhir.
EVENT_ASR_ERROR	Terjadi error selama pengenalan ucapan.

​Panduan cepat

​Prosedur pemanggilan

​Mode sinkron

​Parameter permintaan

​Parameter koneksi dan kontrol

​Parameter pengenalan

​Antarmuka utama

​NativeNui

​initialize

​setParams

​startFileTranscriber

​queryFileTranscriber

​cancelFileTranscriber

​release

​GetVersion

​INativeFileTransCallback: Callback

​onFileTransEventCallback: Dengarkan event dan hasil pengenalan

​onFileTransLogTrackCallback: Dengarkan log pelacakan

​Jenis event

Panduan cepat

Prosedur pemanggilan

Mode sinkron

Parameter permintaan

Parameter koneksi dan kontrol

Parameter pengenalan

Antarmuka utama

NativeNui

initialize

setParams

startFileTranscriber

queryFileTranscriber

cancelFileTranscriber

release

GetVersion

INativeFileTransCallback: Callback

onFileTransEventCallback: Dengarkan event dan hasil pengenalan

onFileTransLogTrackCallback: Dengarkan log pelacakan

Jenis event