Skip to main content

HTTP API Qwen-Audio-ASR-Filetrans untuk pengenalan ucapan non-real-time

Topik ini menjelaskan parameter dan detail antarmuka HTTP API untuk pengenalan ucapan non-real-time menggunakan Qwen-Audio-ASR-Filetrans.

Untuk persyaratan input seperti format audio yang didukung, batas ukuran file, dan batas durasi, lihat Spesifikasi audio.

Cara kerja

Berbeda dengan panggilan DashScope sinkron yang langsung mengembalikan hasil dalam satu permintaan, panggilan asinkron dirancang untuk file audio panjang atau tugas yang memakan waktu. Mode ini menggunakan alur dua langkah (submit-and-poll) untuk menghindari timeout permintaan akibat penantian lama:
  1. Langkah 1: Kirim tugas.
    • Klien mengirim permintaan pemrosesan asinkron.
    • Setelah memvalidasi permintaan, server tidak langsung menjalankan tugas. Sebagai gantinya, server mengembalikan task_id unik untuk menunjukkan bahwa tugas berhasil dibuat.
  2. Langkah 2: Ambil hasil.
    • Klien menggunakan task_id yang dikembalikan untuk melakukan polling berulang ke antarmuka kueri.
    • Saat tugas selesai, antarmuka kueri mengembalikan hasil pengenalan akhir.

Titik akhir layanan

  • Singapura
  • Tiongkok (Beijing)
