Todos los productos
Search
Centro de documentos

Alibaba Cloud Model Studio:SDK de Android de Qwen-Audio-TTS

Última actualización: Oct 12, 2026

Convierta texto en voz expresiva y de alta calidad en su aplicación para Android con el SDK de conversión de texto a voz (TTS) de Qwen-Audio-TTS.

NativeNui

El SDK admite múltiples instancias de NativeNui y utiliza devoluciones de llamada para entregar eventos de síntesis.

Aspectos destacados de la arquitectura:
  • Múltiples instancias: Cree una instancia llamando a new NativeNui(Constants.ModeType.MODE_STREAM_INPUT_TTS).

  • Impulsado por devoluciones de llamada: Reciba eventos y datos de audio a través de la interfaz INativeStreamInputTtsCallback.

  • Tipos de eventos:
    • STREAM_INPUT_TTS_EVENT_SYNTHESIS_STARTED: La tarea de síntesis ha comenzado.
    • onStreamInputTtsDataCallback: Se entregan los datos de audio.
    • STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE: La tarea de síntesis ha finalizado.
    • STREAM_INPUT_TTS_EVENT_TASK_FAILED: La tarea de síntesis ha fallado.

Flujo de uso

Qwen-Audio-TTS admite dos modos de invocación: entrada única y entrada en streaming.

Entrada única es adecuada para textos cortos y cualquier escenario que utilice marcado SSML.

  1. playStreamInputTts() o asyncPlayStreamInputTts() — envía un texto completo e inicia la síntesis. El primero es síncrono y retorna después de que finaliza la síntesis; el segundo es asíncrono y retorna inmediatamente después de iniciar la síntesis.
  2. onStreamInputTtsDataCallback() — recibir datos de audio.
  3. STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE — la síntesis ha finalizado.

Entrada en streaming es adecuada para escenarios de conversación en tiempo real y de formato largo "hablar sobre la marcha". SSML no es compatible con este modo.

  1. startStreamInputTts() — inicializar el SDK y configurar los parámetros de devolución de llamada y conexión.
  2. sendStreamInputTts() — enviar texto continuamente a medida que esté disponible.
  3. onStreamInputTtsDataCallback() — recibir datos de audio.
  4. stopStreamInputTts() o asyncStopStreamInputTts() — enviar la solicitud de fin de síntesis. El primero es síncrono y regresa después de que finaliza la síntesis; el segundo es asíncrono y regresa inmediatamente después de enviar la solicitud.
  5. STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE — la síntesis ha finalizado.

startStreamInputTts

Inicia la síntesis en streaming bidireccional, abre la conexión al servicio y registra la devolución de llamada para eventos y datos de audio.

Este método puede bloquearse. Llámelo en un hilo que no sea de UI.

Firma del método:
public synchronized int startStreamInputTts(INativeStreamInputTtsCallback callback,
                                            String ticket,
                                            String parameters,
                                            String session_id,
                                            int log_level,
                                            boolean save_log)
Parámetros:
ParámetroTipoDescripción
callbackINativeStreamInputTtsCallbackSu implementación de la interfaz de devolución de llamada de eventos y datos.
ticketStringUna cadena JSON que contiene configuraciones de autenticación, conexión y depuración. Consulte la referencia del parámetro ticket a continuación.
parametersStringUna cadena JSON que controla la salida de la síntesis de voz. Consulte la referencia de parámetros a continuación.
session_idStringUn ID de sesión especificado por el cliente. Si se omite, el servidor genera uno automáticamente.
log_levelintControla la verbosidad de los registros internos del SDK.

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 (deshabilita el registro)
save_logbooleanSi se deben escribir registros en un archivo local. Si es true, configure debug_path en el ticket para especificar el destino y, opcionalmente, configure max_log_file_size para limitar el tamaño del archivo.
Valor devuelto:

Devuelve un código de error.

ejemplo JSON del ticket:
{
    "url": "wss://dashscope.aliyuncs.com/api-ws/v1/inference",
    "apikey": "sk-****",
    "device_id": "my_device_id"
}
parámetros del ticket:
ParámetroTipoObligatorioDescripción
urlStringSíDirección del servicio:
  • wss://dashscope.aliyuncs.com/api-ws/v1/inference
  • China (Beijing): wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference
  • Singapur: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference

Reemplace {WorkspaceId} con su ID de espacio de trabajo real.

apikeyStringSíSu clave API. Para limitar el radio de impacto si se expone una clave de larga duración, utilice en su lugar una clave API temporal de corta duración.
device_idStringSíUn identificador único para el usuario final. Configúrelo con su ID de usuario dentro de la aplicación o con un identificador de dispositivo generado por el cliente. Este ID se utiliza principalmente para la correlación de registros y la resolución de problemas.
complete_waiting_msintNoDespués de llamar al método stop, el tiempo en milisegundos para esperar el evento STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE antes de que se agote el tiempo de espera.

Predeterminado: 10000.

debug_pathStringNoLa ruta local donde se escriben los archivos de registro.

Este parámetro solo surte efecto cuando save_log se establece en true para startStreamInputTts, playStreamInputTts o asyncPlayStreamInputTts. En ese caso, la ruta es obligatoria; de lo contrario, la llamada devuelve un error.

Se conservan como máximo dos archivos de registro en el dispositivo.

max_log_file_sizeintNoEl tamaño máximo del archivo de registro en bytes.

Este parámetro surte efecto solo cuando save_log se establece en true para startStreamInputTts, playStreamInputTts o asyncPlayStreamInputTts.

Predeterminado: 104857600 (100 × 1024 × 1024 bytes, o 100 MiB).

log_track_levelintNoNivel de filtro para los registros que se entregan a través de la devolución de llamada de registro (onStreamInputTtsLogTrackCallback).

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 (deshabilita el registro)

Nota: log_track_level funciona junto con log_level (establecido en startStreamInputTts, playStreamInputTts o asyncPlayStreamInputTts) para decidir qué registros llegan al callback. Una entrada de registro debe tener un nivel igual o superior tanto a log_track_level como a log_level para ser entregada. Por ejemplo, si log_track_level es 2 (INFO) y log_level es 3 (WARNING), solo WARNING y superiores (nivel >= 3) llegan al callback.

ejemplo JSON de parámetros:
{
    "model": "qwen-audio-3.0-tts-flash",
    "voice": "longanlingxi",
    "format": "mp3",
    "volume": 50,
    "rate": 1.0,
    "pitch": 1.0
}
referencia de parámetros:
ParámetroTipoObligatorioDescripción
modelStringSíEl nombre del modelo.
voiceStringSíLa voz utilizada para la síntesis de habla.
  • Voces del sistema: Consulte la lista de voces de Qwen-Audio-TTS
  • Voces clonadas: Voces personalizadas creadas mediante clonación de voz
  • Voces personalizadas: Voces personalizadas creadas mediante diseño de voz
formatStringNoEl formato de codificación de audio.

Valores válidos:

  • pcm
  • wav
  • mp3 (predeterminado)
  • opus
enable_audio_decoderbooleanNoSi se debe habilitar el decodificador interno del SDK. Valor predeterminado: false.

Este parámetro surte efecto solo cuando el formato de codificación de audio es opus o mp3. Cuando está habilitado, el SDK decodifica los datos de audio opus o mp3 en datos PCM antes de devolverlos.

volumeintNoEl nivel de volumen.

Valor predeterminado: 50.

Valores válidos: [0, 100].

sample_rateintNoLa tasa de muestreo de audio en Hz.

Valores válidos: 8000, 16000, 22050 (predeterminado), 24000, 44100, 48000.

ratefloatNoLa velocidad del habla.

Valor predeterminado: 1.0.

Valores válidos: [0.5, 2.0].

pitchfloatNoEl tono.

Valor predeterminado: 1.0.

Valores válidos: [0.5, 2.0].

bit_rateintNoLa tasa de bits de audio en kbps. Cuando el formato de audio es mp3 u opus, utilice bit_rate para ajustar la tasa de bits.

Valor predeterminado: 32.

Valores válidos: [6, 510].

enable_ssmlbooleanNoSi se debe habilitar SSML.

Predeterminado: false.

  • true: habilitado.
  • false: deshabilitado.

Para las restricciones de uso de SSML (modelos, voces y API compatibles), consulte Limitaciones.

word_timestamp_enabledbooleanNoEspecifica si se deben habilitar las marcas de tiempo a nivel de palabra.

Valor predeterminado: false.

Disponible solo en modo de salida por streaming. Se admiten voces clonadas. Para voces del sistema compatibles, consulte la lista de voces de Qwen-Audio-TTS.

Las marcas de tiempo de palabras se devuelven en el campo all_response de INativeStreamInputTtsCallback.

seedintNoUna semilla aleatoria para controlar la variación en la salida de la síntesis. Cuando la versión del modelo, el texto, la voz y otros parámetros no cambian, usar la misma semilla produce resultados idénticos.

