SDK Python pengenalan ucapan non-real-time Paraformer

Dokumen ini hanya berlaku untuk wilayah Tiongkok Daratan (Beijing). Untuk menggunakan model ini, Anda harus menggunakan API key dari wilayah Tiongkok Daratan (Beijing).

Alibaba Cloud Model Studio telah merilis domain khusus ruang kerja untuk wilayah Tiongkok (Beijing). Domain khusus baru ini memberikan performa lebih unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami merekomendasikan migrasi dari dashscope.aliyuncs.com ke {WorkspaceId}.cn-beijing.maas.aliyuncs.com.Ganti {WorkspaceId} dengan Workspace ID aktual Anda. Domain yang ada tetap berfungsi penuh.

Panduan pengguna:Pengenalan ucapan non-real-time

Prasyarat

Anda telah mengaktifkan layanan dan mendapatkan API key. Harap konfigurasikan API key sebagai variabel lingkungan alih-alih melakukan hardcoding di kode Anda untuk mencegah risiko keamanan akibat kebocoran kode.

Ketika Anda perlu memberikan akses sementara kepada aplikasi atau pengguna pihak ketiga, atau ketika ingin mengontrol secara ketat operasi berisiko tinggi seperti mengakses atau menghapus data sensitif, kami merekomendasikan penggunaan token otentikasi sementara.Dibandingkan dengan API Key jangka panjang, token otentikasi sementara memiliki periode validitas singkat (60 detik) dan keamanan lebih tinggi, sehingga cocok untuk skenario pemanggilan sementara dan secara efektif mengurangi risiko kebocoran API Key.Penggunaan: Dalam kode Anda, ganti API Key yang awalnya digunakan untuk otentikasi dengan token otentikasi sementara yang diperoleh.

Instal SDK DashScope terbaru.

Mulai

kelas inti (Transcription) mendukung dua pendekatan transkripsi:

Pengiriman asinkron + tunggu sinkron: Kirim tugas dan blokir hingga selesai serta mengembalikan hasil.
Pengiriman asinkron + polling asinkron: Kirim tugas dan polling hasil kapan saja.

Pengiriman asinkron + tunggu sinkron

Panggil metode async_call dari kelas inti (Transcription) dan atur parameter permintaan.
- Layanan transkripsi file memproses tugas yang dikirim melalui API berdasarkan upaya terbaik. Setelah dikirim, tugas memasuki status antrian (PENDING). Waktu antrian bergantung pada panjang antrian dan durasi file serta tidak dapat diperkirakan secara tepat, tetapi biasanya selesai dalam beberapa menit. Setelah pemrosesan dimulai, pengenalan ucapan selesai dengan kecepatan ratusan kali lipat dari kecepatan real-time.
- Setelah setiap tugas selesai, hasil pengenalan dan tautan unduh URL berlaku selama 24 jam. Setelah kedaluwarsa, Anda tidak dapat mengkueri tugas atau mengunduh hasil melalui URL yang sebelumnya diberikan.
Panggil metode wait dari kelas inti (Transcription) untuk menunggu secara sinkron hingga tugas selesai. Status tugas: PENDING, RUNNING, SUCCEEDED, FAILED. Panggilan wait diblokir selama status PENDING atau RUNNING. Ketika tugas mencapai status SUCCEEDED atau FAILED, wait mengembalikan hasilnya. Metode wait mengembalikan TranscriptionResponse.

Klik untuk melihat contoh lengkap

from http import HTTPStatus
from dashscope.audio.asr import Transcription
import json

# Jika Anda belum mengonfigurasi API Key dalam variabel lingkungan,
# hapus komentar baris berikut dan ganti "apiKey" dengan API Key Anda sendiri.
# import dashscope
# dashscope.api_key = "apiKey"
# Tiongkok (Beijing): Ganti {WorkspaceId} dengan Workspace ID aktual Anda. Konfigurasi bervariasi berdasarkan wilayah.
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

task_response = Transcription.async_call(
    model='paraformer-v2',
    file_urls=['{YOUR_AUDIO_URL}'],
    language_hints=['zh', 'en']  # Parameter "language_hints" hanya didukung oleh model paraformer-v2.
)

transcribe_response = Transcription.wait(task=task_response.output.task_id)
if transcribe_response.status_code == HTTPStatus.OK:
    print(json.dumps(transcribe_response.output, indent=4, ensure_ascii=False))
    print('transkripsi selesai!')

Pengiriman asinkron + polling asinkron

Panggil metode async_call dari kelas inti Transcription dan atur parameter permintaan.
- Layanan transkripsi file memproses tugas yang dikirim melalui API berdasarkan upaya terbaik. Setelah dikirim, tugas memasuki status antrian (PENDING). Waktu antrian bergantung pada panjang antrian dan durasi file serta tidak dapat diperkirakan secara tepat, tetapi biasanya selesai dalam beberapa menit. Setelah pemrosesan dimulai, pengenalan ucapan selesai dengan kecepatan ratusan kali lipat dari kecepatan real-time.
- Setelah setiap tugas selesai, hasil pengenalan dan tautan unduh URL berlaku selama 24 jam. Setelah kedaluwarsa, Anda tidak dapat mengkueri tugas atau mengunduh hasil melalui URL yang sebelumnya diberikan.
Polling metode fetch dari kelas inti (Transcription) hingga tugas selesai. Berhenti polling ketika statusnya SUCCEEDED atau FAILED dan proses hasilnya. Metode fetch mengembalikan TranscriptionResponse.

Klik untuk melihat contoh lengkap

from http import HTTPStatus
from dashscope.audio.asr import Transcription
import json

# Jika Anda belum mengonfigurasi API Key dalam variabel lingkungan,
# hapus komentar baris berikut dan ganti "apiKey" dengan API Key Anda sendiri.
# import dashscope
# dashscope.api_key = "apiKey"
# Tiongkok (Beijing): Ganti {WorkspaceId} dengan Workspace ID aktual Anda. Konfigurasi bervariasi berdasarkan wilayah.
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

transcribe_response = Transcription.async_call(
    model='paraformer-v2',
    file_urls=['{YOUR_AUDIO_URL}'],
    language_hints=['zh', 'en']  # Parameter "language_hints" hanya didukung oleh model paraformer-v2.
)

while True:
    if transcribe_response.output.task_status == 'SUCCEEDED' or transcribe_response.output.task_status == 'FAILED':
        break
    transcribe_response = Transcription.fetch(task=transcribe_response.output.task_id)

if transcribe_response.status_code == HTTPStatus.OK:
    print(json.dumps(transcribe_response.output, indent=4, ensure_ascii=False))
    print('transkripsi selesai!')

Parameter permintaan

Teruskan parameter-parameter ini ke metode async_call dari kelas inti (Transcription).

