Skip to main content
Qwen-Audio-3.x-ASR-Flash-Filetrans/Fun-ASR

Qwen-Audio-3.x-ASR-Flash-Filetrans/Fun-ASR non-real-time speech recognition HarmonyOS SDK

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

User guide: Non-real-time speech recognition. For input requirements such as supported audio formats and file size and duration limits, see Audio specifications.

Quick start

  1. Obtain an API key: Obtain an API key. For security, we recommend configuring the API key as an environment variable.
  2. 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

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

Asynchronous mode

  1. Initialize the SDK.
  2. Configure parameters based on your business requirements.
  3. Call startFileTranscriber to start a recognition task with async_request set to true.
  4. Call queryFileTranscriber to query the recognition progress or result.
  5. In the onFileTransEventCallback interface, listen for the EVENT_FILE_TRANS_QUERY_RESULT event to obtain the current query result.
  6. In the onFileTransEventCallback interface, listen for the EVENT_FILE_TRANS_RESULT event to obtain the final recognition result.
  7. 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
ParameterTypeRequiredDescription
urlstringYesThe 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.
apikeystringYesThe 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_modestringYesThe operating mode. For non-real-time speech recognition, this is fixed at "1".
device_idstringYesA 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_pathstringNoThe 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_sizenumberNoSets 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
ParameterTypeRequiredDescription
file_urlsarray[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.

  • 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_requestbooleanNoSpecifies whether to use an asynchronous request. Default value: false. Valid values: - true: asynchronous request - false: synchronous request.
apikeystringNoIf apikey in Connection and control parameters is a temporary API key, update it here before it expires.
nls_configobjectYesThe core speech recognition configuration object, which contains key parameters for model selection and recognition effect control.
nls_config.modelstringYesThe model used in the example. For model information, see Supported models and regions.
nls_config.special_word_filterobjectNoSpecifies 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_idarray[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.

Each specified track is billed separately. For example, [0, 1] for one file incurs two separate charges.

Default value: [0].

nls_config.diarization_enabledbooleanNo

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.

If 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_countintegerNo

This 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_idstringNoThe 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_hintsarray[string]NoSpecifies 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. Qwen-Audio-3.0-ASR-Flash-Filetrans models support up to 4 values. If more than 4 values are specified, only the first 4 take effect. Fun-ASR models support only 1 value. If multiple values are specified, only the first one takes effect. Supported language codes: - qwen-audio-3.0-asr-flash-filetrans, fun-asr, fun-asr-2025-11-07, fun-asr-mtl, and fun-asr-mtl-2025-08-25: - 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 - fun-asr-2025-08-25: - zh: Chinese - en: English.
nls_config.parametersobjectNoConfigures 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.
Unlike 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
ParameterTypeDescription
callbackINativeFileTransCallbackAn implementation of the file transcription event and data callback interface.
parametersstringA JSON string that contains authentication, connection, and debugging parameters. See Connection and control parameters.
levelnumberControls the SDK log level. Valid values are defined by the Constants.LogLevel enumeration.
save_logbooleanSpecifies 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.
  • Return value
An error code. See Error code reference.

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
ParameterTypeDescription
paramsstringThe 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 } }
  • Return value
An error code. See Error code reference.

startFileTranscriber

Starts recognition.
  • Method signature
public startFileTranscriber(params: string, task_id: ArrayBuffer): number
  • Parameter descriptions
ParameterTypeDescription
paramsstringThe 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_idArrayBufferThe 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.
  • Return value
An error code. See Error code reference.

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
ParameterTypeDescription
task_idstringThe ID of the task to query, obtained from the buffer written by startFileTranscriber.
  • Return value
An error code. See Error code reference.

cancelFileTranscriber

Immediately cancels the current task.
  • Method signature
public cancelFileTranscriber(task_id: string): number
  • Parameter descriptions
ParameterTypeDescription
task_idstringThe ID of the task to cancel.
  • Return value
An error code. See Error code reference.

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
  • Return value
An error code. See Error code reference.

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
ParameterTypeDescription
eventConstants.NuiEventThe callback event.
resultCodenumberThe error code. This parameter is valid when EVENT_ASR_ERROR occurs.
finishnumberIndicates whether the task has ended.
asrResultAsrResultThe speech recognition result.
taskIdstringThe task ID.

Constants.NuiEvent

HarmonyOS SDK event types are defined by the Constants.NuiEvent enumeration. The following events apply to audio file transcription:
EventDescription
EVENT_FILE_TRANS_CONNECTEDThe service is connected.
EVENT_FILE_TRANS_UPLOADEDThe audio file to recognize is uploaded.
EVENT_FILE_TRANS_QUERY_RESULTThe task query result.
EVENT_FILE_TRANS_RESULTThe final recognition result.
EVENT_ASR_ERRORAn error occurs during speech recognition.

Auxiliary types

Constants.LogLevel

The enumeration values for the level parameter are as follows:
ValueDescription
LOG_LEVEL_VERBOSEThe most detailed logs.
LOG_LEVEL_DEBUGDebug logs.
LOG_LEVEL_INFOInformational logs (default).
LOG_LEVEL_WARNINGWarning logs.
LOG_LEVEL_ERRORError logs.
LOG_LEVEL_NONEDisables 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.
API Usage
Text Generation
Image Generation
  • FAQ
Video Generation
World models
Audio
Real-time Multimodal
Realtime API
Text Embedding
More Models
Toolkit/Framework
TokenPlan
Model Production
File Management
Billing
Model Management
More