Qwen-Audio-ASR-Filetrans non-real-time speech recognition HarmonyOS SDK_Alibaba Cloud Model Studio(Model Studio) - Alibaba Cloud Model Studio

This guide explains how to use the Qwen-Audio-ASR-Filetrans non-real-time speech recognition HarmonyOS SDK to convert speech to text.

Quick start

Obtain an API key: Obtain an API key. For security, we recommend configuring the API key as an environment variable.
Download the SDK and run the sample code:
- Download the latest SDK package.
- Extract the TAR package. Obtain the HAR-format SDK from the neonui directory and add it to your project dependencies. For C++ integration, obtain the dynamic libraries and header files from native/libs and native/include in the TAR package.
- Open the project in DevEco Studio. The sample code is located in DashFunAsrFileTranscriberPage.ets. Replace the API key to try the feature.

Invocation steps

Synchronous mode

Initialize the SDK.
Configure parameters based on your business requirements.
Call startFileTranscriber to start a recognition task with async_request set to false.
In the onFileTransEventCallback interface, listen for the EVENT_FILE_TRANS_RESULT event to obtain the final recognition result.
Call release to release SDK resources.

Asynchronous mode

Initialize the SDK.
Configure parameters based on your business requirements.
Call startFileTranscriber to start a recognition task with async_request set to true.
Call queryFileTranscriber to query the recognition progress or result.
In the onFileTransEventCallback interface, listen for the EVENT_FILE_TRANS_QUERY_RESULT event to obtain the current query result.
In the onFileTransEventCallback interface, listen for the EVENT_FILE_TRANS_RESULT event to obtain the final recognition result.
Call release to release SDK resources.

Request parameters

Connection and control parameters

Pass a JSON string to the parameters parameter of initializeFileTrans to configure the following parameters.

Example

The following JSON string is an example and does not include all parameters. Add parameters as needed:

{
    "url": "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}

Parameter descriptions

Parameter	Type	Required	Description
`url`	`string`	Yes	The endpoint. This is fixed at `wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription`. Replace `{WorkspaceId}` with your actual workspace ID.
`apikey`	`string`	Yes	The API key. We recommend using a more secure temporary API key with a short validity period to reduce the risk of leaking a long-term key.
`service_mode`	`string`	Yes	The operating mode. For non-real-time speech recognition, this is fixed at `"1"`.
`device_id`	`string`	Yes	A unique string that identifies the end user. You can set it to an in-app user ID or a unique device identifier generated by the client. This ID is mainly used for log tracking and troubleshooting.
`debug_path`	`string`	No	The storage path for log files. This parameter takes effect only if you set `save_log` to true when you call `initializeFileTrans`. In this case, you must specify a log file path. Otherwise, an error occurs. A maximum of two log files are retained locally.
`max_log_file_size`	`number`	No	Sets the maximum size of a log file in bytes. This parameter takes effect only if you set `save_log` to true when you call `initializeFileTrans`. Default value: 104857600 (100 * 1024 * 1024 bytes, or 100 MiB).

Speech recognition effect parameters

Configure the nls_config parameter by using setParams, or configure all speech recognition effect parameters by using startFileTranscriber.

Example

The following JSON string is an example and does not include all parameters. Add parameters as needed:

{
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"qwen-audio-3.0-asr-flash-filetrans",
        "diarization_enabled": false,
        "parameters": {
            "speech_noise_threshold": 0.0
        }
    }
}

Parameter descriptions