Valor predeterminado: 0.

Valores válidos: [0, 65535].

language_hintsString[]No

Importante

  • Este parámetro es una matriz, pero la versión actual solo procesa el primer elemento. Pase un único valor.
  • Este parámetro especifica el idioma de destino para la síntesis de voz. No está relacionado con el idioma de la muestra de audio utilizada en la clonación de voz. Para establecer el idioma de origen de una tarea de clonación, consulte la referencia de la API de clonación de voz.

Especifica el idioma objetivo para la síntesis de voz con el fin de mejorar la calidad de salida.

Cuando la pronunciación de dígitos, la expansión de abreviaturas, la lectura de símbolos o la síntesis en idiomas minoritarios no cumpla con las expectativas, utilice este parámetro. Por ejemplo:

  • Pronunciación inesperada de dígitos: "hola, esto es 110" se lee como "hola, esto es uno cero" en lugar de la pronunciación china esperada
  • Pronunciación incorrecta de símbolos: "@" se lee como su equivalente en chino en lugar de "arroba"
  • Mala calidad de síntesis en idiomas minoritarios con resultados poco naturales

Valores válidos

  • zh: Chino
  • en: Inglés
  • fr: Francés
  • de: Alemán
  • ja: Japonés
  • ko: Coreano
  • ru: Ruso
  • pt: Portugués
  • th: Tailandés
  • id: Indonesio
  • vi: Vietnamita
  • es: Español
  • it: Italiano
  • ms: Malayo
  • fil: Filipino
  • ar: Árabe
instructionStringNoControla las características de la síntesis, como el dialecto, la emoción o el estilo de habla.

Para detalles de uso, consulte Control de instrucciones.

enable_aigc_tagbooleanNoEspecifica si se debe incrustar una marca de agua AIGC en el audio generado. Cuando se establece en true, la marca de agua se incrusta en archivos de audio de formatos compatibles (wav/mp3/opus).

Valor predeterminado: false.

aigc_propagatorStringNoEstablece el campo ContentPropagator en la marca de agua AIGC, identificando al propagador del contenido. Surte efecto solo cuando enable_aigc_tag es true.

Valor predeterminado: UID de Alibaba Cloud.

aigc_propagate_idStringNoEstablece el campo PropagateID en la marca de agua AIGC, identificando de manera única una acción de propagación específica. Surte efecto solo cuando enable_aigc_tag es true.

Valor predeterminado: El ID de solicitud de la solicitud actual de síntesis de voz.

hot_fixobjectNoConfiguración de corrección rápida de texto para personalizar la pronunciación de palabras especificadas o reemplazar texto antes de la síntesis.

Campos:

  • pronunciation: Especifica anotaciones pinyin para palabras cuya pronunciación predeterminada necesita corrección.
  • replace: Reemplaza palabras especificadas antes de la síntesis. El texto de reemplazo se utiliza como la entrada real de la síntesis.

Ejemplo:

"hot_fix": {
  "pronunciation": [
    {"天气": "tian1 qi4"}
  ],
  "replace": [
    {"今天": "金天"}
  ]
}

sendStreamInputTts

Envía el texto que se va a sintetizar. Utilice este método junto con startStreamInputTts.

Después de llamar a startStreamInputTts, llame a este método para enviar texto continuamente.

Cuando haya enviado todo el texto, llame a stopStreamInputTts o asyncStopStreamInputTts para finalizar la entrada.

Firma del método:
public synchronized int sendStreamInputTts(String text)
Parámetros:
ParámetroTipoDescripción
textStringTexto a sintetizar. SSML no es compatible. Las etiquetas SSML en la entrada se leen en voz alta como texto sin formato en lugar de ser analizadas.
Valor devuelto:

Devuelve un código de error.

stopStreamInputTts

Método síncrono que indica al servidor que se ha enviado todo el texto y se bloquea hasta que se haya sintetizado todo el audio y se reciba el evento STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE.

El tiempo de espera es controlado por complete_waiting_ms.

Firma del método:
public synchronized int stopStreamInputTts()
Valor devuelto:

Devuelve un código de error.

asyncStopStreamInputTts

Método asíncrono que indica al servidor que se ha enviado todo el texto. La llamada regresa inmediatamente y la síntesis continúa en segundo plano.

Utilice el evento STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE para detectar cuándo ha finalizado la síntesis.

Firma del método:
public synchronized int asyncStopStreamInputTts()
Valor devuelto:

Devuelve un código de error.

cancelStreamInputTts

Cierra inmediatamente la conexión al servidor y aborta la tarea de síntesis actual. No se entregan más devoluciones de llamada de audio después de esta llamada.

Firma del método:
public synchronized int cancelStreamInputTts()
Valor devuelto:

Devuelve un código de error.

playStreamInputTts

Método de síntesis única síncrono. La llamada envía el texto, se bloquea mientras se recibe el audio y regresa solo después de que la síntesis ha finalizado. No necesita llamar al método stop posteriormente.

SSML está habilitado de forma predeterminada para este método. Para anularlo, configure enable_ssml explícitamente.

Llame a este método en un hilo que no sea de UI.

Firma del método:
public synchronized int playStreamInputTts(INativeStreamInputTtsCallback callback,
                                           String ticket,
                                           String parameters,
                                           String text,
                                           String session_id,
                                           int log_level,
                                           boolean save_log)
Parámetros:

La devolución de llamada, el ticket y otros parámetros compartidos tienen el mismo significado que en startStreamInputTts.

ParámetroTipoDescripción
textStringTexto a sintetizar. Admite SSML.
Valor devuelto:

Devuelve un código de error.

asyncPlayStreamInputTts

Método de síntesis única asíncrono. La llamada regresa inmediatamente, la síntesis se ejecuta en segundo plano y los resultados se entregan a través de la devolución de llamada. No necesita llamar al método stop posteriormente.

SSML está habilitado de forma predeterminada para este método. Para anularlo, configure enable_ssml explícitamente.

Firma del método:
public synchronized int asyncPlayStreamInputTts(INativeStreamInputTtsCallback callback,
                                           String ticket,
                                           String parameters,
                                           String text,
                                           String session_id,
                                           int log_level,
                                           boolean save_log)
Parámetros:

La devolución de llamada, el ticket y otros parámetros compartidos tienen el mismo significado que en startStreamInputTts.

ParámetroTipoDescripción
textStringTexto a sintetizar. Admite SSML.
Valor devuelto:

Devuelve un código de error.

INativeStreamInputTtsCallback

La interfaz de devolución de llamada TTS en streaming de Qwen-Audio-TTS entrega eventos de síntesis, datos de audio y registros.

onStreamInputTtsEventCallback: recibir eventos

Firma del método:
void onStreamInputTtsEventCallback(StreamInputTtsEvent event,
                                   String task_id,
                                   String session_id,
                                   int ret_code,
                                   String error_msg,
                                   String timestamp,
                                   String all_response);
Parámetros:
ParámetroTipoDescripción
eventStreamInputTtsEventEl evento que se está entregando.
task_idStringEl ID de la tarea de síntesis.
session_idStringEl ID de sesión. Se devuelve tal como lo proporcionó el cliente; generado por el servidor si se omite.
ret_codeintCódigo de error. Válido solo con el evento STREAM_INPUT_TTS_EVENT_TASK_FAILED.
error_msgStringMensaje de error. Válido solo con el evento STREAM_INPUT_TTS_EVENT_TASK_FAILED.
timestampStringInformación de marca de tiempo para el resultado de la síntesis.
all_responseStringLa respuesta JSON completa. Analícela para extraer cualquier dato adicional que necesite.

onStreamInputTtsDataCallback: recibir datos de audio

El SDK invoca esta devolución de llamada repetidamente durante la síntesis. Lea los datos de audio desde la devolución de llamada.

Firma del método:
void onStreamInputTtsDataCallback(byte[] data);
Parámetros:
ParámetroTipoDescripción
databyte[]Datos de audio para el segmento actual. Úselos para:
  • Ensamble un archivo de audio completo y reprodúzcalo.
  • Reprodúzcalo en tiempo real con un reproductor compatible con streaming.

Notas:

  • Para formatos comprimidos como mp3 y opus, la reproducción segmentada requiere un reproductor en streaming. La decodificación puede fallar si reproduce los segmentos cuadro por cuadro.
  • Para ensamblar un archivo completo, ábralo en modo de anexado y escriba cada segmento en orden.
  • Para wav y mp3, solo la primera invocación de onStreamInputTtsDataCallback contiene el encabezado del archivo. Las invocaciones posteriores contienen audio sin procesar. Concatene todos los fragmentos de buffer en orden. Para opus, cada trama es una página Ogg autónoma y se puede concatenar directamente.

onStreamInputTtsLogTrackCallback: recibir registros de seguimiento

Utilice esta devolución de llamada para recibir registros internos detallados del SDK, lo cual ayuda en la resolución de problemas y depuración.

