Alibaba Cloud Model Studio:Java SDK

• 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.

  Note

  Use 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.

• Install the latest version of the DashScope SDK.

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.

• Audio formats

  aac, amr, avi, flac, flv, m4a, mkv, mov, mp3, mp4, mpeg, ogg, opus, wav, webm, wma, wmv

  Important

  Because 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.

Asynchronous submission + synchronous wait

1. Configure request parameters.

2. Instantiate the core class (Transcription).

3. Call the asyncCall method of the core class (Transcription) to asynchronously submit the task.

   Note

   • Tasks enter the PENDING state 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.

4. Call the wait method of the core class (Transcription) to synchronously wait for the task to finish.

   Task statuses include PENDING, RUNNING, SUCCEEDED, and FAILED. The wait interface blocks on PENDING/RUNNING and unblocks when the task reaches SUCCEEDED or FAILED, returning the task execution result.

   wait returns the task execution result (TranscriptionResult).

import com.alibaba.dashscope.audio.asr.transcription.*;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.*;

import java.util.Arrays;

public class Main {
    public static void main(String[] args) {
        // The following URL is for the Singapore region. If you use a model in the Beijing region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
        Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
        // Create transcription request parameters.
        TranscriptionParam param =
                TranscriptionParam.builder()
                        // The API keys for the Singapore and Beijing regions are different. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key.
                        // If you have not configured an environment variable, replace the following line with your Model Studio API key: .apiKey("sk-xxx")
                        //.apiKey("apikey")
                        .model("fun-asr") // Here, fun-asr is used as an example. You can change the model name as needed. For a list of models, see https://www.alibabacloud.com/help/en/model-studio/models.
                        .fileUrls(
                                Arrays.asList(
                                        "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav",
                                        "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.wav"))
                        .build();
        try {
            Transcription transcription = new Transcription();
            // Submit the transcription request.
            TranscriptionResult result = transcription.asyncCall(param);
            System.out.println("RequestId: " + result.getRequestId());
            // Block and wait for the task to complete, then get the result.
            result = transcription.wait(
                    TranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId()));
            // Print the result.
            System.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(result.getOutput()));
        } catch (Exception e) {
            System.out.println("error: " + e);
        }
        System.exit(0);
    }
}

Asynchronous submission + asynchronous query

1. Configure request parameters.

2. Instantiate the core class (Transcription).

3. Call the asyncCall method of the core class (Transcription) to asynchronously submit the task.

   Note

   • Tasks enter the PENDING state 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.

4. Repeatedly call the fetch method of the core class (Transcription) until you retrieve the final task result.

   If the task status is SUCCEEDED or FAILED, stop polling and process the result.

   fetch returns the task execution result (TranscriptionResult).

import com.alibaba.dashscope.audio.asr.transcription.*;
import com.alibaba.dashscope.common.TaskStatus;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.*;

import java.util.Arrays;

public class Main {
    public static void main(String[] args) {
        // The following URL is for the Singapore region. If you use a model in the Beijing region, replace the URL with: https://dashscope.aliyuncs.com/api/v1
        Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
        // Create transcription request parameters.
        TranscriptionParam param =
                TranscriptionParam.builder()
                        // The API keys for the Singapore and Beijing regions are different. To obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key.
                        // If you have not configured an environment variable, replace the following line with your Model Studio API key: .apiKey("sk-xxx")
                        //.apiKey("apikey")
                        .model("fun-asr") // Here, fun-asr is used as an example. You can change the model name as needed. For a list of models, see https://www.alibabacloud.com/help/en/model-studio/models.
                        .fileUrls(
                                Arrays.asList(
                                        "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav",
                                        "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.wav"))
                        .build();
        try {
            Transcription transcription = new Transcription();
            // Submit the transcription request.
            TranscriptionResult result = transcription.asyncCall(param);
            System.out.println("RequestId: " + result.getRequestId());
            // Poll for the task execution result until the task is complete.
            while (true) {
                result = transcription.fetch(TranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId()));
                if (result.getTaskStatus() == TaskStatus.SUCCEEDED || result.getTaskStatus() == TaskStatus.FAILED) {
                    break;
                }
                Thread.sleep(1000);
            }
            // Print the result.
            System.out.println(new GsonBuilder().setPrettyPrinting().create().toJson(result.getOutput()));
        } catch (Exception e) {
            System.out.println("error: " + e);
        }
        System.exit(0);
    }
}

Task execution result (TranscriptionResult)

TranscriptionResult encapsulates the current task execution result.

public String getRequestId()

public String getTaskId()

public TaskStatus getTaskStatus()

public List<TranscriptionTaskResult> getResults()

public JsonObject getOutput()

{
    "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":"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.wav",
            "transcription_url":"https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/20250213/16%3A12/34604a7b-579a-4223-8797-5116a49b07ec-1.json?Expires=1739520730&OSSAccessKeyId=yourOSSAccessKeyId&Signature=tMqyH56oB5rDW9%2FFqD8Yo%2F3WaPk%3D",
            "subtask_status":"SUCCEEDED"
        },
        {
            "file_url":"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav",
            "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=yourOSSAccessKeyId&Signature=BF7vPxlsJN9hkJlY%2BLReezxOwK8%3D",
            "subtask_status":"SUCCEEDED"
        }
    ],
    "task_metrics":{
        "TOTAL":2,
        "SUCCEEDED":2,
        "FAILED":0
    }
}

{
    "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
    }
}

Subtask execution result (TranscriptionTaskResult)

TranscriptionTaskResult encapsulates the subtask execution result. A subtask is the recognition of a single audio file.

public String getFileUrl()

public String getTranscriptionUrl()

public TaskStatus getSubTaskStatus()

public String getMessage()

Recognition result description

{
    "file_url":"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav",
    "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 Alibaba Speech Lab.",
            "sentences":[
                {
                    "begin_time":100,
                    "end_time":3820,
                    "text":"Hello world, this is Alibaba Speech Lab.",
                    "sentence_id":1,
                    "speaker_id":0, // This field is displayed only 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 is omitted here.
                    ]
                }
            ]
        }
    ]
}

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.

// Create transcription request parameters.
TranscriptionParam param =
        TranscriptionParam.builder()
                // If you have not configured the API key as an environment variable, replace apiKey with your own API key.
                //.apiKey("apikey")
                .model("fun-asr")
                .fileUrls(
                        Arrays.asList(
                                "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav",
                                "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.wav"))
                .build();
try {
    Transcription transcription = new Transcription();
    // Submit the 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);
}

public static TranscriptionQueryParam FromTranscriptionParam(TranscriptionParam param, String taskId)

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:

public TranscriptionResult asyncCall(TranscriptionParam param)

public TranscriptionResult wait(TranscriptionQueryParam queryParam)

public TranscriptionResult fetch(TranscriptionQueryParam queryParam)

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
    }
}

Features

Troubleshooting

If a code error occurs, troubleshoot the issue based on the information in Error codes.

ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx