The parameters and interface details of the Fun-ASR audio file recognition Java SDK.
User guide: For more information about models and selection suggestions, see Audio file recognition - Fun-ASR/Paraformer.
Prerequisites
You have activated Model Studio and created an API key. To prevent security risks from code leaks, do not hard-code the API key in your code. Instead, export it as an environment variable.
NoteUse a temporary authentication token to grant temporary access to third-party applications or users, or to strictly control high-risk operations like accessing or deleting sensitive data.
A temporary authentication token is more secure than a long-lived API key because it expires in 60 seconds. This short lifespan makes it ideal for temporary call scenarios and significantly reduces the risk of a compromised API key.
To use this method, replace the API key in your code with the temporary authentication token.
Model availability
International
In the international deployment mode, endpoints and data storage are in the Singapore region. Model inference compute resources are dynamically scheduled globally, excluding Chinese Mainland.
Model | Version | Unit price | Free quota (Note) |
fun-asr Currently, fun-asr-2025-11-07 | Stable | $0.000035/second | 36,000 seconds (10 hours) Valid for 90 days |
fun-asr-2025-11-07 Improved far-field VAD over fun-asr-2025-08-25 for higher accuracy | Snapshot | ||
fun-asr-2025-08-25 | |||
fun-asr-mtl Currently, fun-asr-mtl-2025-08-25 | Stable | ||
fun-asr-mtl-2025-08-25 | Snapshot |
Languages supported:
fun-asr and fun-asr-2025-11-07: Mandarin, Cantonese, Wu, Minnan, Hakka, Gan, Xiang, and Jin. Also supports Mandarin accents from Zhongyuan, Southwest, Jilu, Jianghuai, Lanyin, Jiaoliao, Northeast, Beijing, and Hong Kong–Taiwan regions—including Henan, Shaanxi, Hubei, Sichuan, Chongqing, Yunnan, Guizhou, Guangdong, Guangxi, Hebei, Tianjin, Shandong, Anhui, Nanjing, Jiangsu, Hangzhou, Gansu, and Ningxia. Also supports English and Japanese.
fun-asr-2025-08-25: Mandarin and English.
fun-asr-mtl and fun-asr-mtl-2025-08-25: Mandarin, Cantonese, English, Japanese, Korean, Vietnamese, Indonesian, Thai, Malay, Filipino, Arabic, Hindi, Bulgarian, Croatian, Czech, Danish, Dutch, Estonian, Finnish, Greek, Hungarian, Irish, Latvian, Lithuanian, Maltese, Polish, Portuguese, Romanian, Slovak, Slovenian, and Swedish.
Sample rates supported: Any
Audio formats supported: aac, amr, avi, flac, flv, m4a, mkv, mov, mp3, mp4, mpeg, ogg, opus, wav, webm, wma, wmv
Chinese Mainland
In the Chinese Mainland deployment mode, endpoints and data storage are in the Beijing region. Model inference compute resources are limited to Chinese Mainland.
Model | Version | Unit price | Free quota (Note) |
fun-asr Currently, fun-asr-2025-11-07 | Stable | $0.000032 / second | No free quota |
fun-asr-2025-11-07 Improved far-field VAD over fun-asr-2025-08-25 for higher accuracy | Snapshot | ||
fun-asr-2025-08-25 | |||
fun-asr-mtl Currently, fun-asr-mtl-2025-08-25 | Stable | ||
fun-asr-mtl-2025-08-25 | Snapshot |
Languages supported:
fun-asr and fun-asr-2025-11-07: Mandarin, Cantonese, Wu, Minnan, Hakka, Gan, Xiang, and Jin. Also supports Mandarin accents from Zhongyuan, Southwest, Jilu, Jianghuai, Lanyin, Jiaoliao, Northeast, Beijing, and Hong Kong–Taiwan regions—including Henan, Shaanxi, Hubei, Sichuan, Chongqing, Yunnan, Guizhou, Guangdong, Guangxi, Hebei, Tianjin, Shandong, Anhui, Nanjing, Jiangsu, Hangzhou, Gansu, and Ningxia. Also supports English and Japanese.
fun-asr-2025-08-25: Mandarin and English.
fun-asr-mtl and fun-asr-mtl-2025-08-25: Mandarin, Cantonese, English, Japanese, Korean, Vietnamese, Indonesian, Thai, Malay, Filipino, Arabic, Hindi, Bulgarian, Croatian, Czech, Danish, Dutch, Estonian, Finnish, Greek, Hungarian, Irish, Latvian, Lithuanian, Maltese, Polish, Portuguese, Romanian, Slovak, Slovenian, and Swedish.
Sample rates supported: Any
Audio formats supported: aac, amr, avi, flac, flv, m4a, mkv, mov, mp3, mp4, mpeg, ogg, opus, wav, webm, wma, wmv
Limitations
The input must be a publicly accessible file URL (HTTP/HTTPS), for example, https://your-domain.com/file.mp3. Local files and Base64 audio are not supported.
The SDK does not support temporary URLs with the oss:// prefix for audio files stored in OSS.
The RESTful API supports temporary URLs with the oss:// prefix for audio files in OSS, but with the following limitations:
The temporary URL is valid for 48 hours and cannot be used after it expires. Do not use it in a production environment.
The API for obtaining an upload credential is limited to 100 QPS and does not support scaling out. Do not use it in production environments, high-concurrency scenarios, or stress testing scenarios.
For production environments, use a stable storage service such as OSS to ensure long-term file availability and avoid rate limiting issues.
Specify the URLs using the fileUrls parameter. A single request supports up to 100 URLs.
Audio formats
aac,amr,avi,flac,flv,m4a,mkv,mov,mp3,mp4,mpeg,ogg,opus,wav,webm,wma,wmvImportantBecause many audio and video formats and their variants exist, it is not technically feasible to test all of them. The API cannot guarantee that all formats can be correctly recognized. You should test your files to verify that you can obtain the expected speech recognition results.
Audio sample rate: Any
Audio file size and duration
The maximum file size is 2 GB. The maximum duration is 12 hours. For files exceeding these limits, split or compress the file before uploading. For more information about best practices for file pre-processing, see Preprocess video files to improve file transcription efficiency (for audio file recognition scenarios).
Number of audio files for batch processing
A single request supports up to 100 file URLs.
Recognizable languages: fun-asr supports Chinese and English. fun-asr-mtl-2025-08-25 supports Chinese, Cantonese, English, Japanese, Thai, Vietnamese, and Indonesian.
Getting started
The core class (Transcription) provides interfaces for submitting tasks asynchronously, waiting for tasks to finish synchronously, and querying task results asynchronously. You can use the following two methods to perform audio file recognition:
Asynchronous submission and synchronous wait: Submit a task and block the current thread until the task is complete to retrieve the recognition result.
Asynchronous submission and asynchronous query: Submit a task and then call the query interface to retrieve the task result when needed.
Asynchronous submission + synchronous wait
Configure request parameters.
Instantiate the core class (Transcription).
Call the
asyncCallmethod of the core class (Transcription) to asynchronously submit the task.NoteTasks enter the
PENDINGstate after submission. Queuing time (typically a few minutes) depends on the queue length and file duration. Once processing starts, speech recognition completes at significantly accelerated speed.Recognition results and download URLs expire 24 hours after the task completes. Tasks become unqueryable after expiration.
Call the
waitmethod of the core class (Transcription) to synchronously wait for the task to finish.Task statuses include
PENDING,RUNNING,SUCCEEDED, andFAILED. Thewaitinterface blocks onPENDING/RUNNINGand unblocks when the task reachesSUCCEEDEDorFAILED, returning the task execution result.waitreturns the task execution result (TranscriptionResult).
Asynchronous submission + asynchronous query
Configure request parameters.
Instantiate the core class (Transcription).
Call the
asyncCallmethod of the core class (Transcription) to asynchronously submit the task.NoteTasks enter the
PENDINGstate after submission. Queuing time (typically a few minutes) depends on the queue length and file duration. Once processing starts, speech recognition completes at significantly accelerated speed.Recognition results and download URLs expire 24 hours after the task completes. Tasks become unqueryable after expiration.
Repeatedly call the
fetchmethod of the core class (Transcription) until you retrieve the final task result.If the task status is
SUCCEEDEDorFAILED, stop polling and process the result.fetchreturns the task execution result (TranscriptionResult).
Request parameters
Configure the request parameters using the chained methods of TranscriptionParam.
Parameter | Type | Default value | Required | Description |
model | String | - | Yes | The name of the model used for audio and video file transcription. For more information, see Model availability. |
fileUrls | List<String> | - | Yes | A list of URLs for the audio and video files to be transcribed. The HTTP and HTTPS protocols are supported. A single request supports up to 100 URLs. If your audio files are stored in Alibaba Cloud OSS, the SDK does not support temporary URLs with the oss:// prefix. |
vocabularyId | String | - | No | The ID of a hotword vocabulary. The hotwords in the specified vocabulary take effect during this speech recognition task. This feature is disabled by default. For more information about how to use this feature, see Customize hotwords. |
channelId | List<Integer> | [0] | No | Specifies track indices to recognize in multi-track audio files. Indices start from 0. For example, [0] recognizes the first track, and [0, 1] recognizes the first and second tracks simultaneously. If omitted, only the first track is processed by default. Important Each specified track is billed separately. For example, requesting [0, 1] for a single file incurs two separate charges. |
specialWordFilter | String | - | No | Specifies the sensitive words to be processed during speech recognition and supports different processing methods for different sensitive words. If this parameter is not passed, the system's built-in sensitive word filtering logic is enabled. Words in the recognition result that match the Alibaba Cloud Model Studio sensitive word list are replaced with asterisks ( If this parameter is passed, the following sensitive word processing policies can be implemented:
The value of this parameter must be a JSON string with the following structure: JSON field descriptions:
|
diarizationEnabled | Boolean | false | No | Automatic speaker diarization is disabled by default. This feature applies to single-channel audio only (not supported for multi-channel audio). When enabled, recognition results include the For an example of |
speakerCount | Integer | - | No | This parameter is a speaker count hint (an integer from 2 to 100). It only takes effect when By default, speaker count is auto-detected. This parameter assists the algorithm but does not guarantee the exact speaker count. |
language_hints | String[] | - | No | Sets language codes for recognition. If you cannot determine the language in advance, leave this unset—the model will auto-detect the language. The system reads only the first value in the array. Extra values are ignored. Language codes supported by different models:
Note
Set using parameterSet using parameters |
apiKey | String | - | No | Your API key. If you have configured the API key as an environment variable, you do not need to set it in the code. Otherwise, you must set it in the code. |
Response
Task execution result (TranscriptionResult)
TranscriptionResult encapsulates the current task execution result.
Interface/Method | Parameter | Return value | Description |
| None | requestId | Gets the request ID. |
| None | taskId | Gets the task ID. |
| None |
| Gets the task status.
Note When a task contains multiple subtasks, the overall task status is marked as |
| None | Gets the subtask execution result (TranscriptionTaskResult). Each task recognizes one or more audio files. Different audio files are processed in different subtasks. Therefore, each task corresponds to one or more subtasks. | |
| None | Task execution result, in JSON format | Gets the task execution result. The result is in JSON format. If you use the |
Subtask execution result (TranscriptionTaskResult)
TranscriptionTaskResult encapsulates the subtask execution result. A subtask is the recognition of a single audio file.
Interface/Method | Parameter | Return value | Description |
| None | URL of the recognized audio file | Gets the URL of the recognized audio file. |
| None | URL for the recognition result | Gets the URL for the recognition result. This URL is valid for 24 hours. After this period, you cannot query the task or download the result using the URL from a previous query. The recognition result is saved as a JSON file. You can download this file from the URL or read its content directly through an HTTP request. For the meaning of each field in the JSON data, see Recognition result description. |
| None |
| Gets the subtask status.
|
| None | Key information from the task execution process. May be empty. | Gets key information from the task execution process. If a task fails, you can view this content to analyze the cause. |
Recognition result description
The recognition result is saved as a JSON file.
The key parameters are as follows:
Parameter | Type | Description |
audio_format | string | The format of the audio in the source file. |
channels | array[integer] | The audio track index information in the source file. Returns [0] for single-track audio, [0, 1] for dual-track audio, and so on. |
original_sampling_rate | integer | The sample rate of the audio in the source file (Hz). |
original_duration_in_milliseconds | integer | The original duration of the audio in the source file (ms). |
channel_id | integer | The index of the transcribed audio track, starting from 0. |
content_duration | integer | The duration of the content in the audio track that is identified as speech (ms). Important Billing is based on speech content duration only (non-speech parts are not metered). Speech duration is typically shorter than total audio duration. The AI-based speech detection may have minor discrepancies. |
transcript | string | The paragraph-level speech transcription result. |
sentences | array | The sentence-level speech transcription result. |
words | array | The word-level speech transcription result. |
begin_time | integer | Start timestamp (ms). |
end_time | integer | End timestamp (ms). |
text | string | The speech transcription result. |
speaker_id | integer | The index of the current speaker, starting from 0. This is used to distinguish different speakers. This field is displayed in the recognition result only when speaker diarization is enabled. |
punctuation | string | The predicted punctuation mark after the word, if any. |
Key interfaces
Task query parameter class (TranscriptionQueryParam)
TranscriptionQueryParam is used when waiting for a task to complete (by calling the wait method of Transcription) or querying a task execution result (by calling the fetch method of Transcription).
Create a TranscriptionQueryParam instance using the static method FromTranscriptionParam.
Interface/Method | Parameter | Return value | Description |
|
| A | Creates a |
Core class (Transcription)
You can import Transcription using the statement import com.alibaba.dashscope.audio.asr.transcription.*;. The key interfaces of this class are as follows:
Interface/Method | Parameter | Return value | Description |
|
| Asynchronously submits a speech recognition task. | |
|
| Blocks the current thread until the asynchronous task is complete (task status is | |
|
| Asynchronously queries the execution result of the current task. |
Error codes
If an error occurs, see Error messages to troubleshoot the issue.
If a task contains multiple subtasks, the overall task status is marked as SUCCEEDED if at least one subtask succeeds. You must check the subtask_status field to determine the result of each subtask.
Example of an error response:
{
"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": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/long_audio_demo_cn.mp3",
"transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/20241216/xxxx",
"subtask_status": "SUCCEEDED"
},
{
"file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/rich_text_exaple_1.wav",
"code": "InvalidFile.DownloadFailed",
"message": "The audio file cannot be downloaded.",
"subtask_status": "FAILED"
}
],
"task_metrics": {
"TOTAL": 2,
"SUCCEEDED": 1,
"FAILED": 1
}
}FAQ
Features
Q: Is audio in Base64 encoding supported?
This service recognizes audio from publicly accessible URLs only. It does not support audio in Base64 encoding, binary streams, or local files.
Q: How do I provide an audio file as a publicly accessible URL?
You can typically follow these steps. This is a general guide, and the specific steps may vary for different storage products. We recommend that you upload the audio to Object Storage Service (OSS).
The SDK does not support temporary URLs with the oss:// prefix for audio files stored in OSS.
The RESTful API supports temporary URLs with the oss:// prefix for audio files in OSS, but with the following limitations:
The temporary URL is valid for 48 hours and cannot be used after it expires. Do not use it in a production environment.
The API for obtaining an upload credential is limited to 100 QPS and does not support scaling out. Do not use it in production environments, high-concurrency scenarios, or stress testing scenarios.
For production environments, use a stable storage service such as OSS to ensure long-term file availability and avoid rate limiting issues.
Q: How long does it take to get the recognition result?
Tasks enter the PENDING state after submission. Queuing time (typically a few minutes) varies with the queue length and file duration. The longer the audio file, the longer the processing time.
Troubleshooting
If a code error occurs, troubleshoot the issue based on the information in Error codes.
Q: Why can't I get a result after continuous polling?
This may be because of rate limiting.
Q: Why is the audio not recognized (no recognition result)?
Check whether the audio format and sample rate are correct and meet the parameter constraints.
You can use the ffprobe tool to retrieve information about the audio container, codec, sample rate, and channels:
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx