Skip to main content
Non-real-time speech recognition (Paraformer)

Paraformer non-real-time speech recognition Java SDK

This topic describes the parameters and interface details of the Paraformer non-real-time 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.
This document applies only to the China (Beijing) region. To use models, you must use an API key from the China (Beijing) region.
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.
When 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 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

image
  1. Configure Request parameters.
  2. Instantiate Core class (Transcription).
  3. Call the asyncCall method 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.
  4. Call the wait method of Core class (Transcription) to synchronously wait for the task to finish. Task statuses include PENDING, RUNNING, SUCCEEDED, and FAILED. When the task is in PENDING or RUNNING state, the wait interface is blocked. When the task is in SUCCEEDED or FAILED state, the wait interface is no longer blocked and returns the task result. wait returns Task result (TranscriptionResult).
import com.alibaba.dashscope.audio.asr.transcription.*;
import com.google.gson.*;

import java.util.Arrays;

public class Main {
    public static void main(String[] args) {
        // The following configuration is for the China (Beijing) region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration varies by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
        // Create transcription request parameters
        TranscriptionParam param =
                TranscriptionParam.builder()
                        // If the API Key is not configured in an environment variable, replace apiKey with your own API Key
                        //.apiKey("apikey")
                        .model("paraformer-v2")
                        // "language_hints" is only supported by the paraformer-v2 model
                        .parameter("language_hints", new String[]{"zh", "en"})
                        .fileUrls(
                                Arrays.asList(
                                        "{YOUR_AUDIO_URL}"))
                        .build();
        try {
            Transcription transcription = new Transcription();
            // Submit transcription request
            TranscriptionResult result = transcription.asyncCall(param);
            System.out.println("RequestId: " + result.getRequestId());
            // Block and wait for the task to complete and get the result
            result = transcription.wait(
                    TranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId()));
            // Print result
            System.out.println(result.getOutput());
        } catch (Exception e) {
            System.out.println("error: " + e);
        }
        System.exit(0);
    }
}

Async submit + async query

image
  1. Configure Request parameters.
  2. Instantiate Core class (Transcription).
  3. Call the asyncCall method 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.
  4. Loop calling the fetch method of Core class (Transcription) until you obtain the final task result. When the task status is SUCCEEDED or FAILED, stop polling and process the result. fetch returns Task result (TranscriptionResult).
import com.alibaba.dashscope.audio.asr.transcription.*;
import com.alibaba.dashscope.common.TaskStatus;
import com.google.gson.*;

import java.util.Arrays;

public class Main {
    public static void main(String[] args) {
        // The following configuration is for the China (Beijing) region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration varies by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
        // Create transcription request parameters
        TranscriptionParam param =
                TranscriptionParam.builder()
                        // If the API Key is not configured in an environment variable, replace apiKey with your own API Key
                        //.apiKey("apikey")
                        .model("paraformer-v2")
                        // "language_hints" is only supported by the paraformer-v2 model
                        .parameter("language_hints", new String[]{"zh", "en"})
                        .fileUrls(
                                Arrays.asList(
                                        "{YOUR_AUDIO_URL}"))
                        .build();
        try {
            Transcription transcription = new Transcription();
            // Submit transcription request
            TranscriptionResult result = transcription.asyncCall(param);
            System.out.println("RequestId: " + result.getRequestId());
            // Loop to get the task result until the task finishes
            while (true) {
                result = transcription.fetch(TranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId()));
                if (result.getTaskStatus() == TaskStatus.SUCCEEDED || result.getTaskStatus() == TaskStatus.FAILED) {
                    break;
                }
                Thread.sleep(1000);
            }
            // Print result
            System.out.println(result.getOutput());
        } catch (Exception e) {
            System.out.println("error: " + e);
        }
        System.exit(0);
    }
}

Request parameters

Request parameters are configured through the chained methods of TranscriptionParam.
TranscriptionParam param = TranscriptionParam.builder()
  .model("paraformer-v2")
  // "language_hints" is only supported by the paraformer-v2 model
  .parameter("language_hints", new String[]{"zh", "en"})
  .fileUrls(
          Arrays.asList(
                  "{YOUR_AUDIO_URL}"))
  .build();
ParameterTypeDefaultRequiredDescription
modelString
YesSpecifies the Paraformer model name for audio/video file transcription. See Supported models.
fileUrlsList<String>
YesThe 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.
vocabularyIdString
NoThe 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.
channelIdList<Integer>[0]NoSpecifies 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.
Each specified track is billed independently. For example, requesting [0, 1] for a single file incurs two separate charges.
disfluencyRemovalEnabledBooleanfalseNoFilters filler words. Disabled by default.
timestampAlignmentEnabledBooleanfalseNoWhether to enable the timestamp alignment feature. Disabled by default.
specialWordFilterString
NoSpecifies 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:
  • Replace with *: Replace matching sensitive words with * of equal length.
  • Filter directly: Completely remove matching sensitive words from the recognition results.
