Transkripsikan audio yang telah direkam sebelumnya menjadi teks. Model pengenalan ucapan non-real-time mendukung pengenalan multibahasa, pengenalan konten bernyanyi, pengurangan noise, dan diarizasi pembicara, sehingga sangat cocok untuk transkripsi rapat, analisis panggilan, pembuatan subtitle, serta kasus penggunaan serupa lainnya.
Ikhtisar
Transkripsikan file audio dan video yang telah direkam sebelumnya secara massal dengan mengirimkan tugas asinkron.
-
Mendukung peningkatan konteks, yang memungkinkan Anda memberikan petunjuk kontekstual untuk meningkatkan akurasi pengenalan (hanya untuk fun-asr-flash-2026-06-15).
-
Mendukung hotword khusus untuk meningkatkan akurasi pengenalan istilah spesifik domain melalui daftar kata yang telah ditentukan.
-
Fitur yang dapat dikonfigurasi mencakup diarizasi pembicara, penyaringan kata sensitif, serta timestamp tingkat kalimat dan kata.
-
Secara asinkron mentranskripsikan satu file audio hingga 12 jam dan 2 GB.
-
Menerima laju sampel apa pun dan bekerja dengan format audio dan video umum, termasuk AAC, WAV, dan MP3.
Untuk skenario real-time seperti subtitel langsung, rapat daring, atau asisten suara, gunakan Pengenalan ucapan real-time sebagai gantinya. Untuk panduan memilih model yang tepat, lihat Speech-to-text.
Prasyarat
-
Anda telah Mendapatkan Kunci API dan menyimpan Kunci API tersebut sebagai Variabel lingkungan.
-
Untuk memanggil API melalui SDK DashScope, instal SDK terbaru.
Mendapatkan WorkspaceId Anda: Masuk ke Konsol Model Studio, navigasi ke Workspace Management di sidebar kiri, lalu temukan ID ruang kerja Anda di halaman daftar ruang kerja. ID ruang kerja adalah pengenal string yang digunakan dalam URL Titik akhir API tertentu.
Titik akhir alternatif: Untuk sebagian besar pemanggilan API, Anda dapat menggunakan https://dashscope.aliyuncs.com sebagai URL dasar tanpa memerlukan awalan WorkspaceId. Contohnya: https://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription. Hal ini menyederhanakan pengaturan jika Anda tidak memerlukan routing berbasis Wilayah.
Panduan cepat
Fun-ASR
File audio dan video biasanya berukuran besar, sehingga API transkripsi file bersifat asinkron: kirimkan tugas, polling Titik akhir kueri untuk memeriksa statusnya, lalu ambil hasil pengenalan setelah tugas selesai.
cURL
Saat Anda memanggil API dengan cURL, pertama-tama kirimkan tugas untuk mendapatkan task_id, lalu gunakan ID tersebut untuk menanyakan hasilnya.
Kirimkan tugas
Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah.
# Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
curl -X POST 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-DashScope-Async: enable" \
-d '{
"model": "fun-asr",
"input": {
"file_urls": [
"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav"
]
},
"parameters": {
"channel_id": [0],
"language_hints": ["zh", "en"]
}
}'Dapatkan hasil tugas
Titik akhir kueri ini memiliki batas default 20 QPS dan dapat ditingkatkan hingga 100 QPS. Untuk throughput yang lebih tinggi atau untuk menghindari Pembatasan kecepatan akibat polling, konfigurasikan callback tugas asinkron (lihat Ganti polling dengan callback untuk beban kerja konkurensi tinggi).
Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah.
# Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
curl -X GET 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json"Unduh hasil pengenalan
Setelah tugas berhasil, bidang output.results[].transcription_url yang dikembalikan oleh Titik akhir kueri mengarah ke file JSON yang dapat diunduh publik berisi hasil pengenalan lengkap. URL tersebut berlaku selama 24 jam secara default, jadi segera unduh dan simpan file tersebut.
# Ganti {transcription_url} dengan nilai transcription_url yang dikembalikan oleh Titik akhir kueri
curl -sS '{transcription_url}' -o transcription.json
cat transcription.json | jq .Python
from http import HTTPStatus
from dashscope.audio.asr import Transcription
from urllib import request
import dashscope
import os
import json
# Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah.
# Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
# Kunci API untuk Wilayah Singapura dan Beijing berbeda. Untuk mendapatkan Kunci API, lihat: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan Kunci API Model Studio Anda: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")
task_response = Transcription.async_call(
model='fun-asr',
file_urls=['https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav'],
language_hints=['zh', 'en'] # language_hints adalah parameter opsional yang digunakan untuk menentukan kode bahasa dari audio yang akan dikenali. Untuk rentang nilai, lihat dokumentasi referensi API.
)
transcription_response = Transcription.wait(task=task_response.output.task_id)
if transcription_response.status_code == HTTPStatus.OK:
for transcription in transcription_response.output['results']:
if transcription['subtask_status'] == 'SUCCEEDED':
url = transcription['transcription_url']
result = json.loads(request.urlopen(url).read().decode('utf8'))
print(json.dumps(result, indent=4,
ensure_ascii=False))
else:
print('transkripsi gagal!')
print(transcription)
else:
print('Error: ', transcription_response.output.message)Java
import com.alibaba.dashscope.audio.asr.transcription.*;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.*;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Arrays;
import java.util.List;
public class Main {
public static void main(String[] args) {
// Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah.
// Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
// Buat parameter permintaan transkripsi.
TranscriptionParam param =
TranscriptionParam.builder()
// Kunci API untuk Wilayah Singapura dan Beijing berbeda. Untuk mendapatkan Kunci API, lihat: https://www.alibabacloud.com/help/en/model-studio/get-api-key
// Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan Kunci API Model Studio Anda: .apiKey("sk-xxx")
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model("fun-asr")
// language_hints adalah parameter opsional yang digunakan untuk menentukan kode bahasa dari audio yang akan dikenali. Untuk rentang nilai, lihat dokumentasi referensi API.
.parameter("language_hints", new String[]{"zh", "en"})
.fileUrls(
Arrays.asList(
"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav"))
.build();
try {
Transcription transcription = new Transcription();
// Kirim permintaan transkripsi
TranscriptionResult result = transcription.asyncCall(param);
System.out.println("RequestId: " + result.getRequestId());
// Blokir dan tunggu hingga tugas selesai, lalu dapatkan hasilnya
result = transcription.wait(
TranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId()));
// Dapatkan hasil transkripsi
List<TranscriptionTaskResult> taskResultList = result.getResults();
if (taskResultList != null && taskResultList.size() > 0) {
for (TranscriptionTaskResult taskResult : taskResultList) {
String transcriptionUrl = taskResult.getTranscriptionUrl();
HttpURLConnection connection =
(HttpURLConnection) new URL(transcriptionUrl).openConnection();
connection.setRequestMethod("GET");
connection.connect();
BufferedReader reader =
new BufferedReader(new InputStreamReader(connection.getInputStream()));
Gson gson = new GsonBuilder().setPrettyPrinting().create();
JsonElement jsonResult = gson.fromJson(reader, JsonObject.class);
System.out.println(gson.toJson(jsonResult));
}
}
} catch (Exception e) {
System.out.println("error: " + e);
}
System.exit(0);
}
}Fun-ASR-Flash
fun-asr-flash-2026-06-15 mendukung panggilan sinkron untuk file audio hingga 5 menit. Hasil dapat dikembalikan dalam mode streaming atau non-streaming.
Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah. Kunci API untuk Wilayah Singapura dan Beijing berbeda.
# Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
curl --location --request POST 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header "Content-Type: application/json" \
--header "X-DashScope-SSE: disable" \
--data '{
"model": "fun-asr-flash-2026-06-15",
"input": {
"messages": [
{
"role": "user",
"content": [
{
"type": "input_audio",
"input_audio": {
"data": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav"
}
}
]
}
]
},
"parameters": {
"format": "wav",
"sample_rate": "16000"
}
}'Catatan struktur respons untuk fun-asr-flash: Model fun-asr-flash-2026-06-15 mengembalikan struktur respons yang berbeda dari format standar generasi multimodal DashScope. Teks yang dikenali tersedia di output.output.sentence.text dan output.text dalam respons, bukan di output.choices[].message.content. Saat mengurai respons dari model ini, gunakan jalur output.output untuk mengakses hasil pengenalan.
Contoh cuplikan respons:
{
"output": {
"output": {
"sentence": {
"text": "Hello World, this is Alibaba Speech Lab."
}
},
"text": "Hello World, this is Alibaba Speech Lab."
},
"request_id": "..."
}Qwen3-ASR-Flash-Filetrans
Qwen3-ASR-Flash-Filetrans dirancang khusus untuk transkripsi asinkron file audio. Model ini mendukung rekaman hingga 12 jam, hanya menerima URL file audio yang dapat diakses publik (upload file lokal tidak didukung), dan mengembalikan hasil pengenalan lengkap dalam satu respons setelah tugas selesai.
cURL
Saat Anda memanggil API dengan cURL, pertama-tama kirimkan tugas untuk mendapatkan task_id, lalu gunakan ID tersebut untuk menanyakan hasilnya.
Kirimkan tugas
Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah.
# Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
curl -X POST 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-DashScope-Async: enable" \
-d '{
"model": "qwen3-asr-flash-filetrans",
"input": {
"file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"
},
"parameters": {
"channel_id":[
0
],
"enable_itn": false,
"enable_words": true
}
}'Dapatkan hasil tugas
Titik akhir kueri ini memiliki batas default 20 QPS dan dapat ditingkatkan hingga 100 QPS. Untuk throughput yang lebih tinggi atau untuk menghindari Pembatasan kecepatan akibat polling, konfigurasikan callback tugas asinkron (lihat Ganti polling dengan callback untuk beban kerja konkurensi tinggi).
Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah.
# Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
curl -X GET 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json"Unduh hasil pengenalan
Setelah tugas berhasil, bidang output.result.transcription_url yang dikembalikan oleh Titik akhir kueri mengarah ke file JSON yang dapat diunduh publik berisi hasil pengenalan lengkap. URL tersebut berlaku selama 24 jam secara default, jadi segera unduh dan simpan file tersebut.
# Ganti {transcription_url} dengan nilai transcription_url yang dikembalikan oleh Titik akhir kueri
curl -sS '{transcription_url}' -o transcription.json
cat transcription.json | jq .Contoh lengkap
Java
import com.google.gson.Gson;
import com.google.gson.annotations.SerializedName;
import okhttp3.*;
import java.io.IOException;
import java.util.concurrent.TimeUnit;
public class Main {
// Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah.
// Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
private static final String API_URL_SUBMIT = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription";
// Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah.
// Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
private static final String API_URL_QUERY = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/";
private static final Gson gson = new Gson();
public static void main(String[] args) {
// Kunci API untuk Wilayah Singapura dan Beijing berbeda. Untuk mendapatkan Kunci API, lihat: https://www.alibabacloud.com/help/en/model-studio/get-api-key
// Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan Kunci API Model Studio Anda: String apiKey = "sk-xxx"
String apiKey = System.getenv("DASHSCOPE_API_KEY");
OkHttpClient client = new OkHttpClient();
// 1. Kirimkan tugas
/*String payloadJson = """
{
"model": "qwen3-asr-flash-filetrans",
"input": {
"file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"
},
"parameters": {
"channel_id": [0],
"enable_itn": false,
"language": "zh"
}
}
""";*/
String payloadJson = """
{
"model": "qwen3-asr-flash-filetrans",
"input": {
"file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"
},
"parameters": {
"channel_id": [0],
"enable_itn": false,
"enable_words": true
}
}
""";
RequestBody body = RequestBody.create(payloadJson, MediaType.get("application/json; charset=utf-8"));
Request submitRequest = new Request.Builder()
.url(API_URL_SUBMIT)
.addHeader("Authorization", "Bearer " + apiKey)
.addHeader("Content-Type", "application/json")
.addHeader("X-DashScope-Async", "enable")
.post(body)
.build();
String taskId = null;
try (Response response = client.newCall(submitRequest).execute()) {
if (response.isSuccessful() && response.body() != null) {
String respBody = response.body().string();
ApiResponse apiResp = gson.fromJson(respBody, ApiResponse.class);
if (apiResp.output != null) {
taskId = apiResp.output.taskId;
System.out.println("Tugas dikirim, task_id: " + taskId);
} else {
System.out.println("Konten respons pengiriman: " + respBody);
return;
}
} else {
System.out.println("Pengiriman tugas gagal! Kode HTTP: " + response.code());
if (response.body() != null) {
System.out.println(response.body().string());
}
return;
}
} catch (IOException e) {
e.printStackTrace();
return;
}
// 2. Poll status tugas
boolean finished = false;
while (!finished) {
try {
TimeUnit.SECONDS.sleep(2); // Tunggu 2 detik sebelum menanyakan lagi
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
return;
}
String queryUrl = API_URL_QUERY + taskId;
Request queryRequest = new Request.Builder()
.url(queryUrl)
.addHeader("Authorization", "Bearer " + apiKey)
.addHeader("X-DashScope-Async", "enable")
.addHeader("Content-Type", "application/json")
.get()
.build();
try (Response response = client.newCall(queryRequest).execute()) {
if (response.body() != null) {
String queryResponse = response.body().string();
ApiResponse apiResp = gson.fromJson(queryResponse, ApiResponse.class);
if (apiResp.output != null && apiResp.output.taskStatus != null) {
String status = apiResp.output.taskStatus;
System.out.println("Status tugas saat ini: " + status);
if ("SUCCEEDED".equalsIgnoreCase(status)
|| "FAILED".equalsIgnoreCase(status)
|| "UNKNOWN".equalsIgnoreCase(status)) {
finished = true;
System.out.println("Tugas selesai. Hasil akhir: ");
System.out.println(queryResponse);
}
} else {
System.out.println("Konten respons kueri: " + queryResponse);
}
}
} catch (IOException e) {
e.printStackTrace();
return;
}
}
}
static class ApiResponse {
@SerializedName("request_id")
String requestId;
Output output;
}
static class Output {
@SerializedName("task_id")
String taskId;
@SerializedName("task_status")
String taskStatus;
}
}Python
import os
import time
import requests
import json
# Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah.
# Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
API_URL_SUBMIT = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription"
# Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah.
# Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
API_URL_QUERY_BASE = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/"
def main():
# Kunci API untuk Wilayah Singapura dan Beijing berbeda. Untuk mendapatkan Kunci API, lihat: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan Kunci API Model Studio Anda: api_key = "sk-xxx"
api_key = os.getenv("DASHSCOPE_API_KEY")
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
"X-DashScope-Async": "enable"
}
# 1. Kirimkan tugas
payload = {
"model": "qwen3-asr-flash-filetrans",
"input": {
"file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"
},
"parameters": {
"channel_id": [0],
# "language": "zh",
"enable_itn": False,
"enable_words": True
}
}
print("Mengirim tugas transkripsi ASR...")
try:
submit_resp = requests.post(API_URL_SUBMIT, headers=headers, data=json.dumps(payload))
except requests.RequestException as e:
print(f"Permintaan pengiriman tugas gagal: {e}")
return
if submit_resp.status_code != 200:
print(f"Pengiriman tugas gagal! Kode HTTP: {submit_resp.status_code}")
print(submit_resp.text)
return
resp_data = submit_resp.json()
output = resp_data.get("output")
if not output or "task_id" not in output:
print("Konten respons pengiriman tidak sesuai:", resp_data)
return
task_id = output["task_id"]
print(f"Tugas dikirim, task_id: {task_id}")
# 2. Poll status tugas
finished = False
while not finished:
time.sleep(2) # Tunggu 2 detik sebelum menanyakan lagi
query_url = API_URL_QUERY_BASE + task_id
try:
query_resp = requests.get(query_url, headers=headers)
except requests.RequestException as e:
print(f"Permintaan kueri tugas gagal: {e}")
return
if query_resp.status_code != 200:
print(f"Kueri tugas gagal! Kode HTTP: {query_resp.status_code}")
print(query_resp.text)
return
query_data = query_resp.json()
output = query_data.get("output")
if output and "task_status" in output:
status = output["task_status"]
print(f"Status tugas saat ini: {status}")
if status.upper() in ("SUCCEEDED", "FAILED", "UNKNOWN"):
finished = True
print("Tugas selesai. Hasil akhir:")
print(json.dumps(query_data, indent=2, ensure_ascii=False))
else:
print("Konten respons kueri:", query_data)
if __name__ == "__main__":
main()Java SDK
import com.alibaba.dashscope.audio.qwen_asr.*;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import com.google.gson.JsonObject;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.ArrayList;
import java.util.HashMap;
public class Main {
public static void main(String[] args) {
// Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah.
// Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
QwenTranscriptionParam param =
QwenTranscriptionParam.builder()
// Kunci API untuk Wilayah Singapura dan Beijing berbeda. Untuk mendapatkan Kunci API, lihat: https://www.alibabacloud.com/help/en/model-studio/get-api-key
// Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan Kunci API Model Studio Anda: .apiKey("sk-xxx")
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model("qwen3-asr-flash-filetrans")
.fileUrl("https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/rich_text_example_1.wav")
//.parameter("language", "zh")
//.parameter("channel_id", new ArrayList<String>(){{add("0");add("1");}})
.parameter("enable_itn", false)
.parameter("enable_words", true)
.build();
try {
QwenTranscription transcription = new QwenTranscription();
// Kirimkan tugas
QwenTranscriptionResult result = transcription.asyncCall(param);
System.out.println("hasil membuat tugas: " + result);
// Tanyakan status tugas
result = transcription.fetch(QwenTranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId()));
System.out.println("status tugas: " + result);
// Tunggu hingga tugas selesai
result =
transcription.wait(
QwenTranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId()));
System.out.println("hasil tugas: " + result);
// Dapatkan hasil pengenalan ucapan
QwenTranscriptionTaskResult taskResult = result.getResult();
if (taskResult != null) {
// Dapatkan URL hasil pengenalan
String transcriptionUrl = taskResult.getTranscriptionUrl();
// Ambil konten di URL tersebut
HttpURLConnection connection =
(HttpURLConnection) new URL(transcriptionUrl).openConnection();
connection.setRequestMethod("GET");
connection.connect();
BufferedReader reader =
new BufferedReader(new InputStreamReader(connection.getInputStream()));
// Cetak hasil JSON dengan format rapi
Gson gson = new GsonBuilder().setPrettyPrinting().create();
System.out.println(gson.toJson(gson.fromJson(reader, JsonObject.class)));
}
} catch (Exception e) {
System.out.println("error: " + e);
}
}
}SDK Python
import json
import os
import sys
from http import HTTPStatus
import dashscope
from dashscope.audio.qwen_asr import QwenTranscription
from dashscope.api_entities.dashscope_response import TranscriptionResponse
# jalankan skrip transkripsi
if __name__ == '__main__':
# Kunci API untuk Wilayah Singapura dan Beijing berbeda. Untuk mendapatkan Kunci API, lihat: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan Kunci API Model Studio Anda: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")
# Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah.
# Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
task_response = QwenTranscription.async_call(
model='qwen3-asr-flash-filetrans',
file_url='https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/rich_text_example_1.wav',
#language="",
enable_itn=False,
enable_words=True
)
print(f'task_response: {task_response}')
print(task_response.output.task_id)
query_response = QwenTranscription.fetch(task=task_response.output.task_id)
print(f'query_response: {query_response}')
task_result = QwenTranscription.wait(task=task_response.output.task_id)
print(f'task_result: {task_result}')Qwen3-ASR-Flash
Qwen3-ASR-Flash mendukung rekaman hingga 5 menit. Model ini menerima URL file audio yang dapat diakses publik atau upload file lokal, dan dapat mengalirkan hasil pengenalan kembali kepada Anda.
Input: URL file audio
SDK Python
import os
import dashscope
# Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah.
# Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
messages = [
{"role": "user", "content": [{"audio": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"}]}
]
response = dashscope.MultiModalConversation.call(
# Kunci API untuk Wilayah Singapura/AS dan Beijing berbeda. Untuk mendapatkan Kunci API, lihat: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan Kunci API Model Studio Anda: api_key = "sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
# Untuk menggunakan model di Wilayah AS, tambahkan akhiran "-us" pada nama model, contohnya qwen3-asr-flash-us
model="qwen3-asr-flash",
messages=messages,
result_format="message",
asr_options={
#"language": "zh", # Opsional. Jika bahasa audio diketahui, gunakan parameter ini untuk menentukan bahasa guna meningkatkan akurasi pengenalan.
"enable_itn":False
}
)
print(response)Java SDK
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
public class Main {
public static void simpleMultiModalConversationCall()
throws ApiException, NoApiKeyException, UploadFileException {
MultiModalConversation conv = new MultiModalConversation();
MultiModalMessage userMessage = MultiModalMessage.builder()
.role(Role.USER.getValue())
.content(Arrays.asList(
Collections.singletonMap("audio", "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3")))
.build();
Map<String, Object> asrOptions = new HashMap<>();
asrOptions.put("enable_itn", false);
// asrOptions.put("language", "zh"); // Opsional. Jika bahasa audio diketahui, gunakan parameter ini untuk menentukan bahasa guna meningkatkan akurasi pengenalan.
MultiModalConversationParam param = MultiModalConversationParam.builder()
// Kunci API untuk Wilayah Singapura/AS dan Beijing berbeda. Untuk mendapatkan Kunci API, lihat: https://www.alibabacloud.com/help/en/model-studio/get-api-key
// Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan Kunci API Model Studio Anda: .apiKey("sk-xxx")
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
// Untuk menggunakan model di Wilayah AS, tambahkan akhiran "-us" pada nama model, contohnya qwen3-asr-flash-us
.model("qwen3-asr-flash")
.message(userMessage)
.parameter("asr_options", asrOptions)
.build();
MultiModalConversationResult result = conv.call(param);
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
// Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah.
// Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
simpleMultiModalConversationCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}cURL
Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah.
# Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
curl -X POST "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3-asr-flash",
"input": {
"messages": [
{
"content": [
{
"text": ""
}
],
"role": "system"
},
{
"content": [
{
"audio": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"
}
],
"role": "user"
}
]
},
"parameters": {
"asr_options": {
"enable_itn": false
}
}
}'Input: File audio terenkode Base64
Kirimkan audio terenkripsi Base64 sebagai URL data dalam bentuk data:<mediatype>;base64,<data>.
-
<mediatype>: jenis MIME.Nilainya tergantung pada format audio. Contohnya:
-
WAV:
audio/wav -
MP3:
audio/mpeg
-
-
<data>: data audio yang dienkripsi sebagai string Base64.Encoding Base64 meningkatkan ukuran muatan, jadi pastikan file sumber cukup kecil sehingga hasil enkoding tidak melebihi batas input 10 MB.
-
Contoh:
data:audio/wav;base64,SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4LjI5LjEwMAAAAAAAAAAAAAAA//PAxABQ/BXRbMPe4IQAhl9
SDK Python
Contoh ini menggunakan file audio berikut: welcome.mp3.
import base64
import dashscope
import os
import pathlib
# Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah.
# Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
# Ganti dengan jalur aktual ke file audio Anda
file_path = "welcome.mp3"
# Ganti dengan jenis MIME aktual file audio Anda
audio_mime_type = "audio/mpeg"
file_path_obj = pathlib.Path(file_path)
if not file_path_obj.exists():
raise FileNotFoundError(f"File audio tidak ditemukan: {file_path}")
base64_str = base64.b64encode(file_path_obj.read_bytes()).decode()
data_uri = f"data:{audio_mime_type};base64,{base64_str}"
messages = [
{"role": "user", "content": [{"audio": data_uri}]}
]
response = dashscope.MultiModalConversation.call(
# Kunci API untuk Wilayah Singapura/AS dan Beijing berbeda. Untuk mendapatkan Kunci API, lihat: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan Kunci API Model Studio Anda: api_key = "sk-xxx",
api_key=os.getenv("DASHSCOPE_API_KEY"),
# Untuk menggunakan model di Wilayah AS, tambahkan akhiran "-us" pada nama model, contohnya qwen3-asr-flash-us
model="qwen3-asr-flash",
messages=messages,
result_format="message",
asr_options={
# "language": "zh", # Opsional. Jika bahasa audio diketahui, gunakan parameter ini untuk menentukan bahasa guna meningkatkan akurasi pengenalan.
"enable_itn":False
}
)
print(response)SDK Java
Contoh ini menggunakan file audio berikut: welcome.mp3.
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.*;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
public class Main {
// Ganti dengan jalur aktual ke file audio Anda
private static final String AUDIO_FILE = "welcome.mp3";
// Ganti dengan jenis MIME aktual file audio Anda
private static final String AUDIO_MIME_TYPE = "audio/mpeg";
public static void simpleMultiModalConversationCall()
throws ApiException, NoApiKeyException, UploadFileException, IOException {
MultiModalConversation conv = new MultiModalConversation();
MultiModalMessage userMessage = MultiModalMessage.builder()
.role(Role.USER.getValue())
.content(Arrays.asList(
Collections.singletonMap("audio", toDataUrl())))
.build();
Map<String, Object> asrOptions = new HashMap<>();
asrOptions.put("enable_itn", false);
// asrOptions.put("language", "zh"); // Opsional. Jika bahasa audio diketahui, gunakan parameter ini untuk menentukan bahasa guna meningkatkan akurasi pengenalan.
MultiModalConversationParam param = MultiModalConversationParam.builder()
// Kunci API untuk Wilayah Singapura/AS dan Beijing berbeda. Untuk mendapatkan Kunci API, lihat: https://www.alibabacloud.com/help/en/model-studio/get-api-key
// Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan Kunci API Model Studio Anda: .apiKey("sk-xxx")
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
// Untuk menggunakan model di Wilayah AS, tambahkan akhiran "-us" pada nama model, contohnya qwen3-asr-flash-us
.model("qwen3-asr-flash")
.message(userMessage)
.parameter("asr_options", asrOptions)
.build();
MultiModalConversationResult result = conv.call(param);
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
// Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah.
// Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
simpleMultiModalConversationCall();
} catch (ApiException | NoApiKeyException | UploadFileException | IOException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
// Hasilkan URI data
public static String toDataUrl() throws IOException {
byte[] bytes = Files.readAllBytes(Paths.get(AUDIO_FILE));
String encoded = Base64.getEncoder().encodeToString(bytes);
return "data:" + AUDIO_MIME_TYPE + ";base64," + encoded;
}
}Input: jalur mutlak ke file audio lokal
Saat Anda memproses file audio lokal dengan SDK DashScope, berikan jalur file sebagai input. Bangun jalur tersebut sesuai dengan SDK dan sistem operasi Anda, seperti yang ditunjukkan pada tabel berikut.
|
Sistem operasi |
SDK |
Format jalur file |
Contoh |
|
Linux atau macOS |
SDK Python |
file://{jalur_mutlak_ke_file} |
file:///home/audio/test.wav |
|
SDK Java |
|||
|
Windows |
SDK Python |
file://{jalur_mutlak_ke_file} |
file://D:/audio/test.wav |
|
SDK Java |
file:///{jalur_mutlak_ke_file} |
file:///D:/audio/test.wav |
Pemanggilan file lokal dibatasi hingga 100 QPS dan batas ini tidak dapat ditingkatkan, sehingga tidak cocok untuk beban kerja produksi, konkurensi tinggi, atau pengujian beban. Untuk konkurensi yang lebih tinggi, unggah file ke OSS dan panggil API dengan URL-nya.
SDK Python
Contoh ini menggunakan file audio berikut: welcome.mp3.
import os
import dashscope
# Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah.
# Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
# Ganti ABSOLUTE_PATH/welcome.mp3 dengan jalur mutlak ke file audio lokal Anda
audio_file_path = "file://ABSOLUTE_PATH/welcome.mp3"
messages = [
{"role": "user", "content": [{"audio": audio_file_path}]}
]
response = dashscope.MultiModalConversation.call(
# Kunci API untuk Wilayah Singapura/AS dan Beijing berbeda. Untuk mendapatkan Kunci API, lihat: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan Kunci API Model Studio Anda: api_key = "sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
# Untuk menggunakan model di Wilayah AS, tambahkan akhiran "-us" pada nama model, contohnya qwen3-asr-flash-us
model="qwen3-asr-flash",
messages=messages,
result_format="message",
asr_options={
# "language": "zh", # Opsional. Jika bahasa audio diketahui, gunakan parameter ini untuk menentukan bahasa guna meningkatkan akurasi pengenalan.
"enable_itn":False
}
)
print(response)SDK Java
Contoh ini menggunakan file audio berikut: welcome.mp3.
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
public class Main {
public static void simpleMultiModalConversationCall()
throws ApiException, NoApiKeyException, UploadFileException {
// Ganti ABSOLUTE_PATH/welcome.mp3 dengan jalur mutlak ke file lokal Anda
String localFilePath = "file://ABSOLUTE_PATH/welcome.mp3";
MultiModalConversation conv = new MultiModalConversation();
MultiModalMessage userMessage = MultiModalMessage.builder()
.role(Role.USER.getValue())
.content(Arrays.asList(
Collections.singletonMap("audio", localFilePath)))
.build();
Map<String, Object> asrOptions = new HashMap<>();
asrOptions.put("enable_itn", false);
// asrOptions.put("language", "zh"); // Opsional. Jika bahasa audio diketahui, gunakan parameter ini untuk menentukan bahasa guna meningkatkan akurasi pengenalan.
MultiModalConversationParam param = MultiModalConversationParam.builder()
// Kunci API untuk Wilayah Singapura dan Beijing berbeda. Untuk mendapatkan Kunci API, lihat: https://www.alibabacloud.com/help/en/model-studio/get-api-key
// Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan Kunci API Model Studio Anda: .apiKey("sk-xxx")
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
// Untuk menggunakan model di Wilayah AS, tambahkan akhiran "-us" pada nama model, contohnya qwen3-asr-flash-us
.model("qwen3-asr-flash")
.message(userMessage)
.parameter("asr_options", asrOptions)
.build();
MultiModalConversationResult result = conv.call(param);
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
// Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah.
// Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
simpleMultiModalConversationCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}Keluaran streaming
Model menghasilkan hasil antara langkah demi langkah, dan hasil akhir disusun dari hasil-hasil tersebut. Panggilan non-streaming menunggu hasil lengkap dan mengembalikannya dalam satu respons, sedangkan panggilan streaming mengembalikan hasil saat dihasilkan, yang secara signifikan mengurangi waktu hingga token pertama. Pilih parameter streaming yang sesuai dengan metode panggilan Anda:
-
SDK Python DashScope: atur
streamke true. -
SDK Java DashScope: panggil metode
streamCall. -
HTTP DashScope: atur header
X-DashScope-SSEkeenable.
SDK Python
import os
import dashscope
# Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah.
# Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
messages = [
{"role": "user", "content": [{"audio": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"}]}
]
response = dashscope.MultiModalConversation.call(
# Kunci API untuk Wilayah Singapura/AS dan Beijing berbeda. Untuk mendapatkan Kunci API, lihat: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan Kunci API Model Studio Anda: api_key = "sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
# Untuk menggunakan model di Wilayah AS, tambahkan akhiran "-us" pada nama model, contohnya qwen3-asr-flash-us
model="qwen3-asr-flash",
messages=messages,
result_format="message",
asr_options={
# "language": "zh", # Opsional. Jika bahasa audio diketahui, gunakan parameter ini untuk menentukan bahasa guna meningkatkan akurasi pengenalan.
"enable_itn":False
},
stream=True
)
for response in response:
try:
print(response["output"]["choices"][0]["message"].content[0]["text"])
except:
passSDK Java
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import io.reactivex.Flowable;
public class Main {
public static void simpleMultiModalConversationCall()
throws ApiException, NoApiKeyException, UploadFileException {
MultiModalConversation conv = new MultiModalConversation();
MultiModalMessage userMessage = MultiModalMessage.builder()
.role(Role.USER.getValue())
.content(Arrays.asList(
Collections.singletonMap("audio", "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3")))
.build();
Map<String, Object> asrOptions = new HashMap<>();
asrOptions.put("enable_itn", false);
// asrOptions.put("language", "zh"); // Opsional. Jika bahasa audio diketahui, gunakan parameter ini untuk menentukan bahasa guna meningkatkan akurasi pengenalan.
MultiModalConversationParam param = MultiModalConversationParam.builder()
// Kunci API untuk Wilayah Singapura dan Beijing berbeda. Untuk mendapatkan Kunci API, lihat: https://www.alibabacloud.com/help/en/model-studio/get-api-key
// Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan Kunci API Model Studio Anda: .apiKey("sk-xxx")
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
// Untuk menggunakan model di Wilayah AS, tambahkan akhiran "-us" pada nama model, contohnya qwen3-asr-flash-us
.model("qwen3-asr-flash")
.message(userMessage)
.parameter("asr_options", asrOptions)
.build();
Flowable<MultiModalConversationResult> resultFlowable = conv.streamCall(param);
resultFlowable.blockingForEach(item -> {
try {
System.out.println(item.getOutput().getChoices().get(0).getMessage().getContent().get(0).get("text"));
} catch (Exception e){
System.exit(0);
}
});
}
public static void main(String[] args) {
try {
// Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah.
// Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
simpleMultiModalConversationCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}cURL
Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah.
# Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
curl -X POST "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-DashScope-SSE: enable" \
-d '{
"model": "qwen3-asr-flash",
"input": {
"messages": [
{
"content": [
{
"text": ""
}
],
"role": "system"
},
{
"content": [
{
"audio": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"
}
],
"role": "user"
}
]
},
"parameters": {
"incremental_output": true,
"asr_options": {
"enable_itn": false
}
}
}'Paraformer
Kode contoh untuk Paraformer mirip dengan panggilan asinkron Fun-ASR. Ganti nama model dengan nama model Paraformer.
Fitur lanjutan
Gunakan API kompatibel OpenAI
Mode kompatibel OpenAI tidak tersedia di Wilayah AS.
Hanya seri model Qwen3-ASR-Flash yang mendukung panggilan kompatibel OpenAI. Mode ini hanya menerima URL file audio yang dapat diakses publik; jalur mutlak ke file audio lokal tidak diterima.
SDK Python OpenAI harus versi 1.52.0 atau lebih baru, dan SDK Node.js harus versi 4.68.0 atau lebih baru. Untuk menginstal atau memperbarui:
# Python
pip install -U "openai>=1.52.0"
# Node.js
npm install openai@^4.68.0asr_options bukan parameter standar OpenAI. Saat menggunakan SDK Python OpenAI, lewatkan melalui extra_body. Saat menggunakan Node.js OpenAI SDK (v4.x), lewatkan asr_options langsung dalam objek badan permintaan alih-alih membungkusnya dalam extra_body, karena SDK Node.js tidak mendukung bidang extra_body.
Masukan: URL file audio
SDK Python
from openai import OpenAI
import os
try:
client = OpenAI(
# Kunci API untuk Wilayah Singapura/AS dan Beijing berbeda. Untuk mendapatkan Kunci API, lihat: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan Kunci API Model Studio Anda: api_key = "sk-xxx",
api_key=os.getenv("DASHSCOPE_API_KEY"),
# Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah.
# Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
stream_enabled = False # Apakah akan mengaktifkan keluaran streaming
completion = client.chat.completions.create(
model="qwen3-asr-flash",
messages=[
{
"content": [
{
"type": "input_audio",
"input_audio": {
"data": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"
}
}
],
"role": "user"
}
],
stream=stream_enabled,
# Saat stream adalah False, stream_options tidak dapat diatur
# stream_options={"include_usage": True},
extra_body={
"asr_options": {
# "language": "zh",
"enable_itn": False
}
}
)
if stream_enabled:
full_content = ""
print("Keluaran streaming:")
for chunk in completion:
# Saat stream_options.include_usage adalah True, bidang choices dari chunk terakhir adalah daftar kosong dan harus dilewati (Anda bisa mendapatkan penggunaan token melalui chunk.usage)
print(chunk)
if chunk.choices and chunk.choices[0].delta.content:
full_content += chunk.choices[0].delta.content
print(f"Konten lengkap: {full_content}")
else:
print(f"Keluaran non-streaming: {completion.choices[0].message.content}")
except Exception as e:
print(f"Error: {e}")SDK Node.js
// Persiapan sebelum menjalankan:
// Umum untuk Windows/Mac/Linux:
// 1. Pastikan Node.js terinstal (versi >= 14 direkomendasikan)
// 2. Jalankan perintah berikut untuk menginstal dependensi yang diperlukan: npm install openai
import OpenAI from "openai";
const client = new OpenAI({
// Kunci API untuk Wilayah Singapura/AS dan Beijing berbeda. Untuk mendapatkan Kunci API, lihat: https://www.alibabacloud.com/help/en/model-studio/get-api-key
// Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan Kunci API Model Studio Anda: apiKey: "sk-xxx",
apiKey: process.env.DASHSCOPE_API_KEY,
// Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah.
// Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
});
async function main() {
try {
const streamEnabled = false; // Apakah akan mengaktifkan keluaran streaming
const completion = await client.chat.completions.create({
model: "qwen3-asr-flash",
messages: [
{
role: "user",
content: [
{
type: "input_audio",
input_audio: {
data: "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"
}
}
]
}
],
stream: streamEnabled,
// Saat stream adalah False, stream_options tidak dapat diatur
// stream_options: {
// "include_usage": true
// },
asr_options: {
// language: "zh",
enable_itn: false
}
});
if (streamEnabled) {
let fullContent = "";
console.log("Keluaran streaming:");
for await (const chunk of completion) {
console.log(JSON.stringify(chunk));
if (chunk.choices && chunk.choices.length > 0) {
const delta = chunk.choices[0].delta;
if (delta && delta.content) {
fullContent += delta.content;
}
}
}
console.log(`Konten lengkap: ${fullContent}`);
} else {
console.log(`Keluaran non-streaming: ${completion.choices[0].message.content}`);
}
} catch (err) {
console.error(`Error: ${err}`);
}
}
main();cURL
Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah.
# Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
curl -X POST 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3-asr-flash",
"messages": [
{
"content": [
{
"type": "input_audio",
"input_audio": {
"data": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"
}
}
],
"role": "user"
}
],
"stream":false,
"asr_options": {
"enable_itn": false
}
}'Masukan: file audio yang dienkode Base64
Anda juga dapat mengirimkan audio terenkripsi Base64 sebagai URL data, dalam format data:<mediatype>;base64,<data>.
-
<mediatype>: Jenis MIME.Nilainya bervariasi tergantung format audio. Contohnya:
-
WAV:
audio/wav -
MP3:
audio/mpeg
-
-
<data>: String terenkripsi Base64 dari data audio.Pengenkripsian Base64 memperbesar ukuran muatan. Pastikan file sumber cukup kecil agar data terenkripsi tetap berada dalam batas input 10 MB.
-
Contoh:
data:audio/wav;base64,SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4LjI5LjEwMAAAAAAAAAAAAAAA//PAxABQ/BXRbMPe4IQAhl9
SDK Python
Contoh ini menggunakan file audio berikut: welcome.mp3.
import base64
from openai import OpenAI
import os
import pathlib
try:
# Ganti dengan jalur sebenarnya ke file audio Anda
file_path = "welcome.mp3"
# Ganti dengan jenis MIME sebenarnya dari file audio Anda
audio_mime_type = "audio/mpeg"
file_path_obj = pathlib.Path(file_path)
if not file_path_obj.exists():
raise FileNotFoundError(f"Audio file not found: {file_path}")
base64_str = base64.b64encode(file_path_obj.read_bytes()).decode()
data_uri = f"data:{audio_mime_type};base64,{base64_str}"
client = OpenAI(
# Kunci API untuk wilayah Singapura/AS dan Beijing berbeda. Untuk mendapatkan Kunci API, lihat: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# Jika variabel lingkungan tidak dikonfigurasi, ganti baris berikut dengan Kunci API Model Studio Anda: api_key = "sk-xxx",
api_key=os.getenv("DASHSCOPE_API_KEY"),
# Konfigurasi berikut adalah untuk wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja Anda yang sebenarnya. Konfigurasi bervariasi menurut wilayah.
# Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
stream_enabled = False # Apakah akan mengaktifkan keluaran streaming
completion = client.chat.completions.create(
model="qwen3-asr-flash",
messages=[
{
"content": [
{
"type": "input_audio",
"input_audio": {
"data": data_uri
}
}
],
"role": "user"
}
],
stream=stream_enabled,
# Ketika stream adalah False, stream_options tidak dapat diatur
# stream_options={"include_usage": True},
extra_body={
"asr_options": {
# "language": "zh",
"enable_itn": False
}
}
)
if stream_enabled:
full_content = ""
print("Streaming output:")
for chunk in completion:
# Ketika stream_options.include_usage adalah True, bidang pilihan dari chunk terakhir adalah daftar kosong dan harus dilewati (Anda bisa mendapatkan penggunaan token melalui chunk.usage)
print(chunk)
if chunk.choices and chunk.choices[0].delta.content:
full_content += chunk.choices[0].delta.content
print(f"Full content: {full_content}")
else:
print(f"Non-streaming output: {completion.choices[0].message.content}")
except Exception as e:
print(f"Error: {e}")SDK Node.js
Contoh ini menggunakan file audio berikut: welcome.mp3.
// Persiapan sebelum menjalankan:
// Umum untuk Windows/Mac/Linux:
// 1. Pastikan Node.js terinstal (versi >= 14 direkomendasikan)
// 2. Jalankan perintah berikut untuk menginstal dependensi yang diperlukan: npm install openai
import OpenAI from "openai";
import { readFileSync } from 'fs';
const client = new OpenAI({
// Kunci API untuk Wilayah Singapura/AS dan Beijing berbeda. Untuk mendapatkan Kunci API, lihat: https://www.alibabacloud.com/help/en/model-studio/get-api-key
// Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan Kunci API Model Studio Anda: apiKey: "sk-xxx",
apiKey: process.env.DASHSCOPE_API_KEY,
// Konfigurasi berikut berlaku untuk Wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi tergantung wilayah.
// Alternatif: gunakan "https://dashscope.aliyuncs.com" tanpa awalan WorkspaceId
baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
});
const encodeAudioFile = (audioFilePath) => {
const audioFile = readFileSync(audioFilePath);
return audioFile.toString('base64');
};
// Ganti dengan jalur aktual ke file audio Anda
const dataUri = `data:audio/mpeg;base64,${encodeAudioFile("welcome.mp3")}`;
async function main() {
try {
const streamEnabled = false; // Apakah akan mengaktifkan keluaran streaming
const completion = await client.chat.completions.create({
model: "qwen3-asr-flash",
messages: [
{
role: "user",
content: [
{
type: "input_audio",
input_audio: {
data: dataUri
}
}
]
}
],
stream: streamEnabled,
// Saat stream adalah False, stream_options tidak dapat diatur
// stream_options: {
// "include_usage": true
// },
asr_options: {
// language: "zh",
enable_itn: false
}
});
if (streamEnabled) {
let fullContent = "";
console.log("Keluaran streaming:");
for await (const chunk of completion) {
console.log(JSON.stringify(chunk));
if (chunk.choices && chunk.choices.length > 0) {
const delta = chunk.choices[0].delta;
if (delta && delta.content) {
fullContent += delta.content;
}
}
}
console.log(`Konten lengkap: ${fullContent}`);
} else {
console.log(`Keluaran non-streaming: ${completion.choices[0].message.content}`);
}
} catch (err) {
console.error(`Error: ${err}`);
}
}
main();Proses file audio panjang
Pengenalan ucapan non-real-time mentranskripsikan file audio panjang secara asinkron, sehingga sangat cocok untuk menghasilkan notula rapat, transkrip wawancara, dan meninjau rekaman panggilan.
Batasan:
-
Qwen3-ASR-Flash-Filetrans, Fun-ASR, dan Paraformer: Setiap file audio dibatasi hingga ukuran 2 GB dan durasi 12 jam.
-
Qwen3-ASR-Flash: Setiap file audio dibatasi hingga ukuran 10 MB dan durasi 5 menit. Untuk audio yang lebih panjang, gunakan Qwen3-ASR-Flash-Filetrans atau Fun-ASR.
-
Saat speaker diarization diaktifkan: Pastikan durasi audio kurang dari 2 jam untuk menghindari kegagalan pengenalan atau timeout. Untuk detail selengkapnya, lihat Speaker diarization.
Cara kerja: Transkripsi audio panjang dijalankan sebagai tugas asinkron dalam tiga langkah:
-
Kirim tugas transkripsi untuk menerima
task_id. -
Poll status task, atau panggil metode wait SDK untuk memblokir hingga tugas selesai.
-
Setelah tugas selesai, unduh file JSON hasil dari URL yang dikembalikan.
Untuk contoh kode, lihat panduan quick start Qwen3-ASR-Flash-Filetrans.
Streaming output
Qwen3-ASR-Flash mendukung streaming output: hasil antara dikembalikan selama audio sedang diproses, yang sangat cocok untuk kasus penggunaan yang memerlukan umpan balik progres secara real-time.
Fun-ASR, Paraformer, dan Qwen3-ASR-Flash-Filetrans adalah model transkripsi asinkron dan tidak mendukung streaming output. Ambil hasil akhirnya melalui polling task (lihat Proses file audio panjang).
Untuk mengaktifkan streaming output:
-
DashScope Python SDK: atur
streamkeTrue. -
DashScope Java SDK: panggil API melalui metode
streamCall. -
DashScope HTTP: atur Header
X-DashScope-SSEkeenable. -
OpenAI-compatible SDK: atur
streamkeTrue.
Untuk contoh kode streaming, lihat Streaming output dalam panduan quick start Qwen3-ASR-Flash.
Tingkatkan akurasi dengan hotwords
Fun-ASR dan Paraformer meningkatkan akurasi pengenalan untuk kata benda khusus domain (nama, lokasi, nama produk) melalui hotwords. Buat daftar hotword di Konsol Model Studio, lalu teruskan ID-nya ke API melalui parameter vocabulary_id.
Untuk petunjuk membuat dan menggunakan daftar hotword, lihat Tingkatkan akurasi pengenalan.
Konvensi penamaan SDK untuk parameter ini berbeda-beda (kunci dictionary, atribut objek, atau metode). Untuk pemetaan bidang lengkapnya, lihat referensi API untuk setiap SDK.
Tingkatkan akurasi dengan peningkatan konteks
Model fun-asr-flash-2026-06-15 meningkatkan akurasi pengenalan untuk kata benda khusus (nama, lokasi, istilah Produk) melalui peningkatan konteks — yaitu dengan meneruskan riwayat percakapan atau teks domain ke model.
Untuk Penggunaan dan contoh, lihat Context enhancement.
Speaker diarization
Speaker diarization mengidentifikasi pembicara yang berbeda dalam sebuah file audio dan memberi tag setiap kalimat dalam transcript dengan label pembicara. Fitur ini sangat cocok untuk rekaman rapat multipihak dan wawancara.
Model yang didukung: Fun-ASR dan Paraformer mendukung speaker diarization (secara default dinonaktifkan). Seri Qwen-ASR belum mendukung fitur ini.
Untuk mengaktifkan: Atur diarization_enabled ke true dalam permintaan API. Setiap kalimat dalam hasil respons kemudian akan menyertakan bidang speaker_id yang mengidentifikasi pembicara.
Struktur respons (cuplikan):
{
"transcripts": [
{
"sentences": [
{ "begin_time": 100, "end_time": 3820, "text": "Hello, let's discuss the project progress today.", "speaker_id": 0 },
{ "begin_time": 3820, "end_time": 6500, "text": "Sure, I'll give the update first.", "speaker_id": 1 }
]
}
]
}Konvensi penamaan SDK untuk bidang-bidang ini bervariasi (kunci kamus, atribut objek, atau metode). Untuk pemetaan bidang lengkap, lihat referensi API masing-masing SDK.
Saat speaker diarization diaktifkan, pastikan durasi audio tidak melebihi 2 jam untuk menghindari kegagalan pengenalan atau timeout. (Untuk batas durasi audio saat diarization tidak diaktifkan, lihat Process long audio files.) Diarization hanya didukung untuk audio mono.
Untuk definisi bidang lengkap, lihat referensi API.
Sensitive word filter
Fitur sensitive word filter mengganti atau menghapus kata sensitif dari hasil pengenalan. Fitur ini sangat cocok untuk quality assurance (QA) layanan pelanggan, kepatuhan konten, dan moderasi teks terjemahan (subtitle).
Model yang didukung: Fun-ASR dan Paraformer mendukung sensitive word filter. Seri Qwen-ASR (Qwen3-ASR-Flash dan Qwen3-ASR-Flash-Filetrans) belum mendukung fitur ini.
Perilaku default: Ketika parameter special_word_filter tidak ditentukan, sistem akan menerapkan daftar kata sensitif bawaan Alibaba Cloud Model Studio. Kata yang cocok akan diganti dengan jumlah karakter * yang sama.
Konfigurasi kustom: special_word_filter adalah objek JSON dengan tiga bidang:
-
filter_with_signed.word_list: Array string yang kecocokannya diganti dengan jumlah karakter*yang sama. Misalnya, dengan["test"], kalimat "please help me test it" menjadi "please help me **** it". -
filter_with_empty.word_list: Array string yang kecocokannya dihapus dari hasil akhir. Misalnya, dengan["start"], kalimat "is the game about to start now" menjadi "is the game about to now". -
system_reserved_filter: Nilai boolean. Default-nya adalahtrue. Mengontrol apakah daftar kata sensitif bawaan diterapkan selain daftar kustom.
Contoh konfigurasi:
{
"special_word_filter": {
"filter_with_signed": {
"word_list": ["test"]
},
"filter_with_empty": {
"word_list": ["start", "happen"]
},
"system_reserved_filter": true
}
}Konvensi penamaan SDK untuk parameter ini bervariasi (kunci dictionary, atribut objek, atau metode). Untuk pemetaan bidang lengkap, lihat Referensi API.
Emotion recognition
Qwen3-ASR-Flash-Filetrans dan Qwen3-ASR-Flash selalu mengaktifkan fitur emotion recognition tanpa memerlukan konfigurasi tambahan. Hasilnya mencakup tag emosi untuk pembicara, yang diambil dari tujuh kategori detail halus: surprised, neutral, happy, sad, disgusted, angry, dan fearful.
Field paths (berbeda tergantung antarmuka):
-
OpenAI-compatible interface (transkripsi real-time Qwen3-ASR-Flash): tersarang di
choices[].delta.annotations[].emotion(streaming) atauchoices[].message.annotations[].emotion(non-streaming). -
DashScope synchronous interface (Qwen3-ASR-Flash): tersarang di
output.choices[].message.annotations[].emotion. -
DashScope asynchronous task interface (Qwen3-ASR-Flash-Filetrans, transkripsi file audio): tersarang di
transcripts[].sentences[].emotion, bersama bidang timestamp dan speaker pada setiap objek sentence.
Struktur respons (cuplikan dari antarmuka DashScope asynchronous task):
{
"transcripts": [{
"sentences": [{
"begin_time": 0,
"end_time": 1440,
"text": "Welcome to Alibaba Cloud.",
"emotion": "neutral",
"language": "en"
}]
}]
}Konvensi penamaan SDK untuk bidang-bidang ini bervariasi (kunci dictionary, atribut objek, atau metode). Untuk pemetaan bidang lengkap, lihat referensi API.
Model non-real-time Fun-ASR dan Paraformer belum mendukung emotion recognition. Untuk menggunakan emotion recognition dengan pengenalan real-time, lihat bagian terkait di Real-time speech recognition.
Get timestamps
Pengenalan ucapan non-real-time dapat mengembalikan timestamp dalam transcript, yang mendukung pembuatan subtitle, penyorotan kata kunci, serta pengeditan audio atau video. Ketiga model transkripsi asinkron—Fun-ASR, Paraformer, dan Qwen3-ASR-Flash-Filetrans—mendukung timestamp, tetapi perilaku default dan metode pengontrolannya berbeda untuk tiap model:
-
Qwen3-ASR-Flash-Filetrans: Hanya antarmuka asinkron DashScope yang mendukung timestamp; fitur ini selalu aktif. Parameter permintaan
enable_wordsmengatur granularitasnya:false(default) mengembalikan timestamp tingkat kalimat;truemengembalikan timestamp tingkat kata. Timestamp tingkat kata hanya didukung untuk bahasa Tiongkok, Inggris, Jepang, Korea, Jerman, Prancis, Spanyol, Italia, Portugis, dan Rusia. Akurasinya tidak dijamin untuk bahasa lain. -
Fun-ASR: Timestamp selalu aktif dan tidak dapat dinonaktifkan.
-
Paraformer: Timestamp dinonaktifkan secara default. Untuk mengaktifkannya, atur parameter permintaan
timestamp_alignment_enabledke nilaitrue.
Saat Qwen3-ASR-Flash dipanggil melalui antarmuka yang kompatibel dengan OpenAI, output-nya berupa chat.completion dan tidak menyertakan bidang timestamp. Untuk mendapatkan timestamp, gunakan Qwen3-ASR-Flash-Filetrans (antarmuka tugas asinkron).
Timestamp dikembalikan dalam satuan milidetik pada dua tingkat:
-
Tingkat kalimat:
sentences[].begin_timedansentences[].end_timemenandai waktu mulai dan akhir setiap kalimat dalam audio. -
Tingkat kata: Larik
sentences[].words[]. Setiap elemennya berisibegin_time,end_time, dantext(teks kata atau karakter).
Struktur respons (cuplikan dari antarmuka tugas asinkron DashScope):
{
"transcripts": [{
"sentences": [{
"begin_time": 100,
"end_time": 3820,
"text": "Hello, let's discuss the project progress today.",
"words": [
{ "begin_time": 100, "end_time": 596, "text": "Hello" },
{ "begin_time": 596, "end_time": 844, "text": "let's" }
]
}]
}]
}Timestamp dalam audio berupa bilangan bulat milidetik (misalnya, 100). Nilai ini berbeda dengan end_time tingkat tugas (waktu penyelesaian tugas, berupa string seperti "2024-09-12 15:11:40.903"). Jangan tertukar.
Konvensi penamaan SDK untuk bidang-bidang ini bervariasi (kunci kamus, atribut objek, atau metode). Untuk pemetaan lengkap bidang tersebut, lihat referensi API.
Terapkan di lingkungan produksi
Praktik terbaik berikut meningkatkan kualitas pengenalan dan stabilitas sistem saat Anda menggunakan layanan speech recognition non-real-time di lingkungan produksi.
Praktik terbaik untuk produksi
-
File hosting: Unggah file audio ke Alibaba Cloud OSS dan panggil API melalui URL. Hindari mengunggah file lokal (API file lokal dibatasi hingga 100 QPS dan batas tersebut tidak dapat ditingkatkan).
-
Polling asinkron: Transkripsi audio panjang menggunakan alur asinkron. Tetapkan interval polling yang wajar (misalnya, 2–5 detik) untuk menghindari kuota Anda habis karena kueri yang terlalu sering. Jika Anda memerlukan throughput lebih tinggi daripada batas kueri 100 QPS, beralihlah ke notifikasi callback event. Untuk detailnya, lihat Ganti polling dengan callback untuk beban kerja berkonkurensi tinggi.
-
Penanganan error: Terapkan mekanisme retry yang andal. Lakukan retry pada timeout jaringan dan error server sementara (5xx) dengan exponential backoff.
-
Reduksi noise: Untuk audio yang berisik, lakukan pra-pemrosesan file menggunakan alat seperti FFmpeg sebelum mengirimkannya untuk pengenalan.
-
Pemilihan model: Pilih model berdasarkan durasi audio. Gunakan Qwen3-ASR-Flash untuk audio pendek hingga 5 menit. Gunakan Fun-ASR atau Qwen3-ASR-Flash-Filetrans untuk audio yang lebih panjang.
Ganti polling dengan callback untuk beban kerja berkonkurensi tinggi
Setelah Anda mengirimkan task transkripsi asinkron (Fun-ASR, Qwen3-ASR-Flash-Filetrans, atau Paraformer) melalui POST /api/v1/services/audio/asr/transcription, pola umumnya adalah melakukan polling ke GET /api/v1/tasks/{task_id} untuk mendapatkan hasilnya. Endpoint kueri tersebut memiliki batas default 20 QPS dan dapat diskalakan hingga 100 QPS, sehingga beban kerja batch berkonkurensi tinggi dapat dengan mudah memicu throttling.
Alih-alih itu, konfigurasikan notifikasi callback melalui EventBridge: ketika sebuah task selesai, Model Studio secara otomatis mendorong event dashscope:System:AsyncTaskFinish ke target yang telah Anda konfigurasi (titik akhir HTTP/HTTPS atau topik RocketMQ). Konsumen Anda membaca hasil langsung dari event tersebut dan tidak perlu lagi memanggil endpoint kueri, sehingga menghilangkan risiko throttling akibat polling. Untuk detail penyiapan, lihat Konfigurasi notifikasi callback EventBridge.
Model yang didukung
-
Didukung: Fun-ASR, Qwen3-ASR-Flash-Filetrans, dan Paraformer (semua task transkripsi asinkron).
-
Tidak didukung: Qwen3-ASR-Flash, yang menggunakan panggilan sinkron dan streaming, bukan task asinkron.
Isi pesan callback
Untuk ketiga model tersebut, isi pesan callback memiliki nilai data.contain_result yang diatur ke true, dan data.output_result membawa transcription_url secara langsung. Konsumen Anda dapat mengambil hasil pengenalan segera setelah menerima callback, tanpa perlu memanggil kembali GET /api/v1/tasks/{task_id}. Jalur dan struktur field hasil berbeda-beda antar ketiga model—lihat tabel berikut.
Pilih jalur yang benar berdasarkan model yang Anda panggil; jangan pernah hard-code satu jalur saja di konsumen Anda. Saat terjadi kegagalan, data.output_result.output tidak lagi berisi results atau result. Sebagai gantinya, field tersebut berisi code dan message. Periksa terlebih dahulu data.task_status, lalu baca hasilnya.
|
Model |
Kirim parameter |
Jalur field hasil (dalam isi callback) |
|
|
Fun-ASR |
|
|
|
|
Paraformer |
|
Sama seperti Fun-ASR: |
|
|
Qwen3-ASR-Flash-Filetrans |
|
|
|
Pertimbangan
Keamanan (pengiriman HTTP/HTTPS): Di lingkungan produksi, validasi header X-Eventbridge-Signature* pada setiap permintaan callback sebelum memproses permintaan tersebut. Tanpa validasi, IP eksternal mana pun dapat memalsukan event AsyncTaskFinish dan menyuntikkan hasil pengenalan palsu. Berikan waktu respons minimal 5 detik bagi titik akhir Anda untuk merespons setiap permintaan callback. Pengiriman melalui RocketMQ tidak memiliki signature per pesan; keamanan diterapkan melalui otentikasi RocketMQ.
Latensi pengiriman: Perkirakan jeda sekitar 1–90 detik antara penyelesaian task (end_time) dan kedatangan pesan di target Anda (titik akhir HTTP/HTTPS atau topik RocketMQ). Latensi tepatnya bergantung pada beban EventBridge saat ini.
Idempotensi: Event yang sama mungkin dikirimkan lebih dari sekali akibat retry. Terapkan pemrosesan idempoten di sisi konsumen; kami merekomendasikan penggunaan data.id atau data.task_id dari envelope CloudEvents sebagai kunci deduplikasi.
Model dan wilayah yang didukung
Singapore
Untuk memanggil model di bawah ini, gunakan Kunci API di wilayah Singapore:
-
Fun-ASR: fun-asr (stable, saat ini setara dengan fun-asr-2025-11-07), fun-asr-2025-11-07 (snapshot), fun-asr-2025-08-25 (snapshot), fun-asr-mtl (stable, saat ini setara dengan fun-asr-mtl-2025-08-25), fun-asr-mtl-2025-08-25 (snapshot)
-
Fun-ASR-Flash: fun-asr-flash-2026-06-15
-
Qwen3-ASR-Flash-Filetrans: qwen3-asr-flash-filetrans (stable, saat ini setara dengan qwen3-asr-flash-filetrans-2025-11-17), qwen3-asr-flash-filetrans-2025-11-17 (snapshot)
-
Qwen3-ASR-Flash: qwen3-asr-flash (stable, saat ini setara dengan qwen3-asr-flash-2025-09-08), qwen3-asr-flash-2026-02-10 (latest snapshot), qwen3-asr-flash-2025-09-08 (snapshot)
US (Virginia)
Untuk memanggil model di bawah ini, gunakan Kunci API di wilayah AS:
Qwen3-ASR-Flash: qwen3-asr-flash-us (stable, saat ini setara dengan qwen3-asr-flash-2025-09-08-us), qwen3-asr-flash-2025-09-08-us (snapshot)
China (Beijing)
Untuk memanggil model di bawah ini, gunakan Kunci API di wilayah Beijing.
-
Fun-ASR: fun-asr (stable, saat ini setara dengan fun-asr-2025-11-07), fun-asr-2025-11-07 (snapshot), fun-asr-2025-08-25 (snapshot), fun-asr-mtl (stable, saat ini setara dengan fun-asr-mtl-2025-08-25), fun-asr-mtl-2025-08-25 (snapshot)
-
Fun-ASR-Flash: fun-asr-flash-2026-06-15
-
Qwen3-ASR-Flash-Filetrans: qwen3-asr-flash-filetrans (stable, saat ini setara dengan qwen3-asr-flash-filetrans-2025-11-17), qwen3-asr-flash-filetrans-2025-11-17 (snapshot)
-
Qwen3-ASR-Flash: qwen3-asr-flash (stable, saat ini setara dengan qwen3-asr-flash-2025-09-08), qwen3-asr-flash-2026-02-10 (latest snapshot), qwen3-asr-flash-2025-09-08 (snapshot)
-
Paraformer: paraformer-v2, paraformer-8k-v2
Referensi API
FAQ
T: Bagaimana cara memberikan URL audio yang dapat diakses publik ke API?
Gunakan Alibaba Cloud Object Storage Service (OSS). OSS menyediakan penyimpanan yang sangat tersedia dan tahan lama, serta dapat menghasilkan URL yang dapat diakses publik.
Pastikan URL tersebut dapat dijangkau dari internet publik: Buka URL tersebut di browser atau jalankan curl terhadapnya untuk memastikan file audio berhasil diunduh atau diputar (kode status HTTP 200).
T: Bagaimana cara memeriksa apakah format audio memenuhi persyaratan?
Gunakan tool open-source ffprobe untuk memeriksa detail audio dengan cepat:
# Periksa format kontainer (format_name), kodek (codec_name), laju sampel (sample_rate), dan jumlah saluran (channels)
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 your_audio_file.mp3T: Bagaimana cara memproses audio agar memenuhi persyaratan model?
Gunakan tool open-source FFmpeg untuk memotong audio atau mengonversi format:
-
Pemotongan audio: ekstrak segmen dari file audio panjang
# -i: File input # -ss 00:01:30: Atur waktu mulai klip (mulai pada menit ke-1 detik ke-30) # -t 00:02:00: Atur durasi klip (klip selama 2 menit) # -c copy: Salin aliran audio langsung tanpa re-encoding; lebih cepat # output_clip.wav: File output ffmpeg -i long_audio.wav -ss 00:01:30 -t 00:02:00 -c copy output_clip.wav -
Konversi format
Sebagai contoh, konversi audio apa pun ke file WAV mono 16 kHz, 16-bit:
# -i: File input # -ac 1: Atur jumlah saluran menjadi 1 (mono) # -ar 16000: Atur laju sampel menjadi 16000 Hz (16 kHz) # -sample_fmt s16: Atur format sampel menjadi PCM integer bertanda 16-bit # output.wav: File output ffmpeg -i input.mp3 -ac 1 -ar 16000 -sample_fmt s16 output.wav
T: Bagaimana cara meningkatkan akurasi pengenalan?
Faktor-faktor berikut memengaruhi akurasi pengenalan. Periksa masing-masing dan sesuaikan secara tepat.
Faktor utama:
-
Kualitas suara: Peralatan perekaman, laju sampel, dan kebisingan lingkungan secara langsung memengaruhi kejelasan audio. Input berkualitas tinggi merupakan fondasi pengenalan yang akurat.
-
Karakteristik pembicara: Variasi nada, laju bicara, aksen, dan dialek—terutama dialek yang tidak umum dan aksen yang kuat—membuat pengenalan lebih sulit.
-
Bahasa dan kosakata: Penggunaan campuran bahasa, istilah teknis, dan bahasa gaul membuat pengenalan lebih sulit. Konfigurasikan hotword untuk meningkatkan akurasi pada terminologi spesifik domain.
Cara mengoptimalkan:
-
Tingkatkan kualitas audio: Gunakan mikrofon berkualitas tinggi, rekam pada laju sampel yang direkomendasikan, dan minimalkan kebisingan lingkungan serta gema.
-
Adaptasi terhadap pembicara: Untuk audio dengan aksen kuat atau dialek khas, pilih model yang mendukung dialek tersebut.
-
Konfigurasikan hotword: Tetapkan hotword untuk istilah teknis dan nama diri.