Alibaba Cloud Model Studio:Java SDK

• You have activated the Model Studio and created an API key. Export it as an environment variable (not hard-coded) to prevent security risks.

  Note

  For temporary access or strict control over high-risk operations (accessing/deleting sensitive data), use a temporary authentication token instead.

  Compared with long-term API keys, temporary tokens are more secure (60-second lifespan) and reduce API key leakage risk.

  To use a temporary token, replace the API key used for authentication in your code with the temporary authentication token.

• Install the latest version of the DashScope SDK.

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. Replace WorkspaceId with your actual workspace ID. The URLs vary by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.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"))
                        .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. Replace WorkspaceId with your actual workspace ID. The URLs vary by region.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.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"))
                        .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_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":1,
        "SUCCEEDED":1,
        "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/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
          }
      }

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"))
                .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 codes 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/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
    }
}

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