Referensi API untuk pengenalan file rekaman - Intelligent Speech Interaction

Layanan pengenalan file rekaman mentranskripsikan file audio yang dikirimkan melalui URL HTTP atau HTTPS. Layanan ini mendukung dua metode pengambilan—polling dan callback—dan memproses file secara asinkron, bukan secara real time.

Fitur yang didukung

File audio WAV dan MP3 satu track
Dua metode pengambilan: polling dan callback
Model linguistik kustom dan kosakata hotword
Berbagai bahasa: Mandarin Tiongkok, dialek Tiongkok, dan Inggris

Batasan

Kendala	Detail
Format URL	Harus dapat diakses publik melalui nama domain. Alamat IP dan spasi tidak diperbolehkan.
Ukuran file	Maksimum 512 MB
Waktu pemrosesan (uji coba gratis)	Pengenalan selesai dalam waktu 24 jam
Waktu pemrosesan (Edisi Komersial)	Pengenalan selesai dalam waktu 3 jam
Masa retensi hasil	72 jam
Kuota harian (uji coba gratis)	Hingga 2 jam audio per hari kalender

Contoh URL yang valid

https://aliyun-nls.oss-cn-hangzhou.aliyuncs.com/asr/fileASR/examples/nls-sample-16k.wav

Contoh URL yang tidak valid

http://127.0.0.1/sample.wav
D:\files\sample.wav

Batas pemrosesan 24 jam dan 3 jam tidak berlaku jika total durasi file yang diunggah dalam 30 menit melebihi 500 jam. Untuk pemrosesan audio skala besar, hubungi tim pra-penjualan Alibaba Cloud.

Cara kerja

Layanan pengenalan file rekaman menggunakan API POP Alibaba Cloud (gaya remote procedure call). Klien mengirim permintaan melalui HTTP, dan file rekaman harus dapat diakses melalui URL publik.

Tersedia dua operasi:

Kirim task pengenalan (POST): Kirim URL file rekaman dan parameter konfigurasi. Server mengembalikan ID task.
Kueri hasil pengenalan (GET): Gunakan ID task untuk melakukan polling terhadap hasil, atau terima hasil tersebut melalui callback jika Anda mengaktifkan metode callback.

Operasi kueri mendukung hingga 100 permintaan per detik (QPS). Jika Anda melebihi batas ini, server akan mengembalikan Throttling.User : Request was denied due to user flow control. Atur interval polling agar tetap berada dalam batas tersebut.

Pilih metode pengambilan

Metode	Cara kerja	Kapan digunakan
Polling	Kirim task, lalu secara berkala kueri hasilnya menggunakan ID task.	Default. Berfungsi di semua lingkungan.
Callback	Kirim task dengan URL callback. Server mengirimkan hasil ke URL tersebut menggunakan metode POST setelah pemrosesan selesai.	Gunakan ketika Anda dapat menyediakan titik akhir HTTP atau HTTPS yang dapat dijangkau publik.

Prasyarat

Sebelum mengirimkan task pengenalan:

Periksa format dan laju pengambilan sampel audio file Anda. Pilih skenario dan model yang sesuai di Konsol Interaksi Suara Cerdas berdasarkan kasus penggunaan Anda.
Simpan file audio di Alibaba Cloud Object Storage Service (OSS) atau di server file yang dapat diakses publik.
- File OSS publik: Dapatkan URL OSS langsung. Lihat Objek baca publik.
- File OSS privat: Hasilkan URL presigned dengan periode validitas menggunakan SDK. Lihat Objek privat.
- Server file kustom: Pastikan field Content-Length pada header respons HTTP sesuai dengan ukuran file aktual, atau unduhan akan gagal.

Kirim task pengenalan

Metode: POST

Atur parameter permintaan sebagai string JSON dalam badan permintaan.

Contoh isi permintaan

{
    "appkey": "your-appkey",
    "file_link": "https://aliyun-nls.oss-cn-hangzhou.aliyuncs.com/asr/fileASR/examples/nls-sample-16k.wav",
    "version": "4.0",
    "auto_split": false,
    "enable_words": false,
    "enable_sample_rate_adaptive": true,
    "valid_times": [
        {
            "begin_time": 200,
            "end_time": 2000,
            "channel_id": 0
        }
    ]
}

