File transcription iOS SDK for Qwen-Audio-3.0-ASR-Flash-Filetrans/Fun-ASR
User guide: Non-real-time speech recognition. For input requirements such as supported audio formats, file size limits, and duration limits, see Audio specifications.
Configure these parameters by passing a JSON string in the
Configure all speech recognition parameters through the nui_file_trans_start interface.
Initializes the speech recognition SDK instance. The SDK is a singleton. Do not initialize it again before you call nui_release.
Use this interface to set or update the
Starts recognition.
Use this interface to actively query the current status and result of an asynchronous task. After a successful call, the result is returned through the
Cancels the current task immediately.
Releases all internal SDK resources and forcibly terminates all ongoing tasks. After you call this method, the SDK instance becomes unavailable. To use it again, you must call nui_initialize again to initialize it.
Gets the current SDK version information.
Use this callback to receive detailed internal SDK logs for troubleshooting and debugging.
Quick start
- Get an API Key:Obtain an API key
-
Download the SDK and run the sample code:
- Download the latest SDK bundle.
- Unzip the ZIP package and add the included nuisdk.framework to your project.
- Under Build Phases → Link Binary With Libraries, add
nuisdk.xcframework. - Under General → Frameworks, Libraries, and Embedded Content, set
nuisdk.xcframeworkto Embed & Sign. - Open the sample project in Xcode. The sample code is located in
DashFunAsrFileTranscriberViewController.m. Replace the API Key to try out the feature.
Call steps
- Synchronous mode
- Asynchronous mode
- Initialize the SDK.
- Configure the relevant parameters for your use case.
- Set
async_requesttofalseand call nui_file_trans_start to submit a non-real-time speech recognition request and wait for the result. - In the onFileTransEventCallback callback, listen for the
EVENT_FILE_TRANS_RESULTevent to get the final recognition result. - Call nui_release to release the SDK resources.
Request parameters
Connection and control parameters
Configure these parameters by passing a JSON string in the parameters argument of the nui_initialize interface.
- Example parameters: The following is a sample JSON string. Not all parameters are listed. Add the ones you need when you write your code:
- Parameter descriptions
| Parameter | Type | Required | Description |
|---|---|---|---|
url | String | Yes | The endpoint. This is fixed at wss://maas.qwencloudapi.com/api/v1/services/audio/asr/transcription. |
apikey | String | Yes | The API Key. |
service_mode | String | Yes | The run mode. Fixed to "1" for non-real-time speech recognition. |
device_id | String | Yes | A unique string that identifies the end user. Set it to an in-app user ID or a device identifier generated by the client. This ID is used mainly for log tracing and troubleshooting. |
debug_path | String | No | The storage path for the log file. This parameter takes effect only when save_log is set to YES when you call the nui_initialize interface. In that case, you must set the log file path; otherwise, an error is returned.A maximum of two log files are kept locally. |
max_log_file_size | int | No | The maximum size of the log file, in bytes. This parameter takes effect only when save_log is set to YES when you call the nui_initialize interface.Default value: 104857600 (100 * 1024 * 1024 bytes, that is, 100 MiB). |
log_track_level | int | No | Controls the filter level of the log content sent out through the log callback (onFileTransLogTrackCallback). Default value: 2. Valid values:
Note: log_track_level and level (set through the nui_initialize interface) together determine which logs are ultimately sent to the callback. A log's level value must be greater than or equal to both log_track_level and level before it is sent to the callback. For example, if log_track_level is set to 2 (INFO) and level is set to 3 (WARNING), only logs at WARNING or higher (value >= 3) are sent to the callback. |
Speech recognition effect parameters
Configure all speech recognition parameters through the nui_file_trans_start interface.
- Example parameters: The following is a sample JSON string. Not all parameters are listed. Add the ones you need when you write your code:
- Parameter descriptions
| Parameter | Type | Required | Description |
|---|---|---|---|
file_urls | array[string] | Yes | A list of URLs of the audio or video files to transcribe. HTTP and HTTPS are supported. A single request supports only one URL. For input requirements such as supported audio formats, file size limits, and duration limits, see Audio specifications. If the recording is stored in Alibaba Cloud OSS, the RESTful API supports temporary URLs prefixed with oss://, whereas the SDK does not support oss://-prefixed temporary URLs.
The SDK does not support configuring request headers. |
async_request | boolean | No | Whether the speech recognition request is asynchronous. Default value: false.Valid values:
|
apikey | string | No | If the apikey in Connection and control parameters is a temporary API Key, you can update it here to prevent it from expiring. |
nls_config | object | Yes | The core speech recognition configuration object. It contains key parameters such as model selection and recognition effect controls. |
nls_config.model | string | Yes | The model name. Supported values include the Qwen-Audio-3.0-ASR-Flash-Filetrans and Fun-ASR model families. For details, see Supported models and regions. |
nls_config.special_word_filter | object | No | The sensitive words to process during speech recognition. You can set a different handling method for each sensitive word. For details, see Sensitive word filtering. |
nls_config.channel_id | array[integer] | No | The index of the audio tracks to recognize in a multi-track audio file. The index starts at 0. For example, [0] recognizes the first track, and [0, 1] recognizes the first and second tracks at the same time. If you omit this parameter, only the first track is processed. Each specified track is billed independently. For example, requesting [0, 1] for a single file incurs two separate charges. Default value: [0]. |
nls_config.diarization_enabled | boolean | No | Whether to enable speaker diarization. Disabled by default. Applies only to mono audio. Multi-channel audio does not support speaker diarization. When enabled, the recognition result includes a speaker_id field that distinguishes different speakers.When speaker diarization is enabled, keep the audio duration within 2 hours. Otherwise, recognition may fail or time out. Default value: false. For an example of speaker_id, see Recognition result description. |
nls_config.speaker_count | integer | No | Takes effect only when speaker diarization is enabled ( diarization_enabled is set to true).A reference value for the number of speakers. The valid range is an integer from 2 to 100 (inclusive). By default, the number of speakers is detected automatically. If you set this value, it only guides the algorithm to output the specified count when possible and does not guarantee that exact count. No default value. |
nls_config.vocabulary_id | string | No | The ID of a precompiled hot word list. Generate this ID in advance by calling the create hot word list API. Pass the ID during recognition to use the hot words in the list. Suitable for scenarios where the vocabulary is known and relatively stable, and where you need to reuse the same word list across requests. For usage details, see Precompiled hotwords. |
nls_config.input_context | array | No | A list of messages containing optional conversation context to improve recognition accuracy. Context helps improve recognition of domain-specific terms. For usage, see Context enhancement. You can include up to 5 messages of each context type: input_text and text. If this limit is exceeded, only the most recent 5 messages of each type are retained. The combined length of the text fields in the user and assistant messages in each turn must not exceed 400 characters. Each character counts as 1. Excess text is truncated from the end.When you include context, arrange messages by conversation turn. In each turn, the user message (input_text type) must precede the corresponding assistant message (text type). The user message containing input_audio must be the last message in the messages array.See the example below this table. |
nls_config.instant_vocabulary | object | No | Instant hotwords, passed as key-value pairs. Each key is the hotword text (string), and each value is its weight (integer). No precompiled hotword list is required. Use this parameter for temporary, session-level hotwords.Valid weights are integers from 1 to 5, or 50. A higher weight from 1 to 5 makes the model more likely to output the hotword. A weight of 50 defines a super hotword and significantly improves recall. You can specify up to 50 super hotwords. If you also configure precompiled hotwords, the two sets are merged. If the merged set exceeds 2000 hotwords, 2000 are selected at random. For usage, see Instant hotwords. Only qwen-audio-3.0-asr-flash-filetrans supports instant hotwords.See the example below this table. |
nls_config.language_hints | array[string] | No | The language codes to recognize. If you can't determine the language in advance, leave it unset and the model detects the language automatically. For Qwen-Audio-3.0-ASR-Flash-Filetrans models, you can set up to 4 values; any values beyond the first 4 are ignored. For Fun-ASR models, you can set only 1 value; if you set multiple, only the first takes effect.
Click to view the supported language codes
|
nls_config.input_context example:
nls_config.instant_vocabulary example:
Key interfaces
NeoNui
nui_initialize
Initializes the speech recognition SDK instance. The SDK is a singleton. Do not initialize it again before you call nui_release.
- Method signature
- Parameter descriptions
| Parameter | Type | Description |
|---|---|---|
parameters | char* | A JSON string that contains the authentication, connection, and debugging parameters. See Connection and control parameters. |
level | NuiSdkLogLevel | Controls the print level of the SDK's own logs. |
save_log | BOOL | Whether to save logs locally. If set to YES, you must specify a path through debug_path in Connection and control parameters, and you can set the file size through max_log_file_size. |
- Return value Returns an error code. See Error code reference.
nui_set_params
Use this interface to set or update the nls_config parameter independently. If you provide all parameters at once in nui_file_trans_start, you don't need to call this method.
- Method signature
- Parameter descriptions
| Parameter | Type | Description |
|---|---|---|
params | char* | The nls_config parameter in Speech recognition effect parameters. Parameters other than nls_config cannot be set through this method.See the example below this table. |
params example:
- Return value Returns an error code. See Error code reference.
nui_file_trans_start
Starts recognition.
- Method signature
- Parameter descriptions
| Parameter | Type | Description |
|---|---|---|
params | char* | Speech recognition effect parameters. See the example below this table. |
task_id | char* | The task ID. The SDK generates a random string internally and returns the task_id when this interface is called successfully. |
params example:
- Return value Returns an error code. See Error code reference.
nui_file_trans_query
Use this interface to actively query the current status and result of an asynchronous task. After a successful call, the result is returned through the EVENT_FILE_TRANS_QUERY_RESULT event in the onFileTransEventCallback callback.
Obtain the
task_id passed to this method from the EVENT_FILE_TRANS_UPLOADED event.- Method signature
- Parameter descriptions
| Parameter | Type | Description |
|---|---|---|
task_id | char* | The ID of the task to query, obtained from the EVENT_FILE_TRANS_UPLOADED event. |
- Return value Returns an error code. See Error code reference.
nui_file_trans_cancel
Cancels the current task immediately.
- Method signature
- Parameter descriptions
| Parameter | Type | Description |
|---|---|---|
task_id | char* | The ID of the task to cancel, obtained from the EVENT_FILE_TRANS_UPLOADED event. |
- Return value Returns an error code. See Error code reference.
nui_release
Releases all internal SDK resources and forcibly terminates all ongoing tasks. After you call this method, the SDK instance becomes unavailable. To use it again, you must call nui_initialize again to initialize it.
- Method signature
- Return value Returns an error code. See Error code reference.
nui_get_version
Gets the current SDK version information.
- Method signature
- Return value The current SDK version information.
NeoNuiSdkDelegate: monitor callbacks
onFileTransEventCallback: monitor events and speech recognition results
- Method signature
- Parameter descriptions
| Parameter | Type | Description |
|---|---|---|
nuiEvent | NuiCallbackEvent | The callback event. |
asr_result | char* | The speech recognition result. |
task_id | char* | The task ID. |
finish | BOOL | Indicates whether this round of recognition has finished. |
code | int | The error code. It is valid when an EVENT_ASR_ERROR event occurs. See Error code reference. |
onFileTransLogTrackCallback: monitor trace logs
Use this callback to receive detailed internal SDK logs for troubleshooting and debugging.
NuiCallbackEvent: event types
| Event | Description |
|---|---|
| EVENT_FILE_TRANS_CONNECTED | Connected to the service successfully. |
| EVENT_FILE_TRANS_UPLOADED | The audio file to recognize was uploaded successfully. You can now obtain the task_id of the current task. |
| EVENT_FILE_TRANS_QUERY_RESULT | The query task result. |
| EVENT_FILE_TRANS_RESULT | The final recognition result. |
| EVENT_ASR_ERROR | An error occurred during speech recognition. |