Parameter	Type	Required	Description
`file_urls`	`array[string]`	Yes	A list of URLs for the audio or video files to transcribe. HTTP and HTTPS are supported. A single request supports only 1 URL. For input requirements such as supported audio formats and file size and duration limits, see Audio specifications. If an audio file is stored in Alibaba Cloud OSS, the RESTful API supports a temporary URL with the `oss://` prefix, but the SDK does not. Important A temporary URL is valid for 48 hours and cannot be used after it expires. Do not use temporary URLs in production environments. The file upload credential interface is limited to 100 QPS and cannot be scaled out. Do not use it in production environments, high-concurrency scenarios, or stress tests. In production environments, use stable storage such as Alibaba Cloud OSS to ensure long-term file availability and avoid throttling. If a temporary public OSS URL cannot be accessed, set the `X-DashScope-OssResourceResolve` request header to `enable`. This method is not recommended. The SDK does not support configuring request headers.
`async_request`	`boolean`	No	Specifies whether to use an asynchronous request. Default value: `false`. Valid values: - true: asynchronous request - false: synchronous request.
`apikey`	`string`	No	If `apikey` in Connection and control parameters is a temporary API key, update it here before it expires.
`nls_config`	`object`	Yes	The core speech recognition configuration object, which contains key parameters for model selection and recognition effect control.
`nls_config.model`	`string`	Yes	The model name.
`nls_config.special_word_filter`	`object`	No	Specifies sensitive words to process during speech recognition and supports different processing methods for different words. For more information, see Sensitive word filtering.
`nls_config.channel_id`	`array[integer]`	No	Specifies the indexes of audio tracks to recognize in a multitrack audio file. Indexes start from 0. For example, `[0]` recognizes the first track, and `[0, 1]` recognizes the first and second tracks. If omitted, the first track is processed. ImportantEach specified track is billed separately. For example, `[0, 1]` for one file incurs two separate charges. Default value: `[0]`.
`nls_config.diarization_enabled`	`boolean`	No	Specifies whether to enable speaker diarization. This feature is disabled by default. It applies only to mono audio. Multichannel audio does not support speaker diarization. When enabled, the recognition result contains `speaker_id` to distinguish speakers. NoteIf speaker diarization is enabled, we recommend limiting the audio duration to 2 hours to avoid recognition failure or timeout. Default value: false. For an example of `speaker_id`, see Recognition result descriptions.
`nls_config.speaker_count`	`integer`	No	ImportantThis parameter takes effect only when speaker diarization is enabled by setting `diarization_enabled` to `true`. It provides a reference value for the number of speakers. Valid values are integers from 2 through 100. By default, the number of speakers is automatically determined. If this parameter is set, it only guides the algorithm to output the specified number and does not guarantee that number. No default value.
`nls_config.vocabulary_id`	`string`	No	The precompiled hotword list ID. Create a hotword list first and pass its ID during recognition to use the hotwords in the list. This is suitable when the vocabulary is known and relatively stable and the same vocabulary needs to be reused across requests. For more information, see Precompiled hotwords.
`nls_config.language_hints`	`array[string]`	No	Specifies language codes for the audio to recognize. If the language cannot be determined in advance, omit this parameter and the model automatically detects the language. You can set up to 4 values. If you set more, only the first 4 take effect. Click to view the supported language codes zh: Chinese en: English ja: Japanese ko: Korean vi: Vietnamese th: Thai id: Indonesian ms: Malay tl: Filipino hi: Hindi ar: Arabic fr: French de: German es: Spanish pt: Portuguese ru: Russian it: Italian nl: Dutch sv: Swedish da: Danish fi: Finnish no: Norwegian el: Greek pl: Polish cs: Czech hu: Hungarian ro: Romanian bg: Bulgarian hr: Croatian sk: Slovak
`nls_config.parameters`	`object`	No	Configures additional parameters as a JSON object.

Key interfaces

NativeNui

initializeFileTrans

Initializes a speech transcription SDK instance. Do not initialize the instance again before you call release.

NoteUnlike real-time speech recognition, non-real-time audio file transcription must use initializeFileTrans and pass an INativeFileTransCallback callback instead of using initialize.

This interface blocks the calling thread. Call it from a non-UI thread.

Method signature

public initializeFileTrans(callback: INativeFileTransCallback,
                           parameters: string,
                           level: number,
                           save_log: boolean = false): number

Parameter descriptions

Parameter	Type	Description
`callback`	`INativeFileTransCallback`	An implementation of the file transcription event and data callback interface.
`parameters`	`string`	A JSON string that contains authentication, connection, and debugging parameters. See Connection and control parameters.
`level`	`number`	Controls the SDK log level. Valid values are defined by the `Constants.LogLevel` enumeration.
`save_log`	`boolean`	Specifies whether to save local logs. If this parameter is `true`, use `debug_path` in Connection and control parameters to specify a path. You can also use `max_log_file_size` to set the file size.