Parameter permintaan

Parameter	Tipe	Wajib	Deskripsi
`appkey`	String	Ya	Appkey proyek Anda di Konsol Interaksi Suara Cerdas.
`file_link`	String	Ya	URL file rekaman. Pastikan skenario dan model proyek sesuai dengan file rekaman.
`version`	String	Ya	Versi layanan. Nilai default: `2.0`. Atur ke `4.0` untuk integrasi baru.
`enable_words`	Boolean	Tidak	Menentukan apakah akan mengembalikan hasil pengenalan tingkat kata. Nilai default: `false`. Memerlukan `version: 4.0`.
`enable_sample_rate_adaptive`	Boolean	Tidak	Menentukan apakah akan melakukan downsampling otomatis pada audio dengan laju pengambilan sampel di atas 16.000 Hz. Nilai default: `false`. Memerlukan `version: 4.0`.
`enable_callback`	Boolean	Tidak	Menentukan apakah akan menggunakan metode callback. Nilai default: `false`.
`callback_url`	String	Tidak	URL callback. Wajib diisi saat `enable_callback` bernilai `true`. Harus berupa URL HTTP atau HTTPS dengan nama domain (bukan alamat IP).
`auto_split`	Boolean	Tidak	Menentukan apakah akan mengaktifkan pemisahan track otomatis. Saat diaktifkan, server mengidentifikasi pembicara setiap kalimat menggunakan field `ChannelId`. Hanya mendukung audio mono dengan laju 8.000 Hz. Tidak dapat diatur ke `true` saat `enable_unify_post` bernilai `true`.
`enable_unify_post`	Boolean	Tidak	Menentukan apakah akan mengaktifkan post-processing. Nilai default: `false`. Tidak dapat diatur ke `true` saat `auto_split` bernilai `true`.
`enable_inverse_text_normalization`	Boolean	Tidak	Menentukan apakah akan mengaktifkan normalisasi teks terbalik (ITN), yang mengonversi angka Tiongkok menjadi angka Arab. Nilai default: `false`. Memerlukan `version: 4.0` dan `enable_unify_post: true`. ITN tidak berlaku untuk hasil tingkat kata.
`enable_disfluency`	Boolean	Tidak	Menentukan apakah akan mengaktifkan deteksi disfluensi. Nilai default: `false`. Memerlukan `version: 4.0` dan `enable_unify_post: true`.
`valid_times`	List\<ValidTime\>	Tidak	Rentang waktu dalam track audio yang memerlukan pengenalan suara.
`max_end_silence`	Integer	Tidak	Durasi maksimum keheningan di akhir kalimat. Nilai default: `450`. Satuan: milidetik.
`max_single_segment_time`	Integer	Tidak	Durasi maksimum satu kalimat. Nilai minimum: `10000`. Nilai default: `20000`. Satuan: milidetik.
`customization_id`	String	Tidak	ID model linguistik kustom yang dibuat melalui API POP.
`class_vocabulary_id`	String	Tidak	ID kosakata hotword terkategorikan.
`vocabulary_id`	String	Tidak	ID kosakata hotword ekstensif.

Objek ValidTime

Parameter	Tipe	Wajib	Deskripsi
`begin_time`	Int	Ya	Offset waktu mulai rentang waktu. Satuan: milidetik.
`end_time`	Int	Ya	Offset waktu akhir rentang waktu. Satuan: milidetik.
`channel_id`	Int	Ya	Track audio tempat rentang waktu tersebut berlaku. Nilai dimulai dari `0`.

Parameter respons

Kode status HTTP 200 menunjukkan permintaan diterima.

Parameter	Tipe	Deskripsi
`TaskId`	String	ID task. Gunakan ini untuk mengkueri hasil pengenalan.
`RequestId`	String	ID permintaan, untuk debugging.
`StatusCode`	Int	Kode status.
`StatusText`	String	Pesan status.

Contoh respons

{
    "TaskId": "4b56f0c4b7e611e88f34c33c2a60****",
    "RequestId": "E4B183CC-6CFE-411E-A547-D877F7BD****",
    "StatusText": "SUCCESS",
    "StatusCode": 21050000
}

Kueri hasil pengenalan

Metode: GET

Masukkan ID task yang dikembalikan oleh operasi POST sebagai parameter permintaan. Lakukan polling dengan interval yang wajar agar tetap berada dalam batas 100 QPS.

Parameter permintaan

Parameter	Tipe	Wajib	Deskripsi
`TaskId`	String	Ya	ID task yang dikembalikan oleh operasi kirim.

Parameter respons

Kode status HTTP 200 menunjukkan permintaan kueri diterima.

Parameter	Tipe	Deskripsi
`TaskId`	String	ID task.
`StatusCode`	Int	Kode status.
`StatusText`	String	Pesan status.
`RequestId`	String	ID permintaan, untuk debugging.
`Result`	Object	Hasil pengenalan. Hanya muncul saat `StatusText` bernilai `SUCCESS`.
`Sentences`	List\<SentenceResult\>	Hasil pengenalan tingkat kalimat. Hanya muncul saat `StatusText` bernilai `SUCCESS`.
`Words`	List\<WordResult\>	Hasil pengenalan tingkat kata. Hanya muncul saat `enable_words` bernilai `true` dan `version` bernilai `4.0`.
`BizDuration`	Long	Total durasi audio yang dikenali. Satuan: milidetik.
`SolveTime`	Long	Stempel waktu saat tugas pengenalan selesai, dalam satuan milidetik.

Objek SentenceResult

Parameter	Tipe	Deskripsi
`ChannelId`	Int	Track audio tempat kalimat tersebut berada.
`BeginTime`	Int	Offset waktu mulai kalimat. Satuan: milidetik.
`EndTime`	Int	Offset waktu akhir kalimat. Satuan: milidetik.
`Text`	String	Teks yang dikenali dari kalimat tersebut.
`EmotionValue`	Int	Intensitas emosi, dihitung sebagai desibel volume dibagi 10. Nilai valid: 1–10. Nilai lebih tinggi menunjukkan emosi lebih kuat.
`SilenceDuration`	Int	Durasi keheningan antara kalimat ini dan kalimat sebelumnya. Satuan: detik.
`SpeechRate`	Int	Laju bicara rata-rata kalimat tersebut. Satuan: kata per menit.

Objek WordResult

Parameter	Tipe	Deskripsi
`ChannelId`	Int	Track audio tempat kata tersebut berada.
`BeginTime`	Int	Waktu mulai kata tersebut. Satuan: milidetik.
`EndTime`	Int	Waktu akhir kata tersebut. Satuan: milidetik.
`Word`	String	Kata yang dikenali.

Contoh respons

Task berhasil diselesaikan (file satu track nls-sample-16k.wav)

{
    "TaskId": "d429dd7dd75711e89305ab6170fe****",
    "RequestId": "9240D669-6485-4DCC-896A-F8B31F94****",
    "StatusText": "SUCCESS",
    "BizDuration": 2956,
    "SolveTime": 1540363288472,
    "StatusCode": 21050000,
    "Result": {
        "Sentences": [{
            "EndTime": 2365,
            "SilenceDuration": 0,
            "BeginTime": 340,
            "Text": "Weather in Beijing",
            "ChannelId": 0,
            "SpeechRate": 177,
            "EmotionValue": 5.0
        }]
    }
}

Respons callback (versi 4.0, enable_callback: true)

Format respons callback sama dengan format respons polling.

{
    "Result": {
        "Sentences": [{
            "EndTime": 2365,
            "SilenceDuration": 0,
            "BeginTime": 340,
            "Text": "Weather in Beijing",
            "ChannelId": 0,
            "SpeechRate": 177,
            "EmotionValue": 5.0
        }]
    },
    "TaskId": "36d01b244ad811e9952db7bb7ed2****",
    "StatusCode": 21050000,
    "StatusText": "SUCCESS",
    "RequestTime": 1553062810452,
    "SolveTime": 1553062810831,
    "BizDuration": 2956
}

RequestTime adalah timestamp saat permintaan pengenalan dikirimkan, dalam milidetik. Misalnya, nilai 1553062810452 menunjukkan pukul 14:20:10 pada 20 Maret 2019, UTC+8. SolveTime adalah timestamp saat task selesai, dalam milidetik.

Task sedang dalam antrian

{
    "TaskId": "c7274235b7e611e88f34c33c2a60****",
    "RequestId": "981AD922-0655-46B0-8C6A-5C836822****",
    "StatusText": "QUEUEING",
    "StatusCode": 21050002
}

Task sedang berjalan

{
    "TaskId": "c7274235b7e611e88f34c33c2a60****",
    "RequestId": "8E908ED2-867F-457E-82BF-4756194A****",
    "StatusText": "RUNNING",
    "BizDuration": 0,
    "StatusCode": 21050001
}

Gagal mengunduh file

{
    "TaskId": "4cf25b7eb7e711e88f34c33c2a60****",
    "RequestId": "098BF27C-4CBA-45FF-BD11-3F532F26****",
    "StatusText": "FILE_DOWNLOAD_FAILED",
    "BizDuration": 0,
    "SolveTime": 1536906469146,
    "StatusCode": 41050002
}

Hasil tingkat kata (enable_words: true, version: 4.0)

Hasil tingkat kata disertakan bersama hasil tingkat kalimat. Respons polling dan callback menggunakan format yang sama.

{
    "StatusCode": 21050000,
    "Result": {
        "Sentences": [{
            "SilenceDuration": 0,
            "EmotionValue": 5.0,
            "ChannelId": 0,
            "Text": "Weather in Beijing",
            "BeginTime": 340,
            "EndTime": 2365,
            "SpeechRate": 177
        }],
        "Words": [{
            "ChannelId": 0,
            "Word": "Weather",
            "BeginTime": 640,
            "EndTime": 940
        }, {
            "ChannelId": 0,
            "Word": "in",
            "BeginTime": 940,
            "EndTime": 1120
        }, {
            "ChannelId": 0,
            "Word": "Beijing",
            "BeginTime": 1120,
            "EndTime": 2020
        }]
    },
    "SolveTime": 1553236968873,
    "StatusText": "SUCCESS",
    "RequestId": "027B126B-4AC8-4C98-9FEC-A031158F****",
    "TaskId": "b505e78c4c6d11e9a213e11db149****",
    "BizDuration": 2956
}

Kode status layanan

Kode status Normal

Kode status	Pesan status	Deskripsi	Tindakan
21050000	SUCCESS	Task berhasil diselesaikan.	Tidak diperlukan tindakan.
21050001	RUNNING	Task sedang berjalan.	Kueri lagi nanti.
21050002	QUEUEING	Task sedang dalam antrian.	Kueri lagi nanti.
21050003	SUCCESS_WITH_NO_VALID_FRAGMENT	Task berhasil, tetapi tidak ada data suara yang terdeteksi.	Periksa apakah audio berisi suara atau durasi suara terlalu singkat.

Kode error

Kode status yang diawali dengan 4 adalah error sisi klien. Kode status yang diawali dengan 5 adalah error sisi server.