The value of this parameter should be a JSON string with the following structure:
{
  "filter_with_signed": {
    "word_list": ["test"]
  },
  "filter_with_empty": {
    "word_list": ["start", "happen"]
  },
  "system_reserved_filter": true
}
JSON field descriptions:
  • filter_with_signed
    • Type: Object.
    • Required: No.
    • Description: Configures the list of sensitive words to be replaced with *. Matching words in the recognition results will be replaced with * of equal length.
    • Example: Using the JSON above, the speech recognition result for "Help me test this code" would be "Help me **** this code".
    • Internal fields:
      • word_list: An array of strings listing the sensitive words to be replaced.
  • filter_with_empty
    • Type: Object.
    • Required: No.
    • Description: Configures the list of sensitive words to be removed (filtered) from the recognition results. Matching words will be completely deleted.
    • Example: Using the JSON above, the speech recognition result for "The game is about to start, right?" would be "The game is about to, right?".
    • Internal fields:
      • word_list: An array of strings listing the sensitive words to be completely removed (filtered).
  • system_reserved_filter
    • Type: Boolean.
    • Required: No.
    • Default: true.
    • Description: Whether to enable the system's built-in sensitive word rules. When set to true, the system's built-in sensitive word filtering logic is also enabled, and words matching the Alibaba Cloud Model Studio sensitive word list in the recognition results will be replaced with * of equal length.
language_hintsString[]["zh", "en"]NoSpecifies the language codes of the speech to be recognized.This parameter is only applicable to the paraformer-v2 model.Supported language codes:
  • zh: Chinese
  • en: English
  • ja: Japanese
  • yue: Cantonese
  • ko: Korean
  • de: German
  • fr: French
  • ru: Russian
language_hints needs to be set through the TranscriptionParam instance's parameter method or parameters method:
TranscriptionParam param = TranscriptionParam.builder()
  // "language_hints" is only supported by the paraformer-v2 model
  .model("paraformer-v2")
  .parameter("language_hints", new String[]{"zh", "en"})
  .build();
diarizationEnabledBooleanfalseNoAutomatic 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.
For an example of speaker_id, see Recognition result description.
speakerCountInteger
NoA 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.
apiKeyString
NoThe 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/MethodParameterReturn valueDescription
public String getRequestId()
NonerequestIdGets the requestId.
public String getTaskId()
NonetaskIdGets the taskId.
public TaskStatus getTaskStatus()
NoneTaskStatus, the task statusGets 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.
public List<TranscriptionTaskResult> getResults()
NoneSubtask 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.
public JsonObject getOutput()
NoneTask result in JSON formatGets 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.
Normal example
{
    "task_id":"0795ff8c-b666-4e91-bb8b-xxx",
    "task_status":"SUCCEEDED",
    "submit_time":"2025-02-13 16:12:09.109",
    "scheduled_time":"2025-02-13 16:12:09.128",
    "end_time":"2025-02-13 16:12:10.189",
    "results":[
        {
            "file_url":"{YOUR_AUDIO_URL}",
            "transcription_url":"https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/20250213/16%3A12/3baafe5f-d09d-46c6-8b01-724927670edb-1.json?Expires=1739520730&OSSAccessKeyId=YOUR_ACCESS_KEY_ID&Signature=YOUR_SIGNATURE",
            "subtask_status":"SUCCEEDED"
        }
    ],
    "task_metrics":{
        "TOTAL":1,
        "SUCCEEDED":1,
        "FAILED":0
    }
}
Error 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.
{
    "task_id": "7bac899c-06ec-4a79-8875-xxxxxxxxxxxx",
    "task_status": "SUCCEEDED",
    "submit_time": "2024-12-16 16:30:59.170",
    "scheduled_time": "2024-12-16 16:30:59.204",
    "end_time": "2024-12-16 16:31:02.375",
    "results": [
        {
            "file_url": "{YOUR_AUDIO_URL}",
            "code": "InvalidFile.DownloadFailed",
            "message": "The audio file cannot be downloaded.",
            "subtask_status": "FAILED"
        }
    ],
    "task_metrics": {
        "TOTAL": 1,
        "SUCCEEDED": 0,
        "FAILED": 1
    }
}

Subtask result (TranscriptionTaskResult)

