Skip to main content

HTTP API Fun-ASR untuk pengenalan ucapan non-real-time

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

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
Saat Anda mengirim tugas dengan domain baru (https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com), badan permintaan harus menyertakan objek parameters. Bahkan jika Anda tidak perlu mengatur parameter apa pun, kirimkan objek kosong {}. Jika tidak, tugas berhasil dikirim tetapi pengenalan gagal.

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.

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.
parametersobject(Opsional)Objek parameter permintaan.
Saat Anda menggunakan domain baru (https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com), parameters wajib disertakan. Bahkan jika Anda tidak perlu mengatur parameter apa pun, kirimkan objek kosong {}. Jika Anda menghilangkan bidang ini, tugas berhasil dikirim, tetapi antarmuka kueri tugas mengembalikan kegagalan pengenalan.

Properti

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. Teruskan pasangan kunci-nilai dengan teks kata kunci (string) sebagai kunci dan bobot bilangan bulat (integer) sebagai nilai. Anda tidak perlu membuat daftar kata kunci prakompilasi terlebih dahulu.Untuk penggunaannya, 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 1 nilai. Jika lebih, hanya 1 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
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": "fun-asr",
    "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.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.