Kode status	Pesan status	Deskripsi	Solusi
41050001	USER_BIZDURATION_QUOTA_EXCEED	Kuota audio harian terlampaui.	Kirim email ke nls_support@service.aliyun.com untuk meningkatkan kuota Anda.
41050002	FILE_DOWNLOAD_FAILED	File audio tidak dapat diunduh.	Periksa apakah URL benar dan dapat diakses publik.
41050003	FILE_CHECK_FAILED	Format file audio tidak valid.	Periksa apakah file rekaman berupa file WAV atau MP3 satu track atau dua track.
41050004	FILE_TOO_LARGE	File audio melebihi batas ukuran.	Pastikan ukuran file tidak lebih dari 512 MB.
41050005	FILE_NORMALIZE_FAILED	Normalisasi audio gagal.	Periksa apakah file tidak rusak dan dapat diputar.
41050006	FILE_PARSE_FAILED	Penguraian audio gagal.	Periksa apakah file tidak rusak dan dapat diputar.
41050007	MKV_PARSE_FAILED	Penguraian MKV gagal.	Periksa apakah file tidak rusak dan dapat diputar.
41050008	UNSUPPORTED_SAMPLE_RATE	Laju pengambilan sampel audio tidak didukung.	Periksa apakah laju pengambilan sampel file sesuai dengan model Pengenalan Suara Otomatis (ASR) yang terikat pada appkey Anda di Konsol Interaksi Suara Cerdas.
41050009	UNSUPPORTED_ASR_GROUP	Grup ASR tidak didukung.	Periksa apakah appkey termasuk dalam Akun Alibaba Cloud yang sama dengan Pasangan Kunci Akses.
41050010	FILE_TRANS_TASK_EXPIRED	Task pengenalan telah kedaluwarsa.	Periksa apakah ID task valid dan belum kedaluwarsa.
41050011	REQUEST_INVALID_FILE_URL_VALUE	Parameter `file_link` tidak valid.	Periksa format `file_link`.
41050012	REQUEST_INVALID_CALLBACK_VALUE	Parameter `callback_url` tidak valid.	Periksa format `callback_url`.
41050013	REQUEST_PARAMETER_INVALID	Parameter permintaan tidak valid.	Periksa apakah badan permintaan merupakan string JSON yang valid.
41050014	REQUEST_EMPTY_APPKEY_VALUE	Parameter `appkey` tidak ada.	Tambahkan parameter `appkey` ke permintaan.
41050015	REQUEST_APPKEY_UNREGISTERED	Parameter `appkey` tidak valid.	Periksa apakah appkey valid dan termasuk dalam Akun Alibaba Cloud yang sama dengan ID AccessKey.
41050021	RAM_CHECK_FAILED	Autentikasi Pengguna RAM gagal.	Periksa apakah Pengguna RAM memiliki izin untuk memanggil API Interaksi Suara Cerdas.
41050023	CONTENT_LENGTH_CHECK_FAILED	Header `Content-Length` tidak valid.	Periksa apakah nilai `Content-Length` pada header respons HTTP sesuai dengan ukuran file aktual.
41050024	FILE_404_NOT_FOUND	File audio tidak ditemukan di URL yang ditentukan.	Periksa apakah file ada di URL tersebut.
41050025	FILE_403_FORBIDDEN	Akses ke file audio ditolak.	Periksa apakah file dapat diakses publik.
41050026	FILE_SERVER_ERROR	Terjadi error pada server file.	Periksa apakah server file beroperasi dengan benar.
51050000	INTERNAL_ERROR	Terjadi error internal.	Abaikan jika bersifat sementara. Buat tiket jika error berulang.
51050001	VAD_FAILED	Deteksi aktivitas suara (VAD) gagal.	Abaikan jika bersifat sementara. Buat tiket jika error berulang.
51050002	RECOGNIZE_FAILED	ASR gagal.	Abaikan jika bersifat sementara. Buat tiket jika error berulang.
51050003	RECOGNIZE_INTERRUPT	ASR terganggu.	Abaikan jika bersifat sementara. Buat tiket jika error berulang.
51050004	OFFER_INTERRUPT	Task tidak dapat ditulis ke antrian.	Abaikan jika bersifat sementara. Buat tiket jika error berulang.
51050005	FILE_TRANS_TIMEOUT	Task melebihi batas waktu.	Abaikan jika bersifat sementara. Buat tiket jika error berulang.
51050006	FRAGMENT_FAILED	Konversi audio multi-channel ke mono gagal.	Abaikan jika bersifat sementara. Buat tiket jika error berulang.

Catatan versi

Layanan pengenalan file rekaman menggunakan versi 2.0 secara default untuk integrasi yang sudah ada. Jika Anda telah mengaktifkan layanan pengenalan file rekaman tanpa mengatur versi ke 4.0, versinya adalah 2.0 secara default. Anda dapat terus menggunakan versi ini. Jika Anda pengguna baru, atur version ke 4.0.

Perbedaan utama: Pada versi 2.0, respons callback menggunakan format JSON snake_case yang berbeda dari respons polling. Pada versi 4.0, keduanya menggunakan format camelCase yang sama.

Contoh respons callback versi 2.0

{
    "result": [{
        "begin_time": 340,
        "channel_id": 0,
        "emotion_value": 5.0,
        "end_time": 2365,
        "silence_duration": 0,
        "speech_rate": 177,
        "text": "Weather in Beijing"
    }],
    "task_id": "3f5d4c0c399511e98dc025f34473****",
    "status_code": 21050000,
    "status_text": "SUCCESS",
    "request_time": 1551164878830,
    "solve_time": 1551164879230,
    "biz_duration": 2956
}