setParams

Sets or updates only the nls_config parameter. If all parameters are provided in startFileTranscriber, you do not need to call this method.

Method signature

public setParams(params: string): number

Parameter descriptions

Parameter	Type	Description
`params`	`string`	The `nls_config` parameter in Speech recognition effect parameters. Parameters outside `nls_config` cannot be set by using this method. Example: `{ "nls_config": { "model":"qwen-audio-3.0-asr-flash-filetrans", "diarization_enabled": false } }`

startFileTranscriber

Starts recognition.

Method signature

public startFileTranscriber(params: string, task_id: ArrayBuffer): number

Parameter descriptions

Parameter	Type	Description
`params`	`string`	The speech recognition effect parameters. Example: `{ "file_urls": [ "{YOUR_AUDIO_URL}" ], "async_request": false, "nls_config": { "model":"qwen-audio-3.0-asr-flash-filetrans", "diarization_enabled": false } }`
`task_id`	`ArrayBuffer`	The task ID buffer. The SDK writes an internally generated random task ID string to this buffer. The buffer must be at least 33 bytes long. The example uses `new ArrayBuffer(64)`. After a successful call, decode the buffer to obtain the task's `task_id`.

queryFileTranscriber

Queries the current status and result of an asynchronous task. After a successful call, the result is returned by the EVENT_FILE_TRANS_QUERY_RESULT event in the onFileTransEventCallback callback.

Method signature

public queryFileTranscriber(task_id: string): number

Parameter descriptions

Parameter	Type	Description
`task_id`	`string`	The ID of the task to query, obtained from the buffer written by `startFileTranscriber`.

cancelFileTranscriber

Immediately cancels the current task.

Method signature

public cancelFileTranscriber(task_id: string): number

Parameter descriptions

Parameter	Type	Description
`task_id`	`string`	The ID of the task to cancel.

release

Releases all internal SDK resources. After this method is called, the SDK instance becomes unavailable. To use it again, call initializeFileTrans to reinitialize it.

Method signature

public release(): number

GetVersion

Obtains the current SDK version information.

Method signature

public GetVersion(): string

Return value

The current SDK version information.

INativeFileTransCallback

Defines callbacks for file transcription events and recognition results.

onFileTransEventCallback

Listens for file transcription events and obtains speech recognition results.

Method signature

onFileTransEventCallback: (event: Constants.NuiEvent, resultCode: number, finish: number,
                           asrResult: AsrResult, taskId: string) => void;

Parameter descriptions

Parameter	Type	Description
`event`	`Constants.NuiEvent`	The callback event.
`resultCode`	`number`	Valid only when the `EVENT_ASR_ERROR` event occurs.
`finish`	`number`	Indicates whether the task has ended.
`asrResult`	`AsrResult`	The speech recognition result.
`taskId`	`string`	The task ID.

Constants.NuiEvent

HarmonyOS SDK event types are defined by the Constants.NuiEvent enumeration. The following events apply to audio file transcription:

Event	Description
`EVENT_FILE_TRANS_CONNECTED`	The service is connected.
`EVENT_FILE_TRANS_UPLOADED`	The audio file to recognize is uploaded.
`EVENT_FILE_TRANS_QUERY_RESULT`	The task query result.
`EVENT_FILE_TRANS_RESULT`	The final recognition result.
`EVENT_ASR_ERROR`	An error occurs during speech recognition.

Auxiliary types

Constants.LogLevel

The enumeration values for the level parameter are as follows:

Value	Description
`LOG_LEVEL_VERBOSE`	The most detailed logs.
`LOG_LEVEL_DEBUG`	Debug logs.
`LOG_LEVEL_INFO`	Informational logs (default).
`LOG_LEVEL_WARNING`	Warning logs.
`LOG_LEVEL_ERROR`	Error logs.
`LOG_LEVEL_NONE`	Disables logging.

Download the result

Non-real-time speech recognition results are generated asynchronously. The response returned by the EVENT_FILE_TRANS_RESULT event contains transcription_url. Download the recognition text in JSON format from this URL. The URL has a validity period. Download the result promptly.