Firma del método:
default void onStreamInputTtsLogTrackCallback(Constants.LogLevel level, String log)

StreamInputTtsEvent

Enumeración de tipos de eventos para la síntesis de habla en streaming de Qwen-Audio-TTS.

EventoDescripción
STREAM_INPUT_TTS_EVENT_SYNTHESIS_STARTEDEl servidor ha aceptado la solicitud y ha comenzado el procesamiento. Poco después de este evento, onStreamInputTtsDataCallback comienza a devolver los primeros datos de audio.
STREAM_INPUT_TTS_EVENT_SENTENCE_SYNTHESISInformación de ejecución sobre la síntesis, incluidos los datos de facturación.
STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETEEl servidor ha enviado todos los datos de audio y onStreamInputTtsEventCallback no se volverá a llamar. Este evento es la señal explícita de que el flujo de audio ha terminado.
STREAM_INPUT_TTS_EVENT_TASK_FAILEDLa tarea falló. Lea el campo all_response de INativeStreamInputTtsCallback para obtener task_id, error_code y error_message e identificar la causa.
{
    "header": {
        "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
        "event": "task-failed",
        "error_code": "InvalidParameter",
        "error_message": "[tts:]Engine return error code: 418",
        "attributes": {}
    },
    "payload": {}
}

Código de ejemplo

  1. Obtener una clave API: Obtenga una clave API. Por seguridad, almacene la clave API en una variable de entorno.

    NotaUtilice una clave de API temporal cuando necesite otorgar acceso temporal a una aplicación o usuario externo, o cuando want controlar estrictamente operaciones de alto riesgo, como acceder a datos confidenciales o eliminarlos. Una clave de API temporal tiene una validez de 60 segundos, tras los cuales debe solicitar una nueva.

  2. Descargue el SDK y ejecute el código de ejemplo:
    • Descargue el paquete más reciente del SDK.
    • Descomprima el paquete. El SDK en formato AAR se encuentra en app/libs — agréguelo a las dependencias de su proyecto. Para la integración con C++ en Android, obtenga las bibliotecas compartidas de android_libs y los encabezados de android_include dentro del ZIP.
    • Abra el proyecto en Android Studio. El código de ejemplo se encuentra en DashQwen-Audio-TTSStreamTtsActivity.java — reemplace la clave API con la suya propia para probar la función.

Modos de invocación

ModoDescripción
One-shot text inputPasos:
  1. Inicialice el SDK y los componentes del reproductor.
  2. Configure los parámetros para su escenario.
  3. Llame a playStreamInputTts o asyncPlayStreamInputTts para enviar el texto e iniciar la síntesis.
  4. Reciba el evento STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE — la síntesis ha finalizado.
Casos de uso:
  • Síntesis de texto corto
  • Escenarios que requieren marcado SSML
Streaming text inputPasos:
  1. Inicialice el SDK y los componentes del reproductor.
  2. Configure los parámetros para su escenario.
  3. Llame a startStreamInputTts para iniciar la síntesis en streaming.
  4. Llame a sendStreamInputTts para enviar texto continuamente a medida que esté disponible.
  5. Recibir datos de audio binarios en onStreamInputTtsDataCallback.
  6. Llame a stopStreamInputTts o asyncStopStreamInputTts para finalizar la entrada y esperar a que termine la síntesis.
  7. Reciba el evento STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE — la síntesis ha finalizado.
Casos de uso:
  • Escenarios de conversación en tiempo real y de formato largo "hablar sobre la marcha"
  • El marcado SSML no es compatible en este modo

Funciones avanzadas

Marcado SSML

Propósito: Incrustar etiquetas XML en el texto para ajustar la pronunciación, la velocidad de habla, las pausas y otros detalles prosódicos.

Limitaciones: SSML solo es compatible con entrada de texto única (los métodos playStreamInputTts o asyncPlayStreamInputTts). La entrada de texto en streaming (el método sendStreamInputTts) no admite SSML.

Uso: Cuando llama a playStreamInputTts o asyncPlayStreamInputTts, el SDK habilita SSML automáticamente. Pase el texto que contiene etiquetas SSML a través del parámetro text.

Para más información, consulte SSML.

Expresiones matemáticas

Propósito: Permitir que el modelo lea en voz alta fórmulas y expresiones matemáticas comunes correctamente.

Uso: Pase texto que contenga expresiones matemáticas con formato LaTeX a través del parámetro text. Para más información, consulte Convertir fórmulas LaTeX a voz (solo idioma chino).