Parameter	Type	Default	Wajib	Deskripsi
model	str		Ya	Nama model untuk transkripsi file audio dan video Paraformer. Model yang didukung.
file_urls	list[str]		Ya	Daftar URL untuk transkripsi file audio dan video. Protokol HTTP dan HTTPS didukung. Satu permintaan hanya mendukung 1 URL.Jika file audio disimpan di Alibaba Cloud OSS, SDK tidak mendukung URL sementara dengan awalan oss://.
vocabulary_id	str		Tidak	ID kosakata kustom. Didukung untuk model seri v2; memerlukan konfigurasi bahasa. Dinonaktifkan secara default. Kosakata Kustom.
channel_id	list[int]	[0]	Tidak	Menentukan indeks trek audio yang akan dikenali dalam file audio multi-trek. Indeks dimulai dari 0. Misalnya, [0] berarti mengenali trek pertama, dan [0, 1] berarti mengenali trek pertama dan kedua secara simultan. Jika parameter ini dihilangkan, hanya trek pertama yang diproses secara default. Setiap trek yang ditentukan ditagih secara independen. Misalnya, meminta [0, 1] untuk satu file menghasilkan dua tagihan terpisah.
disfluency_removal_enabled	bool	False	Tidak	Menyaring kata-kata pengisi. Dinonaktifkan secara default.
timestamp_alignment_enabled	bool	False	Tidak	Mengaktifkan penyelarasan timestamp. Dinonaktifkan secara default.
special_word_filter	str		Tidak	Menentukan kata sensitif yang akan diproses selama pengenalan ucapan dan mendukung pengaturan metode pemrosesan berbeda untuk kata sensitif yang berbeda.Jika parameter ini tidak diberikan, sistem menggunakan logika penyaringan kata sensitif bawaan, dan kata-kata yang cocok dengan daftar kata sensitif Alibaba Cloud Model Studio dalam hasil pengenalan akan diganti dengan `` dengan panjang yang sama.Jika parameter ini diberikan, strategi pemrosesan kata sensitif berikut dapat diterapkan: Ganti dengan ``: Ganti kata sensitif yang cocok dengan `` dengan panjang yang sama. Filter langsung: Hapus sepenuhnya kata sensitif yang cocok dari hasil pengenalan. Nilai parameter ini harus berupa string JSON dengan struktur berikut: `{ "filter_with_signed": { "word_list": ["test"] }, "filter_with_empty": { "word_list": ["start", "happen"] }, "system_reserved_filter": true }` Deskripsi bidang JSON: `filter_with_signed` Tipe: Object. Wajib: Tidak. Deskripsi: Mengonfigurasi daftar kata sensitif yang akan diganti dengan ``. Kata yang cocok dalam hasil pengenalan akan diganti dengan `` dengan panjang yang sama. Contoh: Menggunakan JSON di atas, hasil pengenalan ucapan untuk "Help me test this code" akan menjadi "Help me *** this code". Bidang internal: `word_list`: Array string yang mencantumkan kata sensitif yang akan diganti. `filter_with_empty` Tipe: Object. Wajib: Tidak. Deskripsi: Mengonfigurasi daftar kata sensitif yang akan dihapus (difilter) dari hasil pengenalan. Kata yang cocok akan dihapus sepenuhnya. Contoh: Menggunakan JSON di atas, hasil pengenalan ucapan untuk "The game is about to start, right?" akan menjadi "The game is about to, right?". Bidang internal: `word_list`: Array string yang mencantumkan kata sensitif yang akan dihapus sepenuhnya (difilter). `system_reserved_filter` Tipe: Boolean. Wajib: Tidak. Default: true. Deskripsi: Apakah akan mengaktifkan aturan kata sensitif bawaan sistem. Ketika diatur ke `true`, logika penyaringan kata sensitif bawaan sistem juga diaktifkan, dan kata-kata yang cocok dengan daftar kata sensitif Alibaba Cloud Model Studio dalam hasil pengenalan akan diganti dengan `*` dengan panjang yang sama.
language_hints	list[str]	["zh", "en"]	Tidak	Menentukan kode bahasa dari ucapan yang akan dikenali.Parameter ini hanya berlaku untuk model paraformer-v2.Kode bahasa yang didukung: zh: Bahasa Tiongkok en: Bahasa Inggris ja: Bahasa Jepang yue: Bahasa Kanton ko: Bahasa Korea de: Bahasa Jerman fr: Bahasa Prancis ru: Bahasa Rusia
diarization_enabled	bool	False	Tidak	Diarisasi pembicara otomatis. Dinonaktifkan secara default.Hanya berlaku untuk audio mono. Audio multi-channel tidak mendukung diarisasi pembicara.Ketika fitur ini diaktifkan, hasil pengenalan akan menyertakan bidang `speaker_id` untuk membedakan pembicara yang berbeda. Jika diarisasi pembicara diaktifkan, disarankan agar durasi audio tidak melebihi 2 jam, jika tidak pengenalan mungkin gagal atau timeout. Untuk contoh `speaker_id`, lihat Deskripsi hasil pengenalan.
speaker_count	int		Tidak	Jumlah pembicara referensi. Bilangan bulat dari 2 hingga 100.Berlaku hanya ketika `diarization_enabled` bernilai true.Ditentukan secara otomatis secara default. Mengatur parameter ini membimbing algoritma tetapi tidak menjamin jumlah yang tepat.

Tanggapan

TranscriptionResponse

TranscriptionResponse berisi task_id, task_status, dan hasil eksekusi dalam properti output. Lihat TranscriptionOutput.

