This topic describes the parameters and interface details of the Paraformer non-real-time speech recognition Java SDK.
Prerequisites
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 non-real-time 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.- The 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.
- The file transcription service processes tasks submitted through the API on a best-effort basis. After submission, a task enters the queued (
-
Call the
waitmethod of Core class (Transcription) to synchronously wait for the task to finish. Task statuses includePENDING,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).
Click to view complete example
Click to view complete example
Async submit + async query
- Configure Request parameters.
- Instantiate Core class (Transcription).
-
Call the
asyncCallmethod of Core class (Transcription) to asynchronously submit a task.- The 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.
- The file transcription service processes tasks submitted through the API on a best-effort basis. After submission, a task enters the queued (
-
Loop calling the
fetchmethod of Core class (Transcription) until you obtain the final task result. When the task status isSUCCEEDEDorFAILED, stop polling and process the result.fetchreturns Task result (TranscriptionResult).
Click to view complete example
Click to view complete example
Request parameters
Request parameters are configured through the chained methods of TranscriptionParam.
Click to view example
Click to view example
| 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. | |
| 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. |
| 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 * of equal length.If this parameter is provided, the following sensitive word processing strategies can be implemented:
| |
| 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:
language_hints needs to be set through the TranscriptionParam instance's parameter method or parameters method: |
| 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 speaker_id field to distinguish different speakers.If speaker diarization is enabled, it is recommended that the audio duration does not exceed 2 hours, otherwise recognition may fail or time out. speaker_id, see Recognition result description. |
| 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 (diarizationEnabled set to true).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 | TaskStatus, the task status | Gets the task status.TaskStatus is an enum class. You only need to focus on the following four statuses: PENDING, RUNNING, SUCCEEDED, and FAILED.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. | |
| None | Subtask result (TranscriptionTaskResult) | 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 getOutput interface to get the task result, you need to parse it yourself.
Click to view JSON example Normal example code" is the error code and "message" is the error message. These two fields only appear in error scenarios. You can use them to troubleshoot issues by referring to Error codes. |
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 | TaskStatus, the subtask status | Gets the subtask status.TaskStatus is an enum class. You only need to focus on the following four statuses: PENDING, RUNNING, SUCCEEDED, and FAILED. | |
| 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.
Click to view recognition result example
Click to view recognition result example
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. 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.
Click to view example
Click to view example
| Interface/Method | Parameter | Return value | Description |
|---|---|---|---|
| A TranscriptionQueryParam instance | Creates a TranscriptionQueryParam instance. |
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 |
|---|---|---|---|
param: Speech recognition parameters, a TranscriptionParam instance | Task result (TranscriptionResult) | Asynchronously submits a speech recognition task. | |
queryParam: A TranscriptionQueryParam instance | Task result (TranscriptionResult) | Blocks the current thread until the async task finishes (task status is SUCCEEDED or FAILED). | |
queryParam: A TranscriptionQueryParam instance | Task result (TranscriptionResult) | Asynchronously queries the current task result. |
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:
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):
1. Choose a storage and hosting method
1. Choose a storage and hosting method
-
Object Storage Service (recommended):
- Use a cloud provider's object storage service (such as Alibaba Cloud OSS) to upload audio files to a bucket and set them to public access.
- Advantages: High availability, CDN acceleration support, easy management.
-
Web server:
- Place audio files on a web server that supports HTTP/HTTPS access (such as Nginx or Apache).
- Advantages: Suitable for small projects or local testing.
-
Content Delivery Network (CDN):
- Host audio files on a CDN and access them through the CDN-provided URL.
- Advantages: Accelerated file delivery, suitable for high-concurrency scenarios.
2. Upload audio files
2. Upload audio files
-
Object Storage Service:
- Log in to the cloud provider's console and create a bucket.
- Upload audio files and set file permissions to "public read" or generate temporary access links.
-
Web server:
- Place audio files in the server's designated directory (such as
/var/www/html/audio/). - Ensure files are accessible via HTTP/HTTPS.
- Place audio files in the server's designated directory (such as
3. Generate a publicly accessible URL
3. Generate a publicly accessible URL
-
Object Storage Service:
- After uploading, the system automatically generates a public access URL (typically in the format
https://<bucket-name>.<region>.aliyuncs.com/<file-name>). - If you need a more user-friendly domain, you can bind a custom domain and enable HTTPS.
- After uploading, the system automatically generates a public access URL (typically in the format
-
Web server:
- The file access URL is typically the server address plus the file path (such as
https://your-domain.com/audio/file.mp3).
- The file access URL is typically the server address plus the file path (such as
-
CDN:
- After configuring CDN acceleration, use the CDN-provided URL (such as
https://cdn.your-domain.com/audio/file.mp3).
- After configuring CDN acceleration, use the CDN-provided URL (such as
4. Verify URL accessibility
4. Verify URL accessibility
- Open the URL in a browser and check whether the audio file can be played.
- Use tools (such as
curlor Postman) to verify whether the URL returns a correct HTTP response (status code 200).
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.