Antarmuka kirim tugas: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcriptionAntarmuka kueri tugas: GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}Ganti {WorkspaceId} dengan Workspace ID Anda yang sebenarnya.
Alibaba Cloud Model Studio telah merilis domain khusus ruang kerja untuk wilayah Tiongkok (Beijing) dan Singapura. Domain khusus baru ini memberikan performa lebih baik dan stabilitas lebih tinggi untuk permintaan inferensi. Kami merekomendasikan migrasi ke domain baru:
  • Tiongkok (Beijing): dari dashscope.aliyuncs.com ke {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapura: dari dashscope-intl.aliyuncs.com ke {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

Header permintaan

ParameterTipeWajibDeskripsi
AuthorizationstringYaToken autentikasi dalam format Bearer <your_api_key>. Ganti "<your_api_key>" dengan Kunci API Anda yang sebenarnya. Diperlukan untuk antarmuka kirim tugas maupun antarmuka kueri tugas.
Content-TypestringYaJenis media dari badan permintaan. Hanya diperlukan untuk antarmuka kirim tugas. Nilai tetap: application/json.
X-DashScope-AsyncstringYaFlag tugas asinkron. Hanya diperlukan untuk antarmuka kirim tugas. Nilai tetap: enable. Jangan dihilangkan, atau tugas tidak dapat dikirim.

Antarmuka kirim tugas

Mengirim tugas pengenalan ucapan. Antarmuka ini mengembalikan respons secara asinkron, sehingga Anda perlu melakukan polling status tugas melalui Antarmuka kueri tugas.
Jika deployment khusus mengembalikan current user api does not support asynchronous calls, atur X-DashScope-Async ke disable dan gunakan permintaan sinkron.

Isi permintaan

modelstring(Wajib)Nama model.inputobject(Wajib)Objek parameter input.

Properti

file_urls array[string](Wajib)Daftar URL file audio atau video yang akan ditranskripsikan. HTTP dan HTTPS didukung. Satu permintaan hanya mendukung satu URL. Untuk persyaratan input seperti format audio yang didukung, batas ukuran file, dan batas durasi, lihat Spesifikasi audio.Jika rekaman disimpan di Alibaba Cloud OSS, RESTful API mendukung URL sementara dengan awalan oss://, sedangkan SDK tidak mendukung URL sementara dengan awalan oss://.
  • URL sementara berlaku selama 48 jam dan tidak dapat digunakan setelah kedaluwarsa. Jangan gunakan di lingkungan produksi.
  • Antarmuka unggah kredensial memiliki pembatasan laju hingga 100 QPS dan tidak dapat diskalakan. Jangan gunakan di skenario produksi, konkurensi tinggi, atau pengujian beban.
  • Untuk produksi, gunakan penyimpanan stabil seperti Alibaba Cloud OSS agar file tersedia dalam jangka panjang dan menghindari pembatasan laju.
  • Jika URL file audio yang diatur sebagai URL publik sementara OSS tidak dapat diakses, atur X-DashScope-OssResourceResolve menjadi enable di header permintaan (tidak direkomendasikan). SDK tidak mendukung konfigurasi header permintaan.
contextarray(object)(Opsional)Daftar pesan yang menyediakan konteks percakapan opsional untuk meningkatkan akurasi pengenalan.
Fitur ini belum didukung oleh SDK.
Peningkatan konteks meningkatkan akurasi pengenalan istilah spesifik domain. Untuk penggunaannya, lihat Peningkatan konteks.Batasan: Pesan konteks dengan tipe input_text dan text masing-masing dibatasi hingga 5 pesan. Jika melebihi batas ini, hanya 5 pesan terbaru yang dipertahankan. Panjang total teks per giliran konteks (panjang gabungan bidang text untuk user dan assistant) tidak boleh melebihi 400 karakter (dihitung per karakter, setiap karakter dihitung sebagai 1). Kelebihan akan dipotong dari akhir.
Saat Anda menyertakan konteks, urutan pesan dalam array messages sangat penting: pesan konteks harus diatur berdasarkan giliran percakapan. Dalam setiap giliran, pesan user (tipe input_text) harus mendahului pesan assistant yang sesuai (tipe text). Pesan user yang berisi input_audio harus ditempatkan di akhir array messages.

Properti

rolestring(Wajib)Peran pesan. Nilai yang valid:
  • user: hasil pengenalan dari giliran sebelumnya atau daftar kata spesifik domain.
  • assistant: balasan model bahasa besar dari giliran sebelumnya.
contentarray(object)(Wajib)Daftar item konten pesan.

Properti

typestring(Wajib)Tipe konten. Nilai yang valid:
  • input_text (opsional, konteks): hasil pengenalan ucapan user dari giliran sebelumnya, atau daftar kata spesifik domain (peran adalah user). Anda juga harus mengirimkan bidang text.
  • text (opsional, konteks): balasan model bahasa besar dari giliran sebelumnya (peran adalah assistant). Anda juga harus mengirimkan bidang text.
textstring(Wajib bersyarat)Saat type adalah input_text, masukkan hasil pengenalan ucapan user dari giliran sebelumnya atau daftar kata spesifik domain. Saat type adalah text, masukkan balasan model bahasa besar dari giliran sebelumnya. Teks dihitung per karakter, dan setiap karakter dihitung sebagai 1. Panjang gabungan bidang text di semua pesan dalam satu giliran konteks tidak boleh melebihi 400 karakter. Kelebihan akan dipotong dari akhir.
parametersobject(Wajib)Selalu sertakan parameters. Jika tidak ada opsi yang perlu diatur, teruskan objek kosong {}. Jika kolom ini dihilangkan, tugas transkripsi yang telah dikirim akan gagal.

Properti

keep_dialect boolean (Opsional)Hanya didukung oleh qwen-audio-3.1-asr-flash-filetrans. Nilai default adalah false, yang mentranskripsikan dialek menjadi bahasa Mandarin standar. Tetapkan ke true untuk mempertahankan ungkapan dialek.vocabulary_id string(Opsional)ID daftar kata kunci yang telah dikompilasi sebelumnya.Hasilkan ID ini terlebih dahulu dengan memanggil API pembuatan daftar kata kunci. Kirimkan ID tersebut saat pengenalan untuk menggunakan kata kunci dalam daftar tersebut.Cocok untuk skenario di mana kosakata sudah diketahui dan relatif stabil, serta Anda perlu menggunakan kembali daftar kata yang sama di berbagai permintaan.Untuk detail penggunaan, lihat Kata kunci yang telah dikompilasi.vocabulary object(Opsional)Kata kunci instan.Dikirim sebagai pasangan kunci-nilai, di mana kunci adalah teks kata kunci (string) dan nilai adalah bobot kata kunci (integer). Tidak perlu membuat daftar kata kunci terlebih dahulu. Bobot berkisar antara [1, 5] atau diatur ke 50: nilai dalam [1, 5] membuat model lebih cenderung mengeluarkan kata tersebut seiring peningkatan nilainya; nilai 50 menandakan kata kunci super, yang sangat meningkatkan recall, tetapi jumlah kata kunci super tidak boleh melebihi 50.Cocok untuk optimasi kata kunci sementara pada tingkat sesi.Jika kata kunci instan dan prakompilasi dikonfigurasi bersama, kedua daftar digabungkan. Jika hasil gabungan melebihi 2000 kata kunci, 2000 kata kunci dipilih secara acak. Untuk detail penggunaan, lihat Kata kunci instan.channel_id array[integer](Opsional)Indeks trek audio yang akan dikenali dalam file audio multi-trek. Indeks dimulai dari 0. Misalnya, [0] mengenali trek pertama, dan [0, 1] mengenali trek pertama dan kedua secara bersamaan. Jika Anda menghilangkan parameter ini, hanya trek pertama yang diproses.
Setiap trek yang ditentukan ditagih secara terpisah. Misalnya, meminta [0, 1] untuk satu file menghasilkan dua tagihan terpisah.
Nilai default: [0].special_word_filter string(Opsional) Atur kata yang akan diganti atau dihapus. Parameter ini adalah string JSON dengan bidang berikut:
  • filter_with_signed.word_list: Array string berisi kata yang akan diganti dengan karakter * dalam jumlah yang sama.
  • filter_with_empty.word_list: Array string berisi kata yang akan dihapus dari hasil.
  • system_reserved_filter: Boolean, default true, untuk turut menggunakan daftar bawaan. Aturan kustom tetap berlaku saat nilainya false.
Jika parameter dihilangkan, kata yang cocok dengan daftar kata sensitif bawaan Model Studio diganti dengan karakter * dalam jumlah yang sama.Misalnya, ganti project dengan tanda bintang yang sama panjang dan hapus report menggunakan nilai berikut:
{
  "special_word_filter": "{\"filter_with_signed\":{\"word_list\":[\"project\"]},\"filter_with_empty\":{\"word_list\":[\"report\"]},\"system_reserved_filter\":true}"
}
diarization_enabled boolean(Opsional)Apakah akan mengaktifkan diarization pembicara. Secara default dinonaktifkan.Hanya berlaku untuk audio mono. Audio multi-channel tidak mendukung diarization pembicara.Saat diaktifkan, hasil pengenalan menyertakan bidang speaker_id yang membedakan pembicara berbeda.
Saat diarization pembicara diaktifkan, pastikan durasi audio tidak melebihi 2 jam. Jika tidak, pengenalan mungkin gagal atau timeout.
Untuk contoh speaker_id, lihat Deskripsi hasil pengenalan.Nilai default: false.speaker_count integer(Opsional)
Hanya berlaku saat diarization pembicara diaktifkan (diarization_enabled diatur ke true).
Nilai referensi jumlah pembicara. Rentang valid adalah bilangan bulat dari 2 hingga 100 (inklusif).Secara default, jumlah pembicara dideteksi secara otomatis. Jika Anda mengatur nilai ini, nilai tersebut hanya membimbing algoritma untuk menghasilkan jumlah yang ditentukan bila memungkinkan dan tidak menjamin jumlah pasti tersebut.Tidak ada nilai default.language_hints array[string](Opsional)Kode bahasa yang akan dikenali. Jika Anda tidak dapat menentukan bahasa sebelumnya, biarkan tidak diatur dan model akan mendeteksi bahasa secara otomatis.Anda dapat menetapkan hingga 4 nilai. Jika lebih, hanya 4 nilai pertama yang berlaku.
  • zh: Tionghoa
  • en: Inggris
  • ja: Jepang
  • ko: Korea
  • vi: Vietnam
  • th: Thai
  • id: Bahasa Indonesia
  • ms: Melayu
  • tl: Filipina
  • 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: Hongaria
  • ro: Rumania
  • bg: Bahasa Bulgaria
  • hr: Kroasia
  • sk: Slovak
  • Panggilan dasar
  • Kata kunci inline
  • Konteks
Contoh berikut menggunakan wilayah Singapura. Ganti "{WorkspaceId}" dengan Workspace ID Anda yang sebenarnya. Konfigurasi berbeda tergantung wilayah. Wilayah Singapura dan Beijing menggunakan Kunci API yang berbeda.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription' \
     --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
     --header "Content-Type: application/json" \
     --header "X-DashScope-Async: enable" \
     --data '{
    "model": "qwen-audio-3.0-asr-flash-filetrans",
    "input": {
        "file_urls": [
            "{YOUR_AUDIO_URL}"
        ]
    },
    "parameters": {
        "channel_id": [0]
    }
}'

Isi respons

request_idstringPengidentifikasi unik panggilan ini.outputobjectData yang dikembalikan oleh antarmuka kirim tugas.

Properti

task_idstringID tugas. Kirimkan ID ini sebagai string di Antarmuka kueri tugas.task_statusstringStatus tugas. Mengembalikan PENDING saat pengiriman berhasil.
{
  "output": {
    "task_status": "PENDING",
    "task_id": "c2e5d63b-96e1-4607-bb91-************"
  },
  "request_id": "77ae55ae-be17-97b8-9942--************"
}

Antarmuka kueri tugas

Menanyakan status eksekusi dan hasil tugas pengenalan ucapan. Lakukan polling ke antarmuka ini hingga tugas mencapai status terminal.

Isi permintaan

task_idstring(Wajib)
Parameter ini adalah parameter path URL. Tidak ada badan permintaan.
Untuk menanyakan tugas, tentukan ID-nya. ID ini adalah task_id yang dikembalikan saat memanggil Antarmuka kirim tugas.
Contoh berikut menggunakan wilayah Singapura. Ganti "{WorkspaceId}" dengan Workspace ID Anda yang sebenarnya. Konfigurasi berbeda tergantung wilayah. Wilayah Singapura dan Beijing menggunakan Kunci API yang berbeda.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}' \
     --header "Authorization: Bearer $DASHSCOPE_API_KEY"

Isi respons

request_idstringPengidentifikasi unik panggilan ini.outputobjectData yang dikembalikan oleh antarmuka kueri tugas.

Properti

task_idstringID tugas yang ditanyakan.task_statusstringStatus tugas yang ditanyakan.
Saat tugas berisi beberapa subtugas, status tugas keseluruhan ditandai sebagai SUCCEEDED selama ada subtugas yang berhasil. Periksa bidang subtask_status untuk menentukan hasil subtugas tertentu.
submit_timestringWaktu tugas dikirim.scheduled_timestringWaktu tugas dijadwalkan untuk dijalankan.end_timestringWaktu tugas berakhir.resultsarray[object]Daftar hasil subtugas, satu untuk setiap file audio yang akan dikenali.
subtask_statusstringStatus subtugas.file_urlstringURL file yang diproses oleh tugas transkripsi file.transcription_urlstringTautan ke hasil pengenalan. Tautan ini berlaku selama 24 jam. Setelah kedaluwarsa, Anda tidak dapat menanyakan tugas atau mengunduh hasil melalui URL yang dikembalikan oleh kueri sebelumnya.Hasil pengenalan disimpan sebagai file JSON. Anda dapat mengunduh file tersebut melalui tautan di atas atau membaca isinya langsung dengan permintaan HTTP. Untuk arti setiap bidang dalam data JSON, lihat Deskripsi hasil pengenalan.codestring
Hanya dikembalikan saat subtugas gagal.
Kode kesalahan subtugas yang gagal.messagestring
Hanya dikembalikan saat subtugas gagal.
Pesan kesalahan subtugas yang gagal.
task_metricsobjectStatistik eksekusi keseluruhan untuk tugas.
TOTALintegerJumlah total subtugas.SUCCEEDEDintegerJumlah subtugas yang berhasil.FAILEDintegerJumlah subtugas yang gagal.
{
  "request_id": "f9e1afad-94d3-997e-a83b-************",
  "output": {
    "task_id": "f86ec806-4d73-485f-a24f-************",
    "task_status": "SUCCEEDED",
    "submit_time": "2024-09-12 15:11:40.041",
    "scheduled_time": "2024-09-12 15:11:40.071",
    "end_time": "2024-09-12 15:11:40.903",
    "results": [
      {
        "file_url": "{YOUR_AUDIO_URL}",
        "transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/pre/filetrans-16k/20240912/15%3A11/409a4b92-445b-4dd8-8c1d-f110954d82d8-1.json?Expires=1726211500&OSSAccessKeyId=YOUR_ACCESS_KEY_ID&Signature=YOUR_SIGNATURE",
        "subtask_status": "SUCCEEDED"
      }
    ],
    "task_metrics": {
      "TOTAL": 1,
      "SUCCEEDED": 1,
      "FAILED": 0
    }
  },
  "usage": {
    "duration": 9
  }
}