Klik untuk melihat contoh struktur TranscriptionResponse

TranscriptionResponse yang dikembalikan oleh async_call tidak menyertakan submit_time atau scheduled_time.

{
    "status_code":200,
    "request_id":"251aceab-a6aa-9fc4-b7f7-0cc6d3e2a9f3",
    "code":null,
    "message":"",
    "output":{
        "task_id":"7d0a58a3-1dbe-4de9-8cff-5f48213128b0",
        "task_status":"PENDING"
    },
    "usage":null
}

Untuk mendapatkan submit_time dan scheduled_time, gunakan metode wait() atau fetch() alih-alih nilai kembalian async_call() secara langsung. TranscriptionResponse yang dikembalikan oleh wait() atau fetch():

{
    "status_code":200,
    "request_id":"251aceab-a6aa-9fc4-b7f7-0cc6d3e2a9f3",
    "code":null,
    "message":"",
    "output":{
        "task_id":"7d0a58a3-1dbe-4de9-8cff-5f48213128b0",
        "task_status":"PENDING",
        "submit_time":"2025-02-13 16:55:08.573",
        "scheduled_time":"2025-02-13 16:55:08.592",
        "task_metrics":{
            "TOTAL":1,
            "SUCCEEDED":0,
            "FAILED":0
        }
    },
    "usage":null
}

Parameter utama:

Parameter	Deskripsi
status_code	Kode status permintaan HTTP.
code	`code` paling luar dapat diabaikan. Dalam `output.results`, bidang `code` adalah kode kesalahan. Gunakan bersama bidang `message` dan rujuk ke Kode kesalahan untuk troubleshooting.
message	`message` paling luar dapat diabaikan. `message` di bawah `output.results` adalah pesan kesalahan. Gunakan bersama bidang `code` dan rujuk ke kode kesalahan untuk troubleshooting.
task_id	ID tugas.
task_status	Status tugas. Keempat status tersebut adalah `PENDING`, `RUNNING`, `SUCCEEDED`, dan `FAILED`. Ketika sebuah tugas berisi beberapa subtugas, jika ada subtugas yang berhasil, status seluruh tugas ditandai sebagai `SUCCEEDED`. Periksa bidang `subtask_status` untuk menentukan hasil setiap subtugas tertentu.
results	Hasil pengenalan dari subtugas.
subtask_status	Status subtugas. Keempat status tersebut adalah `PENDING`, `RUNNING`, `SUCCEEDED`, dan `FAILED`.
file_url	URL file audio yang akan dikenali.
transcription_url	URL yang sesuai dengan hasil pengenalan audio. Hasil pengenalan disimpan sebagai file JSON. Unduh file dari URL di `transcription_url` atau baca isinya melalui permintaan HTTP. Untuk detail konten file JSON, lihat Deskripsi hasil pengenalan.

`TranscriptionOutput`

Objek TranscriptionOutput adalah properti output dari objek TranscriptionResponse, berisi hasil eksekusi tugas.

Klik untuk melihat contoh struktur TranscriptionOutput

Status PENDING
Status RUNNING
Status SUCCEEDED
Status FAILED

{
    "task_id":"f2f7c2fa-0cd9-4bb2-a283-27b26ee4bb67",
    "task_status":"PENDING",
    "submit_time":"2025-02-13 17:59:27.754",
    "scheduled_time":"2025-02-13 17:59:27.789",
    "task_metrics":{
        "TOTAL":1,
        "SUCCEEDED":0,
        "FAILED":0
    }
}

{
    "task_id":"f2f7c2fa-0cd9-4bb2-a283-27b26ee4bb67",
    "task_status":"RUNNING",
    "submit_time":"2025-02-13 17:59:27.754",
    "scheduled_time":"2025-02-13 17:59:27.789",
    "task_metrics":{
        "TOTAL":1,
        "SUCCEEDED":0,
        "FAILED":0
    }
}

{
    "task_id":"f2f7c2fa-0cd9-4bb2-a283-27b26ee4bb67",
    "task_status":"SUCCEEDED",
    "submit_time":"2025-02-13 17:59:27.754",
    "scheduled_time":"2025-02-13 17:59:27.789",
    "end_time":"2025-02-13 17:59:28.828",
    "results":[
        {
            "file_url":"{YOUR_AUDIO_URL}",
            "transcription_url":"https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/20250213/17%3A59/70e737cc-bf8c-418b-b0c8-83fab192a0fa-1.json?Expires=1739527168&OSSAccessKeyId=YOUR_ACCESS_KEY_ID&Signature=YOUR_SIGNATURE",
            "subtask_status":"SUCCEEDED"
        }
    ],
    "task_metrics":{
        "TOTAL":1,
        "SUCCEEDED":1,
        "FAILED":0
    }
}

code adalah kode kesalahan dan message adalah pesan kesalahan. Dikembalikan hanya saat terjadi kesalahan. Lihat Kode kesalahan.

{
    "task_id": "7bac899c-06ec-4a79-8875-xxxxxxxxxxxx",
    "task_status": "FAILED",
    "submit_time": "2024-12-16 16:30:59.170",
    "scheduled_time": "2024-12-16 16:30:59.204",
    "end_time": "2024-12-16 16:31:02.375",
    "results": [
        {
            "file_url": "{YOUR_AUDIO_URL}",
            "code": "InvalidFile.DownloadFailed",
            "message": "File audio tidak dapat diunduh.",
            "subtask_status": "FAILED"
        }
    ],
    "task_metrics": {
        "TOTAL": 1,
        "SUCCEEDED": 0,
        "FAILED": 1
    }
}

Parameter penting:

Parameter	Deskripsi
code	Kode kesalahan. Gunakan bersama bidang `message`. Lihat Kode kesalahan.
message	Pesan kesalahan. Gunakan bersama bidang `code`. Lihat Kode kesalahan.
task_id	ID tugas.
task_status	Status tugas. Keempat status tersebut adalah `PENDING`, `RUNNING`, `SUCCEEDED`, dan `FAILED`. Ketika sebuah tugas berisi beberapa subtugas, jika ada subtugas yang berhasil, status seluruh tugas ditandai sebagai `SUCCEEDED`. Periksa bidang `subtask_status` untuk menentukan hasil setiap subtugas tertentu.
results	Hasil pengenalan dari subtugas.
subtask_status	Status subtugas. Keempat status tersebut adalah `PENDING`, `RUNNING`, `SUCCEEDED`, dan `FAILED`.
file_url	URL file audio yang akan dikenali.
transcription_url	URL yang sesuai dengan hasil pengenalan audio. Hasil pengenalan disimpan dalam file JSON. Unduh file dari `transcription_url` atau baca isinya melalui permintaan HTTP. Untuk detail konten JSON, lihat Deskripsi hasil pengenalan.

Deskripsi hasil pengenalan

Hasil pengenalan disimpan sebagai file JSON.

Klik untuk melihat contoh hasil pengenalan

{
    "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 the Alibaba speech laboratory.",
            "sentences":[
                {
                    "begin_time":100,
                    "end_time":3820,
                    "text":"Hello world, this is the Alibaba speech laboratory.",
                    "sentence_id":1,
                    "speaker_id":0, //Bidang ini hanya ditampilkan ketika diarisasi 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 utama adalah sebagai berikut:

Parameter	Type	Deskripsi
audio_format	string	Format audio dari file sumber.
channels	array[integer]	Informasi indeks trek audio dari file sumber. Mengembalikan [0] untuk audio mono, [0, 1] untuk audio dual-trek, dan seterusnya.
original_sampling_rate	integer	Frekuensi sampling (Hz) audio dalam file sumber.
original_duration	integer	Durasi audio asli (ms) dari file sumber.
channel_id	integer	Indeks trek audio dari hasil transkripsi, dimulai dari 0.
content_duration	integer	Durasi (ms) konten yang diidentifikasi sebagai ucapan dalam trek audio. Layanan model pengenalan ucapan Paraformer hanya mentranskripsikan dan mengukur konten yang diidentifikasi sebagai ucapan dalam trek audio, dan menagih sesuai dengan itu. Konten non-ucapan tidak diukur maupun ditagih. Biasanya, durasi konten ucapan lebih pendek daripada durasi audio asli. Karena penentuan apakah konten ucapan ada dilakukan oleh model AI, mungkin terdapat beberapa penyimpangan dari situasi aktual.
transcript	string	Hasil transkripsi ucapan tingkat paragraf.
sentences	array	Hasil transkripsi ucapan tingkat kalimat.
words	array	Hasil transkripsi ucapan tingkat kata.
begin_time	integer	Timestamp awal (ms).
end_time	integer	Timestamp akhir (ms).
text	string	Hasil transkripsi ucapan.
speaker_id	integer	Indeks pembicara saat ini, dimulai dari 0, digunakan untuk membedakan pembicara yang berbeda. Bidang ini hanya ditampilkan dalam hasil pengenalan ketika diarisasi pembicara diaktifkan.
punctuation	string	Tanda baca yang diprediksi setelah kata (jika ada).

Referensi API

Kelas inti (`Transcription`)

Impor kelas Transcription: from dashscope.audio.asr import Transcription.

Metode anggota Signature metode Deskripsi

Metode anggota	Signature metode	Deskripsi
async_call	`@classmethod def async_call(cls, model: str, file_urls: List[str], phrase_id: str = None, api_key: str = None, workspace: str = None, **kwargs) -> TranscriptionResponse`	Mengirimkan tugas pengenalan ucapan secara asinkron.Metode ini mengembalikan TranscriptionResponse.
wait	`@classmethod def wait(cls, task: Union[str, TranscriptionResponse], api_key: str = None, workspace: str = None, **kwargs) -> TranscriptionResponse`	Memblokir thread saat ini hingga tugas asinkron selesai (status `SUCCEEDED` atau `FAILED`).Metode ini mengembalikan TranscriptionResponse.
fetch	`@classmethod def fetch(cls, task: Union[str, TranscriptionResponse], api_key: str = None, workspace: str = None, **kwargs) -> TranscriptionResponse`	Meminta hasil eksekusi tugas secara asinkron.Metode ini mengembalikan TranscriptionResponse.

async_call

@classmethod
def async_call(cls,
               model: str,
               file_urls: List[str],
               phrase_id: str = None,
               api_key: str = None,
               workspace: str = None,
               **kwargs) -> TranscriptionResponse

Mengirimkan tugas pengenalan ucapan secara asinkron.Metode ini mengembalikan TranscriptionResponse.

wait

@classmethod
def wait(cls,
         task: Union[str, TranscriptionResponse],
         api_key: str = None,
         workspace: str = None,
         **kwargs) -> TranscriptionResponse

Memblokir thread saat ini hingga tugas asinkron selesai (status SUCCEEDED atau FAILED).Metode ini mengembalikan TranscriptionResponse.

fetch

@classmethod
def fetch(cls,
          task: Union[str, TranscriptionResponse],
          api_key: str = None,
          workspace: str = None,
          **kwargs) -> TranscriptionResponse

Meminta hasil eksekusi tugas secara asinkron.Metode ini mengembalikan TranscriptionResponse.

Kode kesalahan

Jika Anda mengalami kesalahan, lihat Kode kesalahan untuk troubleshooting. Jika masalah berlanjut, bergabunglah dengan komunitas developer untuk melaporkan masalah dan berikan Request ID untuk investigasi lebih lanjut. Ketika sebuah tugas berisi beberapa subtugas, selama ada subtugas yang berhasil, status keseluruhan tugas ditandai sebagai SUCCEEDED. Anda perlu memeriksa bidang subtask_status untuk menentukan hasil setiap subtugas. Contoh tanggapan kesalahan:

{
    "task_id": "7bac899c-06ec-4a79-8875-xxxxxxxxxxxx",
    "task_status": "SUCCEEDED",
    "submit_time": "2024-12-16 16:30:59.170",
    "scheduled_time": "2024-12-16 16:30:59.204",
    "end_time": "2024-12-16 16:31:02.375",
    "results": [
        {
            "file_url": "{YOUR_AUDIO_URL}",
            "code": "InvalidFile.DownloadFailed",
            "message": "File audio tidak dapat diunduh.",
            "subtask_status": "FAILED"
        }
    ],
    "task_metrics": {
        "TOTAL": 1,
        "SUCCEEDED": 0,
        "FAILED": 1
    }
}

Contoh lainnya

Jelajahi lebih banyak contoh di GitHub.

FAQ

Fitur

T: Apakah mendukung audio yang diencode Base64?

Tidak. Audio yang diencode Base64 tidak didukung. Hanya audio yang dapat diakses melalui URL publik yang didukung. Aliran biner dan pengenalan file lokal langsung tidak didukung.

T: Bagaimana cara menyediakan file audio sebagai URL publik?

Secara umum, ikuti langkah-langkah berikut (ini memberikan pendekatan umum; spesifiknya bervariasi tergantung produk penyimpanan. Kami merekomendasikan mengunggah audio ke Alibaba Cloud OSS):

1. Pilih metode penyimpanan dan hosting

Sebagai contoh:

Layanan Penyimpanan Objek (direkomendasikan):
- Gunakan layanan penyimpanan objek penyedia cloud (seperti Alibaba Cloud OSS) untuk mengunggah file audio ke bucket dan mengaturnya agar dapat diakses publik.
- Keuntungan: Ketersediaan tinggi, dukungan akselerasi CDN, manajemen mudah.
server web:
- Tempatkan file audio di server web yang mendukung akses HTTP/HTTPS (seperti Nginx atau Apache).
- Keuntungan: Cocok untuk proyek kecil atau pengujian lokal.
Content Delivery Network (CDN):
- Host file audio di CDN dan akses melalui URL yang disediakan CDN.
- Keuntungan: Pengiriman file dipercepat, cocok untuk skenario konkurensi tinggi.

2. Unggah file audio

Unggah file audio berdasarkan metode penyimpanan/hosting yang Anda pilih, misalnya:

Layanan Penyimpanan Objek:
- Login ke konsol penyedia cloud dan buat bucket.
- Unggah file audio dan atur izin file ke "baca publik" atau buat tautan akses sementara.
server web:
- Tempatkan file audio di direktori yang ditentukan server (seperti /var/www/html/audio/).
- Pastikan file dapat diakses melalui HTTP/HTTPS.

3. Hasilkan URL publik

Sebagai contoh:

Layanan Penyimpanan Objek:
- Setelah diunggah, sistem secara otomatis menghasilkan URL akses publik (biasanya dalam format https://<bucket-name>.<region>.aliyuncs.com/<file-name>).
- Jika Anda memerlukan domain yang lebih ramah pengguna, Anda dapat mengikat domain kustom dan mengaktifkan HTTPS.
server web:
- URL akses file biasanya alamat server ditambah jalur file (seperti https://your-domain.com/audio/file.mp3).
CDN:
- Setelah mengonfigurasi akselerasi CDN, gunakan URL yang disediakan CDN (seperti https://cdn.your-domain.com/audio/file.mp3).

4. Verifikasi aksesibilitas URL

Di lingkungan jaringan publik, pastikan URL yang dihasilkan dapat diakses, misalnya:

Buka URL di browser dan periksa apakah file audio dapat diputar.
Gunakan alat (seperti curl atau Postman) untuk memverifikasi apakah URL mengembalikan respons HTTP yang benar (kode status 200).

Saat menggunakan SDK, jika file audio disimpan di Alibaba Cloud OSS, URL sementara dengan awalan oss:// tidak didukung. Saat menggunakan RESTful API, jika file audio disimpan di Alibaba Cloud OSS, URL sementara dengan awalan oss:// didukung:

URL sementara berlaku selama 48 jam dan tidak dapat digunakan setelah kedaluwarsa. Jangan menggunakannya di lingkungan produksi.
API untuk mendapatkan kredensial unggah dibatasi hingga 100 QPS dan tidak mendukung penskalaan keluar. Jangan menggunakannya di lingkungan produksi, skenario konkurensi tinggi, atau skenario uji stres.
Untuk lingkungan produksi, gunakan layanan penyimpanan stabil seperti OSS untuk memastikan ketersediaan file jangka panjang dan menghindari masalah pembatasan laju.

T: Berapa lama waktu yang dibutuhkan untuk mendapatkan hasil pengenalan?

Setelah dikirim, tugas memasuki status antrian (PENDING). Waktu antrian bergantung pada panjang antrian dan durasi file serta tidak dapat diperkirakan secara tepat, tetapi biasanya selesai dalam beberapa menit. Harap tunggu dengan sabar. File audio yang lebih panjang memerlukan waktu pemrosesan lebih lama.

Troubleshooting

Untuk kesalahan kode, lihat Kode kesalahan.

T: Apa yang harus saya lakukan jika hasil pengenalan tidak sinkron dengan pemutaran audio?

Atur parameter permintaan timestamp_alignment_enabled ke true untuk mengaktifkan kalibrasi timestamp, yang menyinkronkan hasil pengenalan dengan pemutaran ucapan.

T: Apa yang harus saya lakukan jika tugas mengembalikan kesalahan InvalidFile.DownloadFailed?

Periksa apakah URL file berisi spasi atau karakter non-ASCII lainnya (seperti karakter Tionghoa). Jika nama file menyertakan spasi (misalnya, my audio recording.mp4), ganti setiap spasi dengan %20 untuk mengencode nama file dalam URL sebelum meneruskannya ke parameter file_urls.

T: Tidak dapat mendapatkan hasil setelah polling terus-menerus?

Ini mungkin karena pembatasan laju. Harap tunggu dengan sabar. Jika Anda memerlukan ekspansi kapasitas, bergabunglah dengan komunitas developer untuk mengajukan permohonan.

T: Mengapa tidak ada hasil pengenalan (tidak dapat mengenali ucapan)?

Periksa apakah audio memenuhi persyaratan (format, frekuensi sampling).
Jika Anda menggunakan model paraformer-v2, periksa apakah pengaturan language_hints sudah benar.
Jika tidak ada yang di atas yang menyelesaikan masalah, Anda dapat menyesuaikan hot word untuk meningkatkan pengenalan kata-kata tertentu.

Pertanyaan lainnya

Kunjungi halaman QA di GitHub.

​Prasyarat

​Mulai

​Pengiriman asinkron + tunggu sinkron

​Pengiriman asinkron + polling asinkron

​Parameter permintaan

​Tanggapan

​TranscriptionResponse

​TranscriptionOutput

​Deskripsi hasil pengenalan

​Referensi API

​Kelas inti (Transcription)

​Kode kesalahan

​Contoh lainnya

​FAQ

​Fitur

​T: Apakah mendukung audio yang diencode Base64?

​T: Bagaimana cara menyediakan file audio sebagai URL publik?

​T: Berapa lama waktu yang dibutuhkan untuk mendapatkan hasil pengenalan?

​Troubleshooting

​T: Apa yang harus saya lakukan jika hasil pengenalan tidak sinkron dengan pemutaran audio?

​T: Apa yang harus saya lakukan jika tugas mengembalikan kesalahan InvalidFile.DownloadFailed?

T: Tidak dapat mendapatkan hasil setelah polling terus-menerus?

T: Mengapa tidak ada hasil pengenalan (tidak dapat mengenali ucapan)?

​Pertanyaan lainnya

Prasyarat

Mulai

Pengiriman asinkron + tunggu sinkron

Pengiriman asinkron + polling asinkron

Parameter permintaan

Tanggapan

TranscriptionResponse

`TranscriptionOutput`

Deskripsi hasil pengenalan

Referensi API

Kelas inti (`Transcription`)

Kode kesalahan

Contoh lainnya

FAQ

Fitur

T: Apakah mendukung audio yang diencode Base64?

T: Bagaimana cara menyediakan file audio sebagai URL publik?

T: Berapa lama waktu yang dibutuhkan untuk mendapatkan hasil pengenalan?

Troubleshooting

T: Apa yang harus saya lakukan jika hasil pengenalan tidak sinkron dengan pemutaran audio?

T: Apa yang harus saya lakukan jika tugas mengembalikan kesalahan InvalidFile.DownloadFailed?

Pertanyaan lainnya