Extract the TAR archive. Obtain the SDK in HAR format from neonui and add it to your project dependencies. For C++ integration, use native/libs and native/include in the TAR archive to obtain the dynamic libraries and header files.
Open the project in DevEco Studio. The sample code is in DashFunAsrFlashFileTranscriberPage.ets. Replace the API key to try the feature.
Pass a JSON string to the initializeFileTrans method's parameters parameter to configure these settings.Parameter example: The following JSON string is an example and does not list all parameters. Add parameters as needed in your code:
The service endpoint. Set this parameter to wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation. Replace {WorkspaceId} with your actual Workspace ID.
apikey
string
Yes
The API key. We recommend using a short-lived, more secure temporary API key to reduce the risk of exposing a long-lived key.
service_mode
string
Yes
The operating mode. For non-real-time speech recognition, set this parameter to "1".
device_id
string
Yes
A unique string that identifies the end user. You can use an in-app user ID or a client-generated unique device identifier. This ID is mainly used for log tracing and troubleshooting.
debug_path
string
No
The path for log files. This parameter takes effect only when you call initializeFileTrans with save_log set to true. In this case, you must specify the log file path. Otherwise, an error occurs. Up to two log files are retained locally.
max_log_file_size
number
No
The maximum log file size in bytes. This parameter takes effect only when you call initializeFileTrans with save_log set to true. Default: 104857600 (100 * 1024 * 1024 bytes, or 100 MiB).
Use setParams to configure nls_config parameters, or use startFileTranscriber to configure all recognition parameters.Parameter example: The following JSON string is an example and does not list all parameters. Add parameters as needed in your code:
If Connection and control parameters apikey uses temporary API key, you can update it here to prevent expiration.
nls_config
object
Yes
The core speech recognition configuration object, including the model and parameters that control recognition.
nls_config.model
string
Yes
The model name.
nls_config.format
string
Yes
The audio format. Set this parameter to the actual format. Supported formats include wav, mp3, opus. For details, see Audio specifications.
nls_config.sample_rate
string
No
The audio sample rate in Hz. For example, 16000 indicates a sample rate of 16 kHz. For details, see Audio specifications.
nls_config.vocabulary_id
string
No
The precompiled vocabulary ID. Create a vocabulary in advance and pass its ID during recognition to use its hotwords. Use this option when the vocabulary is known, relatively stable, and reused across requests. For usage instructions, see Precompiled hotwords.
nls_config.instant_vocabulary
object
No
Instant hotwords.Pass key-value pairs. The key is the hotword text (string) and the value is its weight (integer). You do not need to create a vocabulary in advance. Valid weights are [1, 5] or 50. Within [1, 5], a higher weight makes the model more likely to output the word. A weight of 50 specifies a super hotword and significantly increases recall. You can specify up to 50 super hotwords.Use this option for temporary, session-level hotword optimization.When both instant and precompiled hotwords are configured, the system merges them. If the merged list exceeds 2000 entries, it randomly selects 2000 entries. For usage instructions, see Instant hotwords.
Copy
{ "张三": 5, "李四": 5}
nls_config.language_hints
array[string]
No
The language codes to recognize. If the language is unknown in advance, omit this parameter to let the model detect it automatically. You can set up to 4 values. If you set more, only the first 4 take effect.Specifying language codes can improve recognition accuracy.
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
qwen-audio-3.1-asr-flash also supports the following language codes:
tr: Turkish
fa: Persian
mr: Marathi
ml: Malayalam
ne: Nepali
ky: Kyrgyz
az: Azerbaijani
ka: Georgian
hy: Armenian
sl: Slovenian
sq: Albanian
et: Estonian
lv: Latvian
lt: Lithuanian
ca: Catalan
eu: Basque
gl: Galician
or: Odia
dv: Divehi
as: Assamese
ku: Kurdish
tig: Tigre
fy: Western Frisian
ba: Bashkir
be: Belarusian
tt: Tatar
ia: Interlingua
mhr: Eastern Mari
tok: Toki Pona
messages
array[object]
Yes
The list of messages. It contains the audio to recognize and optional conversation context to improve recognition.See the following descriptions.
messages parameters:
Context improves the recognition accuracy of specialized terms. For usage instructions, see Context enhancement.Context messages (input_text and text types) are limited to five each. If the limit is exceeded, only the five most recent messages are retained. The total context text length per turn (the sum of the user and assistanttext field lengths) must not exceed 400 characters. Each character counts as one. Excess characters are truncated from the end.
When context is included, messages messages must follow a specific order. Arrange context messages by conversation turn. Within each turn, user (input_text type) must precede the corresponding assistant (text type). The input_audiouser message containing input audio must be placed at the end of messages .
Parameter
Type
Required
Description
role
string
Yes
The message role. Valid values:
user (required): A user message. When type is input_audio, it represents the audio to recognize. When type is input_text, it represents recognition results from previous turns or a domain-specific vocabulary (optional context).
assistant (optional context): Large language model responses from previous turns.
content
array[object]
Yes
The list of message content. See the following descriptions.
content parameters:
Parameter
Type
Required
Description
type
string
Yes
The content type. Each request requires at least one input_audio message. Valid values:
input_audio (required): The audio input to recognize (role is user). You must also provide the input_audio object.
input_text (optional context): Recognition results of user speech from previous turns or a domain-specific vocabulary (role is user). You must also provide the text field.
text (optional context): Large language model responses from previous turns (role is assistant). You must also provide the text field.
input_audio
object
No
Required when type is input_audio.
input_audio.data
string
Yes
The audio data to recognize. For supported audio formats, file size limits, duration limits, and other input requirements, see Audio specifications. The following two input methods are supported:
Audio file URL: Pass a publicly accessible audio file URL.
Base64 Data URI: Pass Base64-encoded audio as a Data URI. Concatenate the data:{MIME_TYPE};base64, prefix with the Base64-encoded audio data. Supported MIME types include audio/wav, audio/mp3.Example (URL): https://example.com/audio/sample.wavExample (Base64): data:audio/wav;base64,{BASE64_ENCODED_DATA}
text
string
No
Required when type is input_text, provide recognition results of user speech from previous turns or a domain-specific vocabulary. When type is text, provide large language model responses from previous turns. Text length is counted in characters, with each character counting as one. The total length of all messages' text fields in each context turn must not exceed 400 characters. Excess characters are truncated from the end.
Unlike real-time speech recognition, non-real-time (recorded-file) transcription requires initializeFileTrans with an INativeFileTransCallback callback instead of initialize.
This method blocks. Call it from a non-UI thread.Method signature
Copy
public initializeFileTrans(callback: INativeFileTransCallback, parameters: string, level: number, save_log: boolean = false): number
Parameters
Parameter
Type
Description
callback
INativeFileTransCallback
The implementation of the file transcription event and data callback interface.
parameters
string
A JSON string containing authentication, connection, and debugging parameters. See Connection and control parameters.
level
number
The SDK log level. Use a value from the enumeration.
save_log
boolean
Whether to save logs locally. If set to true, use Connection and control parameters to set debug_path to specify the path, and use max_log_file_size to set the file size.
Use this method to set or update nls_config separately. You do not need to call this method if all parameters are provided in startFileTranscriber in a single call.Method signature
Copy
public setParams(params: string): number
Parameters
Parameter
Type
Description
params
string
Recognition parameters in nls_config parameters; parameters outside nls_config cannot be set with this method.
The task ID buffer. The SDK writes an internally generated random task ID string to this buffer. Its byte length must be >= 33 bytes (the example uses new ArrayBuffer(64)). After a successful call, decode the buffer to obtain the task's task_id.
Use this method to query the current status and result of an asynchronous task. After a successful call, the result is returned through the onFileTransEventCallback callback's EVENT_FILE_TRANS_QUERY_RESULT event.Method signature
Copy
public queryFileTranscriber(task_id: string): number
Parameters
Parameter
Type
Description
task_id
string
The ID of the task to query (written to the buffer by startFileTranscriber ).
Release all internal SDK resources. After this call, the SDK instance becomes unavailable. To use it again, call initializeFileTrans to initialize it again.Method signature
onFileTransLogTrackCallback: Listen for tracing logs
This callback receives detailed internal SDK logs for troubleshooting and debugging.To use this callback, download the HarmonyOS SDK package dated 20260908 or later.