Antarmuka lain: kueri batch status tugas / batalkan tugas

Untuk detailnya, lihat Mengelola tugas asinkron: Anda dapat melakukan kueri batch terhadap tugas pengenalan ucapan non-real-time yang dikirim dalam 24 jam terakhir, dan membatalkan tugas yang berada dalam status PENDING (antrian).

Deskripsi hasil pengenalan

Hasil pengenalan disimpan sebagai file JSON.
{
    "file_url":"{YOUR_AUDIO_URL}",
    "properties":{
        "audio_format":"pcm_s16le",
        "channels":[
            0
        ],
        "original_sampling_rate":16000,
        "original_duration_in_milliseconds":3834
    },
    "transcripts":[
        {
            "channel_id":0,
            "content_duration_in_milliseconds":3720,
            "text":"Hello world, this is Alibaba Speech Lab.",
            "sentences":[
                {
                    "begin_time":100,
                    "end_time":3820,
                    "text":"Hello world, this is Alibaba Speech Lab.",
                    "sentence_id":1,
                    "speaker_id":0, //Bidang ini ditampilkan hanya saat diarization pembicara otomatis diaktifkan
                    "words":[
                        {
                            "begin_time":100,
                            "end_time":596,
                            "text":"Hello ",
                            "punctuation":""
                        },
                        {
                            "begin_time":596,
                            "end_time":844,
                            "text":"world",
                            "punctuation":", "
                        }
                        // Konten lainnya dihilangkan di sini
                    ]
                }
            ]
        }
    ]
}
Parameter berikut perlu diperhatikan:
ParameterTipeDeskripsi
audio_formatstringFormat audio file sumber.
channelsarray[integer]Indeks trek audio dalam file sumber. Untuk audio satu trek, [0] dikembalikan; untuk audio dua trek, [0, 1] dikembalikan; dan seterusnya.
original_sampling_rateintegerFrekuensi sampling (Hz) audio dalam file sumber.
original_duration_in_millisecondsintegerDurasi audio asli (ms) dalam file sumber.
channel_idintegerIndeks trek hasil transkripsi, dimulai dari 0.
content_durationintegerDurasi (ms) konten dalam trek yang diidentifikasi sebagai ucapan.
Penjelasan penagihan berikut berlaku untuk qwen-audio-3.0-asr-flash-filetrans. qwen-audio-3.1-asr-flash-filetrans ditagih berdasarkan penggunaan token.
Layanan model pengenalan ucapan hanya mentranskripsikan konten dalam trek yang diidentifikasi sebagai ucapan, dan mengukur serta menagih berdasarkan durasi tersebut. Konten non-ucapan tidak diukur atau ditagih. Biasanya, durasi konten ucapan lebih pendek daripada durasi audio asli. Karena keberadaan konten ucapan ditentukan oleh model AI, hasilnya mungkin sedikit berbeda dari situasi aktual.
transcriptstringHasil transkripsi tingkat paragraf.
sentencesarrayHasil transkripsi tingkat kalimat.
wordsarrayHasil transkripsi tingkat kata.
begin_timeintegerTimestamp mulai (ms).
end_timeintegerTimestamp akhir (ms).
textstringHasil transkripsi.
speaker_idintegerIndeks pembicara saat ini, dimulai dari 0, digunakan untuk membedakan pembicara berbeda.Bidang ini muncul dalam hasil pengenalan hanya saat diarization pembicara diaktifkan.
punctuationstringTanda baca yang diprediksi setelah kata, jika ada.