SDK de Android para reconocimiento de voz no en tiempo real (Qwen-Audio-3.x-ASR-Flash/Fun-ASR-Flash) - Alibaba Cloud Model Studio

El SDK de Android para reconocimiento de voz no en tiempo real Qwen-Audio-3.x-ASR-Flash/Fun-ASR-Flash convierte el habla en texto.

Guía del usuario: Reconocimiento de voz no en tiempo real. Para formatos de audio admitidos, límites de tamaño de archivo, límites de duración y otros requisitos de entrada, consulte Especificaciones de audio.

Inicio rápido

Obtener una clave API: Obtener una clave API. Por seguridad, recomendamos configurar la clave API en una variable de entorno.
Descargue el SDK y ejecute el código de ejemplo:
- Descargue el paquete más reciente del SDK.
- Extraiga el archivo ZIP. Obtenga el SDK en formato AAR de app/libs y agréguelo a las dependencias de su proyecto. Para la integración Android CPP, use android_libs y android_include en el archivo ZIP para obtener las bibliotecas dinámicas y los archivos de encabezado.
- Abra el proyecto en Android Studio. El código de ejemplo se encuentra en DashFunAsrFlashFileTranscriberActivity.java. Reemplace la clave de API para probar la función.

Procedimiento de llamada

Modo síncrono

Inicializar el SDK
Configure los parámetros según sus requisitos comerciales
Llame a startFileTranscriber para enviar una solicitud de reconocimiento de voz no en tiempo real y esperar el resultado.
Use onFileTransEventCallback para escuchar el evento EVENT_FILE_TRANS_RESULT y obtener el resultado final del reconocimiento.
Llame a release para liberar los recursos del SDK

Parámetros de solicitud

Parámetros de conexión y control

Pase una cadena JSON al parámetro parameters del método initialize para configurar estos ajustes.

Ejemplo de parámetro: La siguiente cadena JSON es un ejemplo y no enumera todos los parámetros. Agregue parámetros según sea necesario en su código:

{
    "url": "wss://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
`url`	`String`	Sí	Endpoints de servicio: `wss://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation` China (Pekín): `wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com`/api/v1/services/aigc/multimodal-generation/generation Singapur: `wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation` Reemplace `{WorkspaceId}` con su ID de espacio de trabajo.
`apikey`	`String`	Sí	Clave de API.
`service_mode`	`String`	Sí	El modo de operación. Para el reconocimiento de voz no en tiempo real, establezca este parámetro en `"1"`.
`device_id`	`String`	Sí	Una cadena única que identifica al usuario final. Puede usar un ID de usuario dentro de la aplicación o un identificador de dispositivo único generado por el cliente. Este ID se utiliza principalmente para el rastreo de registros y la resolución de problemas.
`debug_path`	`String`	No	La ruta para los archivos de registro. Este parámetro solo tiene efecto cuando llama a initialize con `save_log` establecido en true. En este caso, debe especificar la ruta del archivo de registro. De lo contrario, se producirá un error. Se conservan hasta dos archivos de registro localmente.
`max_log_file_size`	`int`	No	El tamaño máximo del archivo de registro en bytes. Este parámetro solo tiene efecto cuando llama a initialize con `save_log` establecido en true. Valor predeterminado: 104857600 (100 * 1024 * 1024 bytes, o 100 MiB).
`log_track_level`	`int`	No	El nivel de filtrado para los registros enviados a través del callback de registro (`onFileTransLogTrackCallback`). Valor predeterminado: 2. Valores válidos: - 0: LOG_LEVEL_VERBOSE - 1: LOG_LEVEL_DEBUG - 2: LOG_LEVEL_INFO - 3: LOG_LEVEL_WARNING - 4: LOG_LEVEL_ERROR - 5: LOG_LEVEL_NONE (desactiva esta función). Nota: `log_track_level` y `level` (configurados a través del método initialize) determinan conjuntamente qué registros se entregan. El nivel numérico de un registro debe ser mayor o igual tanto a `log_track_level` como a `level` para que el registro se entregue. Por ejemplo, si `log_track_level` está establecido en 2 (INFO) y `level` está establecido en 3 (WARNING), solo se entregan registros de WARNING y de mayor severidad (nivel numérico >= 3).

Parámetros de reconocimiento

Use startFileTranscriber para configurar todos los parámetros de reconocimiento.

Ejemplo de parámetro: La siguiente cadena JSON es un ejemplo y no enumera todos los parámetros. Agregue parámetros según sea necesario en su código:

{
  "apikey": "st-****",
  "messages": [
    {
      "content": [
        {
          "input_audio": {
            "data": "{YOUR_AUDIO_URL}"
          },
          "type": "input_audio"
        }
      ],
      "role": "user"
    }
  ],
  "nls_config": {
    "format": "mp3",
    "model": "qwen-audio-3.0-asr-flash"
  }
}

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
`apikey`	`string`	No	Si Parámetros de conexión y control `apikey` utiliza una clave API temporal, puede actualizarla aquí para evitar su caducidad.
`nls_config`	`object`	Sí	El objeto de configuración principal de reconocimiento de voz, que incluye el modelo y los parámetros que controlan el reconocimiento.
`nls_config.model`	`string`	Sí	El modelo utilizado en el ejemplo. Para información sobre modelos, consulte Modelos y regiones admitidos.
`nls_config.format`	`string`	Sí	El formato de audio. Establezca este parámetro en el formato real. Los formatos admitidos incluyen `wav`, `mp3`, `opus`. Para más detalles, consulte Especificaciones de audio.
`nls_config.sample_rate`	`string`	No	La frecuencia de muestreo de audio en Hz. Por ejemplo, `16000` indica una frecuencia de muestreo de 16 kHz. Para más detalles, consulte Especificaciones de audio.
`nls_config.vocabulary_id`	`string`	No	El ID de vocabulario precompilado. Cree un vocabulario con antelación y pase su ID durante el reconocimiento para usar sus palabras clave. Use esta opción cuando el vocabulario es conocido, relativamente estable y se reutiliza en varias solicitudes. Para instrucciones de uso, consulte Palabras clave precompiladas.
`nls_config.instant_vocabulary`	`object`	No	Palabras clave instantáneas. Pase pares clave-valor. La clave es el texto de la palabra clave (`string`) y el valor es su peso (`integer`). No necesita crear un vocabulario con antelación. Los pesos válidos son [1, 5] o 50. Dentro de [1, 5], un peso mayor hace que sea más probable que el modelo genere la palabra. Un peso de 50 especifica una súper palabra clave y aumenta significativamente la recuperación. Puede especificar hasta 50 súper palabras clave. Use esta opción para la optimización temporal de palabras clave a nivel de sesión. Cuando se configuran tanto palabras clave instantáneas como precompiladas, el sistema las fusiona. Si la lista fusionada excede 2000 entradas, selecciona aleatoriamente 2000 entradas. Para instrucciones de uso, consulte Palabras clave instantáneas. ImportantePara los modelos y límites aplicables a palabras clave instantáneas, consulte Palabras clave instantáneas. `{ "张三": 5, "李四": 5 }`
`nls_config.language_hints`	`array[string]`	No	Los códigos de idioma para el reconocimiento. Si el idioma se desconoce de antemano, omita este parámetro para permitir que el modelo lo detecte automáticamente. Para los modelos Qwen-Audio-3.0-ASR-Flash, se admiten hasta cuatro valores. Si se especifican más, solo los primeros cuatro tienen efecto. Para los modelos Fun-ASR-Flash, solo se admite un valor. Si se especifican múltiples valores, solo el primero tiene efecto. Qwen-Audio-3.x-ASR-Flash, fun-asr-flash-2026-06-15: zh: Chino en: Inglés ja: Japonés ko: Coreano vi: Vietnamita th: Tailandés id: Indonesio ms: Malayo tl: Filipino hi: Hindi ar: Árabe fr: Francés de: Alemán es: Español pt: Portugués ru: Ruso it: Italiano nl: Neerlandés sv: Sueco da: Danés fi: Finés no: Noruego el: Griego pl: Polaco cs: Checo hu: Húngaro ro: Rumano bg: Búlgaro hr: Croata sk: Eslovaco
messages	`array[object]`	Sí	La lista de mensajes. Contiene el audio a reconocer y el contexto de conversación opcional para mejorar el reconocimiento. Consulte las siguientes descripciones.

parámetros de messages:

ImportanteEl contexto mejora la precisión del reconocimiento de términos especializados. Para instrucciones de uso, consulte Mejora de contexto.

Restricciones: Los mensajes de contexto (tipos input_text y text) están limitados a cinco cada uno. Si se excede el límite, solo se conservan los cinco mensajes más recientes. La longitud total del texto de contexto por turno (la suma de las longitudes de los campos user y assistant text) no debe exceder 400 caracteres. Cada carácter cuenta como uno. Los caracteres excedentes se truncan desde el final.

ImportanteCuando se incluye contexto, los mensajes de messages deben seguir un orden específico. Organice los mensajes de contexto por turno de conversación. Dentro de cada turno, user (tipo input_text) debe preceder al correspondiente assistant (tipo text). El mensaje input_audio user que contiene el audio de entrada debe colocarse al final de messages.

Parámetro Tipo Obligatorio Descripción

Parámetro	Tipo	Obligatorio	Descripción
role	`string`	Sí	El rol del mensaje. Valores válidos: `user` (requerido): Un mensaje de usuario. Cuando type es `input_audio`, representa el audio a reconocer. Cuando type es `input_text`, representa resultados de reconocimiento de turnos anteriores o un vocabulario específico del dominio (contexto opcional). `assistant` (contexto opcional): Respuestas del modelo de lenguaje grande de turnos anteriores.
content	`array[object]`	Sí	La lista de contenido de mensajes. Consulte las siguientes descripciones.

role

string

Sí

El rol del mensaje. Valores válidos:

user (requerido): Un mensaje de usuario. Cuando type es input_audio, representa el audio a reconocer. Cuando type es input_text, representa resultados de reconocimiento de turnos anteriores o un vocabulario específico del dominio (contexto opcional).
assistant (contexto opcional): Respuestas del modelo de lenguaje grande de turnos anteriores.

content

array[object]

Sí

La lista de contenido de mensajes. Consulte las siguientes descripciones.

parámetros de content:

Parámetro	Tipo	Obligatorio	Descripción
type	`string`	Sí	El tipo de contenido. Cada solicitud requiere al menos un mensaje `input_audio` . Valores válidos: `input_audio` (requerido): La entrada de audio a reconocer (el rol es user). También debe proporcionar el objeto `input_audio`. `input_text` (contexto opcional): Resultados de reconocimiento del habla del usuario de turnos anteriores o un vocabulario específico del dominio (el rol es user). También debe proporcionar el campo `text`. `text` (contexto opcional): Respuestas del modelo de lenguaje grande de turnos anteriores (el rol es assistant). También debe proporcionar el campo `text`.
input_audio	`object`	No	Requerido cuando `type` es `input_audio`.
input_audio.data	string	Sí	Los datos de audio a reconocer. Para formatos de audio admitidos, límites de tamaño de archivo, límites de duración y otros requisitos de entrada, consulte Especificaciones de audio. Se admiten los siguientes dos métodos de entrada: URL del archivo de audio: Pase una URL de archivo de audio accesible públicamente. Data URI Base64: Pase audio codificado en Base64 como un Data URI. Concatene el prefijo `data:{MIME_TYPE};base64,` con los datos de audio codificados en Base64. Los tipos MIME admitidos incluyen `audio/wav`, `audio/mp3`. Ejemplo (URL): `https://example.com/audio/sample.wav` Ejemplo (Base64): `data:audio/wav;base64,{BASE64_ENCODED_DATA}`
text	`string`	No	Requerido cuando `type` es `input_text`, proporcione resultados de reconocimiento del habla del usuario de turnos anteriores o un vocabulario específico del dominio. Cuando `type` es `text`, proporcione respuestas del modelo de lenguaje grande de turnos anteriores. La longitud del texto se cuenta en caracteres, y cada carácter cuenta como uno. La longitud total de todos los campos `text` de los mensajes en cada turno de contexto no debe exceder 400 caracteres. Los caracteres excedentes se truncan desde el final.

Interfaces clave

NativeNui

initialize

Inicialice la instancia del SDK de reconocimiento de voz. El SDK utiliza un singleton. No lo inicialice nuevamente antes de llamar a release.

Este método es bloqueante. Llámelo desde un hilo que no sea de UI.

Firma del método

public synchronized int initialize(final INativeFileTransCallback callback,
                                   String parameters,
                                   final Constants.LogLevel level,
                                   final boolean save_log)

Parámetros

Parámetro	Tipo	Descripción
`callback`	`INativeFileTransCallback`	La implementación de la interfaz de devolución de llamada de eventos y datos.
`parameters`	`String`	Una cadena JSON que contiene parámetros de autenticación, conexión y depuración. Consulte Parámetros de conexión y control.
`level`	`Constants.LogLevel`	El nivel de registros impresos por el SDK.
`save_log`	`boolean`	Indica si se deben guardar los registros localmente. Si se establece en `true`, use Parámetros de conexión y control para establecer `debug_path` y especificar la ruta, y use `max_log_file_size` para establecer el tamaño del archivo.

setParams

Use este método para establecer o actualizar nls_config por separado. No necesita llamar a este método si todos los parámetros se proporcionan en startFileTranscriber en una sola llamada.

Firma del método

public synchronized int setParams(String params);

Parámetros

Parámetro Tipo Descripción

Parámetro	Tipo	Descripción
`params`	`String`	Parámetros de reconocimiento en `nls_config` y parámetros de messages. Ejemplo: `{ "messages": [ { "content": [ { "input_audio": { "data": "{YOUR_AUDIO_URL}" }, "type": "input_audio" } ], "role": "user" } ], "nls_config": { "format": "mp3", "model": "qwen-audio-3.0-asr-flash" } }`

params

String

Parámetros de reconocimiento en nls_config y parámetros de messages.
Ejemplo:

{
  "messages": [
    {
      "content": [
        {
          "input_audio": {
            "data": "{YOUR_AUDIO_URL}"
          },
          "type": "input_audio"
        }
      ],
      "role": "user"
    }
  ],
  "nls_config": {
    "format": "mp3",
    "model": "qwen-audio-3.0-asr-flash"
  }
}

startFileTranscriber

Iniciar el reconocimiento.

Firma del método

public synchronized int startFileTranscriber(String params, byte[ ] task_id)

Parámetros

Parámetro Tipo Descripción

Parámetro	Tipo	Descripción
`params`	`String`	Parámetros de reconocimiento. Ejemplo: `{ "apikey": "st-****", "messages": [ { "content": [ { "input_audio": { "data": "{YOUR_AUDIO_URL}" }, "type": "input_audio" } ], "role": "user" } ], "nls_config": { "format": "mp3", "model": "qwen-audio-3.0-asr-flash" } }`
`task_id`	`byte[ ]`	Puede ignorar este parámetro y pasar null.

params

String

Parámetros de reconocimiento. Ejemplo:

{
  "apikey": "st-****",
  "messages": [
    {
      "content": [
        {
          "input_audio": {
            "data": "{YOUR_AUDIO_URL}"
          },
          "type": "input_audio"
        }
      ],
      "role": "user"
    }
  ],
  "nls_config": {
    "format": "mp3",
    "model": "qwen-audio-3.0-asr-flash"
  }
}

task_id

byte[ ]

Puede ignorar este parámetro y pasar null.

queryFileTranscriber

Esta función de reconocimiento de voz no en tiempo real solo admite solicitudes síncronas. Puede ignorar este método.

cancelFileTranscriber

Cancelar inmediatamente la tarea actual.

Firma del método

public synchronized int cancelFileTranscriber(String task_id)

Parámetros

Parámetro	Tipo	Descripción
`task_id`	`String`	El ID de la tarea a cancelar, obtenido de EVENT_FILE_TRANS_UPLOADED.

release

Libere todos los recursos internos del SDK. Después de esta llamada, la instancia del SDK deja de estar disponible. Para usarla nuevamente, llame a initialize para inicializarla de nuevo.

Firma del método

public synchronized int release();

GetVersion

Obtener la versión actual del SDK.

Firma del método

public synchronized String GetVersion();

Valor de retorno

La versión actual del SDK.

INativeFileTransCallback: Callbacks

onFileTransEventCallback: Escuchar eventos y resultados de reconocimiento

Firma del método

void onFileTransEventCallback(NuiEvent event, final int resultCode, final int arg2, AsrResult asrResult, String taskId);

Parámetros

Parámetro	Tipo	Descripción
`event`	`NuiEvent`	El evento de devolución de llamada.
`resultCode`	`int`	Válido solo cuando ocurre el evento `EVENT_ASR_ERROR`.
`asrResult`	`AsrResult`	El resultado del reconocimiento de voz.
`taskId`	`String`	El ID de la tarea.
`arg2`	`int`	Reservado.

onFileTransLogTrackCallback: Escuchar registros de rastreo

Este callback recibe registros internos detallados del SDK para resolución de problemas y depuración.

default void onFileTransLogTrackCallback(Constants.LogLevel level, String log)

Tipos de eventos

Evento	Descripción
EVENT_FILE_TRANS_CONNECTED	Conectado correctamente al servicio.
EVENT_FILE_TRANS_UPLOADED	El archivo de audio se cargó correctamente. Puede obtener el task_id actual en este punto.
EVENT_FILE_TRANS_RESULT	El resultado final del reconocimiento.
EVENT_ASR_ERROR	Ocurrió un error durante el reconocimiento de voz.