TranscriptionTaskResult encapsulates the subtask result. A subtask recognizes a single audio file.
Interface/MethodParameterReturn valueDescription
public String getFileUrl()
NoneURL of the recognized audio fileGets the URL of the recognized audio file.
public String getTranscriptionUrl()
NoneURL of the recognition resultGets 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.
public TaskStatus getSubTaskStatus()
NoneTaskStatus, the subtask statusGets the subtask status.TaskStatus is an enum class. You only need to focus on the following four statuses: PENDING, RUNNING, SUCCEEDED, and FAILED.
public String getMessage()
NoneKey information during task execution, which may be emptyGets 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.
{
    "file_url":"{YOUR_AUDIO_URL}",
    "properties":{
        "audio_format":"pcm_s16le",
        "channels":[
            0
        ],
        "original_sampling_rate":16000,
        "original_duration_in_milliseconds":3834
    },
    "transcripts":[
        {
            "channel_id":0,
            "content_duration_in_milliseconds":3720,
            "text":"Hello world, this is the Alibaba speech laboratory.",
            "sentences":[
                {
                    "begin_time":100,
                    "end_time":3820,
                    "text":"Hello world, this is the Alibaba speech laboratory.",
                    "sentence_id":1,
                    "speaker_id":0, //This field is only displayed when automatic speaker diarization is enabled
                    "words":[
                        {
                            "begin_time":100,
                            "end_time":596,
                            "text":"Hello ",
                            "punctuation":""
                        },
                        {
                            "begin_time":596,
                            "end_time":844,
                            "text":"world",
                            "punctuation":", "
                        }
                        // Other content omitted here
                    ]
                }
            ]
        }
    ]
}
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.

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.
// Create transcription request parameters
TranscriptionParam param =
        TranscriptionParam.builder()
                // If the API Key is not configured in an environment variable, replace apiKey with your own API Key
                //.apiKey("apikey")
                .model("paraformer-v2")
                // "language_hints" is only supported by the paraformer-v2 model
                .parameter("language_hints", new String[]{"zh", "en"})
                .fileUrls(
                        Arrays.asList(
                                "{YOUR_AUDIO_URL}"))
                .build();
try {
    Transcription transcription = new Transcription();
    // Submit transcription request
    TranscriptionResult result = transcription.asyncCall(param);
    System.out.println("RequestId: " + result.getRequestId());
    TranscriptionQueryParam queryParam = TranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId());

} catch (Exception e) {
    System.out.println("error: " + e);
}
Interface/MethodParameterReturn valueDescription
public static TranscriptionQueryParam FromTranscriptionParam(TranscriptionParam param, String taskId)
  • param: A TranscriptionParam instance
  • taskId: The task ID
A TranscriptionQueryParam instanceCreates 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/MethodParameterReturn valueDescription
public TranscriptionResult asyncCall(TranscriptionParam param)
param: Speech recognition parameters, a TranscriptionParam instanceTask result (TranscriptionResult)Asynchronously submits a speech recognition task.
public TranscriptionResult wait(TranscriptionQueryParam queryParam)
queryParam: A TranscriptionQueryParam instanceTask result (TranscriptionResult)Blocks the current thread until the async task finishes (task status is SUCCEEDED or FAILED).
public TranscriptionResult fetch(TranscriptionQueryParam queryParam)
queryParam: A TranscriptionQueryParam instanceTask 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:
{
    "task_id": "7bac899c-06ec-4a79-8875-xxxxxxxxxxxx",
    "task_status": "SUCCEEDED",
    "submit_time": "2024-12-16 16:30:59.170",
    "scheduled_time": "2024-12-16 16:30:59.204",
    "end_time": "2024-12-16 16:31:02.375",
    "results": [
        {
            "file_url": "{YOUR_AUDIO_URL}",
            "code": "InvalidFile.DownloadFailed",
            "message": "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):
For example:
  • 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.
Upload audio files based on your chosen storage/hosting method, for example:
  • 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.
For example:
  • 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.
  • Web server:
    • The file access URL is typically the server address plus the file path (such as https://your-domain.com/audio/file.mp3).
  • CDN:
    • After configuring CDN acceleration, use the CDN-provided URL (such as https://cdn.your-domain.com/audio/file.mp3).
In a public network environment, ensure the generated URL is accessible, for example:
  • Open the URL in a browser and check whether the audio file can be played.
  • Use tools (such as curl or Postman) to verify whether the URL returns a correct HTTP response (status code 200).
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-v2 model, check whether the language_hints setting 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.
Text Generation
Image Generation
  • FAQ
Video Generation
Audio
Realtime API
Text Embedding
Model Production