This topic describes the parameters and interface details of the Paraformer recorded speech recognition Java SDK.
Alibaba Cloud Model Studio has released a workspace-specific domain for the China (Beijing) region. The new dedicated domain delivers superior performance and higher stability for inference requests. We recommend migrating from dashscope.aliyuncs.com to {WorkspaceId}.cn-beijing.maas.aliyuncs.com.
Replace {WorkspaceId} with your actual Workspace ID. The existing domain remains fully functional.
User guide: Non-real-time speech recognition
Prerequisites
-
You have activated the service and Obtain an API key. Please Configure API key as an environment variable instead of hardcoding it in your code to prevent security risks caused by code leakage.
NoteWhen you need to provide temporary access to third-party applications or users, or when you want to strictly control high-risk operations such as accessing or deleting sensitive data, we recommend using temporary authentication tokens.
Compared with long-term API Keys, temporary authentication tokens have a short validity period (60 seconds) and higher security, making them suitable for temporary call scenarios and effectively reducing the risk of API Key leakage.
Usage: In your code, replace the API Key originally used for authentication with the obtained temporary authentication token.
Quick start
Core class (Transcription) provides interfaces for asynchronously submitting tasks, synchronously waiting for tasks to complete, and asynchronously querying task results. You can use the following two calling methods for recorded speech recognition:
Async submit + sync wait: After submitting a task, the current thread is blocked until the task finishes and the recognition result is obtained.
Async submit + async query: After submitting a task, you can query the task result at any time by calling the query interface.
Async submit + sync wait
Configure Request parameters.
Instantiate Core class (Transcription).
Call the
asyncCallmethod of Core class (Transcription) to asynchronously submit a task.NoteThe file transcription service processes tasks submitted through the API on a best-effort basis. After submission, a task enters the queued (
PENDING) state. The queue time depends on the queue length and file duration and cannot be precisely estimated, but typically completes within a few minutes. Once processing begins, speech recognition completes at several hundred times the real-time speed.After each task completes, the recognition result and URL download link are valid for 24 hours. After expiration, you cannot query the task or download results through the previously provided URL.
Call the
waitmethod of Core class (Transcription) to synchronously wait for the task to finish.Task statuses include
PENDING,RUNNING,SUCCEEDED, andFAILED. When the task is inPENDINGorRUNNINGstate, thewaitinterface is blocked. When the task is inSUCCEEDEDorFAILEDstate, thewaitinterface is no longer blocked and returns the task result.waitreturns Task result (TranscriptionResult).
Async submit + async query
Configure Request parameters.
Instantiate Core class (Transcription).
Call the
asyncCallmethod of Core class (Transcription) to asynchronously submit a task.NoteThe file transcription service processes tasks submitted through the API on a best-effort basis. After submission, a task enters the queued (
PENDING) state. The queue time depends on the queue length and file duration and cannot be precisely estimated, but typically completes within a few minutes. Once processing begins, speech recognition completes at several hundred times the real-time speed.After each task completes, the recognition result and URL download link are valid for 24 hours. After expiration, you cannot query the task or download results through the previously provided URL.
Loop calling the
fetchmethod of Core class (Transcription) until you obtain the final task result.When the task status is
SUCCEEDEDorFAILED, stop polling and process the result.fetchreturns Task result (TranscriptionResult).
Request parameters
Request parameters are configured through the chained methods of TranscriptionParam.
Parameter | Type | Default | Required | Description |
model | String | - | Yes | Specifies the Paraformer model name for audio/video file transcription. See Supported models. |
fileUrls | List<String> | - | Yes | The URL list of audio/video files for transcription. Supports HTTP/HTTPS protocols. Only one URL is supported per request. If audio files are stored in Alibaba Cloud OSS, the SDK does not support temporary URLs with the oss:// prefix. |
vocabularyId | String | - | No | The latest hot word ID. Supports the latest v2 series models with language configuration. The hot words associated with this ID take effect for this speech recognition. Disabled by default. For usage instructions, see Custom hotwords. |
phraseId | String | - | No | The hot word ID. The hot words associated with this ID take effect for this speech recognition. Disabled by default. Note: |
channelId | List<Integer> | [0] | No | Specifies the audio track indexes to recognize in a multi-track audio file. Indexes start from 0. For example, [0] means recognizing the first track, and [0, 1] means recognizing both the first and second tracks simultaneously. If this parameter is omitted, only the first track is processed by default. Important Each specified track is billed independently. For example, requesting [0, 1] for a single file incurs two separate charges. |
disfluencyRemovalEnabled | Boolean | false | No | Filters filler words. Disabled by default. |
timestampAlignmentEnabled | Boolean | false | No | Whether to enable the timestamp alignment feature. Disabled by default. |
specialWordFilter | String | - | No | Specifies sensitive words to process during speech recognition and supports setting different processing methods for different sensitive words. If this parameter is not provided, the system uses the built-in sensitive word filtering logic, and words matching the Alibaba Cloud Model Studio sensitive word list in the recognition results will be replaced with If this parameter is provided, the following sensitive word processing strategies can be implemented:
The value of this parameter should be a JSON string with the following structure: JSON field descriptions:
|
language_hints | String[] | ["zh", "en"] | No | Specifies the language codes of the speech to be recognized. This parameter is only applicable to the paraformer-v2 model. Supported language codes:
Note
Set via parameterSet via parameters |
diarizationEnabled | Boolean | false | No | Automatic speaker diarization. Disabled by default. Only applicable to mono audio. Multi-channel audio does not support speaker diarization. When this feature is enabled, the recognition results will include a Note If speaker diarization is enabled, it is recommended that the audio duration does not exceed 2 hours, otherwise recognition may fail or time out. For an example of |
speakerCount | Integer | - | No | A reference value for the number of speakers. Valid values: integers from 2 to 100 (inclusive). Takes effect when speaker diarization is enabled ( By default, the system automatically determines the number of speakers. If this parameter is configured, it only serves as a hint to the algorithm to try to output the specified number of speakers, but the exact number is not guaranteed. |
apiKey | String | - | No | The API Key. If the API Key is already configured in an environment variable, you do not need to set it in the code. Otherwise, you must set it in the code. |
Response
Task result (TranscriptionResult)
TranscriptionResult encapsulates the current task result.
Interface/Method | Parameter | Return value | Description |
| None | requestId | Gets the requestId. |
| None | taskId | Gets the taskId. |
| None |
| Gets the task status.
Note When a task contains multiple subtasks, as long as any subtask succeeds, the overall task status is marked as |
| None | Gets the Subtask result (TranscriptionTaskResult). Each task recognizes one or more audio files. Different audio files are processed in different subtasks, so each task corresponds to one or more subtasks. | |
| None | Task result in JSON format | Gets the task result. The result is in JSON format. If you use the |
Subtask result (TranscriptionTaskResult)
TranscriptionTaskResult encapsulates the subtask result. A subtask recognizes 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 of the recognition result | Gets the URL of the recognition result. This URL is valid for 24 hours. After expiration, you cannot query the task or download results through the previously provided URL. The recognition result is saved as a JSON file. You can download the file through the URL above or directly read its content 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 during task execution, which may be empty | Gets key information during task execution. When a task fails, you can check 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 audio format of the source file. |
channels | array[integer] | The audio track index information of the source file. Returns [0] for mono audio, [0, 1] for dual-track audio, and so on. |
original_sampling_rate | integer | The sampling rate (Hz) of the audio in the source file. |
original_duration | integer | The original audio duration (ms) of the source file. |
channel_id | integer | The audio track index of the transcription result, starting from 0. |
content_duration | integer | The duration (ms) of content identified as speech in the audio track. Important The Paraformer speech recognition model service only transcribes and meters content identified as speech in the audio track, and bills accordingly. Non-speech content is neither metered nor billed. Typically, the speech content duration is shorter than the original audio duration. Since the determination of whether speech content exists is made by an AI model, there may be some deviation from the actual situation. |
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 | The start timestamp (ms). |
end_time | integer | The end timestamp (ms). |
text | string | The speech transcription result. |
speaker_id | integer | The index of the current speaker, starting from 0, used to distinguish different speakers. This field is only displayed in the recognition results when speaker diarization is enabled. |
punctuation | string | The predicted punctuation after the word (if any). |
Key interfaces
Task query parameter class (TranscriptionQueryParam)
TranscriptionQueryParam is used when waiting for a task to complete (calling the Transcription wait method) or querying the task result (calling the Transcription fetch method).
Create a TranscriptionQueryParam instance through the static method FromTranscriptionParam.
Interface/Method | Parameter | Return value | Description |
|
| A | Creates a |
Core class (Transcription)
Transcription can be imported with "import com.alibaba.dashscope.audio.asr.transcription.*;". Its key interfaces are as follows:
Interface/Method | Parameter | Return value | Description |
|
| Asynchronously submits a speech recognition task. | |
|
| Blocks the current thread until the async task finishes (task status is | |
|
| Asynchronously queries the current task result. |
Other interfaces: Batch query task status / Cancel task
For details, see Manage asynchronous tasks: Supports batch querying of recorded speech recognition tasks submitted within the last 24 hours, and also supports canceling tasks in PENDING (queued) state.
Error codes
If you encounter errors, see Error codes for troubleshooting.
If the issue persists, join the developer community to report the issue and provide the Request ID for further investigation.
When a task contains multiple subtasks, as long as any subtask succeeds, the overall task status is marked as SUCCEEDED. You need to check the subtask_status field to determine the result of each subtask.
Error response example:
{
"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/rich_text_exaple_1.wav",
"code": "InvalidFile.DownloadFailed",
"message": "The audio file cannot be downloaded.",
"subtask_status": "FAILED"
}
],
"task_metrics": {
"TOTAL": 1,
"SUCCEEDED": 0,
"FAILED": 1
}
}More examples
For more examples, see GitHub.
FAQ
Feature questions
Q: Does it support Base64-encoded audio?
No. Base64-encoded audio is not supported. Only audio accessible via publicly accessible URLs is supported. Binary streams and direct local file recognition are not supported.
Q: How to provide audio files as publicly accessible URLs?
Generally, follow these steps (this provides a general approach; specifics vary by storage product. We recommend uploading audio to Alibaba Cloud OSS):
When using the SDK, if audio files are stored in Alibaba Cloud OSS, temporary URLs with the oss:// prefix are not supported.
When using the RESTful API, if audio files are stored in Alibaba Cloud OSS, temporary URLs with the oss:// prefix are supported:
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 recognition results?
After submission, the task enters a queued (PENDING) state. The queue time depends on the queue length and file duration and cannot be precisely estimated, but typically completes within a few minutes. Please wait patiently. Longer audio files require more processing time.
Troubleshooting
If you encounter code errors, troubleshoot based on the information in Error codes.
Q: What to do if the recognition result and audio playback are out of sync?
Set the Request parameters timestampAlignmentEnabled to true to enable the timestamp alignment feature, which synchronizes the recognition result with audio playback.
Q: Unable to get results after continuous polling?
This may be due to rate limiting. Please wait patiently. If you need capacity expansion, join the developer community to apply.
Q: Why is there no recognition result (unable to recognize speech)?
Check whether the audio meets the requirements (format, sampling rate).
If you are using the
paraformer-v2model, check whether thelanguage_hintssetting is correct.If none of the above resolves the issue, you can customize hot words to improve the recognition of specific words.
More questions
See GitHub QA.