Todos los productos
Search
Centro de documentos

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

Última actualización: Oct 12, 2026

Utilice el SDK de iOS de Qwen-Audio-TTS para convertir texto en voz expresiva y de alta calidad en sus aplicaciones iOS.

NeoNui

Aspectos destacados de la arquitectura:
  • Patrón Singleton: obtenga la instancia global mediante [StreamInputTts get_instance].
  • Impulsado por callbacks: reciba eventos y datos de audio a través del protocolo StreamInputTtsDelegate.
  • Configuración JSON: pase los parámetros como cadenas JSON.

Flujos de llamada

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

Entrada única: ideal para la síntesis de texto corto o cuando necesita 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. TTS_EVENT_SYNTHESIS_COMPLETE — Síntesis completada.

Entrada en streaming: ideal para conversaciones en tiempo real o escenarios de formato largo de "hablar mientras se sintetiza". Este modo no admite marcado SSML.

  1. startStreamInputTts() — Inicialice el SDK y configure el delegado de callback y los parámetros de conexión.
  2. sendStreamInputTts() — Envíe continuamente fragmentos de texto para ser sintetizados.
  3. onStreamInputTtsDataCallback() — Recibir datos de audio.
  4. stopStreamInputTts() o asyncStopStreamInputTts() — Envía la solicitud de fin de 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 enviar la solicitud.
  5. TTS_EVENT_SYNTHESIS_COMPLETE — Síntesis completada.

startStreamInputTts

Inicia una tarea de síntesis de voz en streaming y abre una conexión con el servidor.

Firma del método
- (int) startStreamInputTts:(const char *)ticket parameters:(const char *)parameters sessionId:(const char *)sessionId logLevel:(NuiSdkLogLevel)logLevel saveLog:(BOOL)saveLog;
Parámetros
ParámetroTipoDescripción
ticketchar*Cadena JSON que contiene la configuración de autenticación, conexión y depuración.
parameterschar*Cadena JSON que contiene la configuración de efectos de síntesis de voz.
sessionIdchar*ID de sesión especificado por el cliente. Si se omite, el servidor genera uno.
logLevelNuiSdkLogLevelNivel de impresión para los registros internos del SDK.
saveLogBOOLIndica si se deben guardar los registros localmente. Cuando se establece en YES, debe especificar una ruta con debug_path y puede limitar el tamaño del archivo con max_log_file_size.
Valor de retorno

Devuelve un código de error. Ejemplo de JSON de ticket: El siguiente ejemplo no incluye todos los campos. Agregue los demás según lo requiera su código:

{
  "url": "wss://dashscope.aliyuncs.com/api-ws/v1/inference",
  "apikey": "st-****",
  "device_id": "my_device_id"
}
Campos de ticket
CampoTipoObligatorioDescripció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íClave de API. Para limitar la exposición en caso de que se filtre una clave de larga duración, utilice una clave de API de corta duración en su lugar.
device_idstringSíIdentificador único para el usuario final. Establézcalo en el ID de usuario dentro de la aplicación o en un identificador de dispositivo generado por el cliente. El ID se utiliza para el rastreo de registros y la resolución de problemas.
complete_waiting_msintNoTiempo de espera, en milisegundos, para esperar el evento de síntesis completada (TTS_EVENT_SYNTHESIS_COMPLETE) después de llamar a stopStreamInputTts.

Predeterminado: 10000.

debug_pathstringNoRuta local donde se almacenan los archivos de registro.

Este campo solo surte efecto cuando saveLog se establece en YES en startStreamInputTts, playStreamInputTts o asyncPlayStreamInputTts. En ese caso, debe establecer esta ruta; de lo contrario, se devuelve un error.

Se conservan como máximo dos archivos de registro localmente.

max_log_file_sizeintNoTamaño máximo de un archivo de registro, en bytes.

Este campo surte efecto únicamente cuando saveLog se establece en YES en startStreamInputTts, playStreamInputTts o asyncPlayStreamInputTts.

Valor predeterminado: 104857600 (100 × 1024 × 1024 bytes, es decir, 100 MiB).

log_track_levelintNoNivel de filtro para los registros entregados a través del callback 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 callback)

Nota: log_track_level y logLevel (establecidos mediante startStreamInputTts, playStreamInputTts o asyncPlayStreamInputTts) determinan conjuntamente qué registros llegan a la devolución de llamada. Un registro activa la devolución de llamada solo cuando su nivel está en o por encima de ambos umbrales. Por ejemplo, si log_track_level es 2 (INFO) y logLevel es 3 (WARNING), solo se entregan los registros con nivel WARNING o superior (nivel >= 3).

Ejemplo de JSON de parameters: El siguiente ejemplo no incluye todos los campos. Agregue los demás según lo requiera su código:

{
  "model": "qwen-audio-3.0-tts-flash",
  "voice": "longanlingxi",
  "format": "mp3",
  "sample_rate": 24000,
  "volume": 50,
  "rate": 1,
  "pitch": 1,
  "language_hints": ["zh"],
  "enable_ssml": false
}
Campos de parameters
CampoTipoObligatorioDescripció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_decoderBOOLNoSi se debe habilitar el decodificador interno del SDK. Valor predeterminado: NO.

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 se devuelven en all_response de onStreamInputTtsEventCallback.

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_hintsarray[string]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, utilice este método para enviar texto continuamente.

Después de enviar todo el texto, llame a stopStreamInputTts o asyncStopStreamInputTts para indicar el fin de la entrada.

Firma del método
- (int) sendStreamInputTts:(const char *)text;
Parámetros
ParámetroTipoDescripción
textchar*Texto a sintetizar. SSML no es compatible. Las etiquetas SSML en la entrada se leen como texto plano en lugar de analizarse.
Valor de retorno

Devuelve un código de error.

stopStreamInputTts

Método síncrono. Notifica al servidor que se ha enviado todo el texto y luego se bloquea hasta que se sintetice cada fragmento de audio y se reciba TTS_EVENT_SYNTHESIS_COMPLETE.

El tiempo de espera de bloqueo está controlado por complete_waiting_ms.

Firma del método
- (int) stopStreamInputTts;
Valor de retorno

Devuelve un código de error.

asyncStopStreamInputTts

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

Utilice TTS_EVENT_SYNTHESIS_COMPLETE para detectar cuándo finaliza la síntesis.

Firma del método
- (int) asyncStopStreamInputTts;
Valor de retorno

Devuelve un código de error.

cancelStreamInputTts

Cierra inmediatamente la conexión con el servidor y termina la tarea de síntesis actual. Después de llamar a este método, no se activarán más callbacks de datos de audio.

Firma del método
- (int) cancelStreamInputTts;
Valor de retorno

Devuelve un código de error.

playStreamInputTts

Método de síntesis única síncrono. Envía el texto y se bloquea mientras se reciben todos los datos de audio, luego regresa después de que finaliza la síntesis. No necesita llamar a stopStreamInputTts posteriormente.

Este método habilita SSML de forma predeterminada. Para deshabilitar SSML, establezca el campo enable_ssml en parameters como false.

Firma del método
- (int) playStreamInputTts:(const char *)ticket parameters:(const char *)parameters text:(const char *)text sessionId:(const char *)sessionId logLevel:(NuiSdkLogLevel)logLevel saveLog:(BOOL)saveLog;
Parámetros

Los parámetros compartidos ticket, parameters y otros utilizan las mismas definiciones que startStreamInputTts.

ParámetroTipoDescripción
textchar*Texto a sintetizar. Admite SSML.
Valor de retorno

Devuelve un código de error.

asyncPlayStreamInputTts

Este método envía todo el texto para su síntesis de manera asíncrona. Regresa inmediatamente sin esperar datos de audio. No necesita llamar a stopStreamInputTts posteriormente.

Este método habilita SSML de forma predeterminada. Para deshabilitar SSML, establezca el campo enable_ssml en parameters como false.

Firma del método
- (int) asyncPlayStreamInputTts:(const char *)ticket parameters:(const char *)parameters text:(const char *)text sessionId:(const char *)sessionId logLevel:(NuiSdkLogLevel)logLevel saveLog:(BOOL)saveLog;
Parámetros

Los parámetros compartidos ticket, parameters y otros utilizan las mismas definiciones que startStreamInputTts.

ParámetroTipoDescripción
textchar*Texto a sintetizar. Admite SSML.
Valor de retorno

Devuelve un código de error.

StreamInputTtsDelegate

Protocolo de callback para la síntesis de voz en streaming de Qwen-Audio-TTS. Implemente este protocolo para recibir eventos de síntesis, datos de audio y registros.

onStreamInputTtsEventCallback: escucha de eventos

Firma del método
- (void)onStreamInputTtsEventCallback:(StreamInputTtsCallbackEvent)event taskId:(char*)taskid sessionId:(char*)sessionId ret_code:(int)ret_code error_msg:(char*)error_msg timestamp:(char*)timestamp all_response:(char*)all_response;
Parámetros
ParámetroTipoDescripción
eventStreamInputTtsCallbackEventEvento de callback.
taskidchar*ID de la tarea de síntesis de voz.
sessionIdchar*ID de sesión. El valor proporcionado por el cliente se devuelve tal cual. Si no se proporcionó none, el servidor genera uno.
ret_codeintCódigo de error. Válido únicamente para el evento TTS_EVENT_TASK_FAILED. Consulte los códigos de error.
error_msgchar*Mensaje de error. Válido únicamente para el evento TTS_EVENT_TASK_FAILED.
timestampchar*Información de marca de tiempo para el resultado de la síntesis.
all_responsechar*Respuesta JSON completa. Analice esta cadena para extraer los campos que necesita.

onStreamInputTtsDataCallback: escucha de datos de audio

El SDK activa este callback repetidamente durante la síntesis. Lea los datos de audio desde el callback.

Firma del método
- (void)onStreamInputTtsDataCallback:(char*)buffer len:(int)len;
Parámetros
ParámetroTipoDescripción
bufferchar*Datos de audio para el segmento actual. Utilice estos datos para:
  • Ensamble un archivo de audio completo y reprodúzcalo.
  • Transmita los datos a un reproductor que admita reproducción en streaming.

Nota:

  • Para los formatos comprimidos mp3 y opus, utilice un reproductor en streaming. Reproducir segmentos cuadro por cuadro puede causar fallos de decodificación.
  • Al ensamblar un archivo completo, añada cada segmento al mismo archivo.
  • Para los formatos wav y mp3, solo la primera invocación de onStreamInputTtsDataCallback incluye el encabezado del archivo; las invocaciones posteriores devuelven datos de audio sin procesar. Concatene todos los valores de buffer en orden. Para el formato opus, cada trama es una página Ogg autónoma que puede concatenar directamente.
lenintLongitud de los datos de audio, en bytes.

onStreamInputTtsLogTrackCallback: escucha de registros de seguimiento

Este callback entrega registros internos detallados del SDK para ayudar en la resolución de problemas y la depuración.

Firma del método
- (void)onStreamInputTtsLogTrackCallback:(NuiSdkLogLevel)level
                            logMessage:(const char *)log;
Parámetros
ParámetroTipoDescripción
levelNuiSdkLogLevelNivel de registro.
logchar*Contenido del registro.

StreamInputTtsCallbackEvent

Enumeración de tipo de evento para la síntesis de voz en streaming de Qwen-Audio-TTS.

EventoDescripción
TTS_EVENT_SYNTHESIS_STARTEDEl servidor aceptó la solicitud y comenzó el procesamiento. onStreamInputTtsDataCallback normalmente entrega el primer segmento de audio poco después de este evento.
TTS_EVENT_SENTENCE_SYNTHESISInformación de progreso emitida durante la síntesis, incluidos los datos de facturación.
TTS_EVENT_SYNTHESIS_COMPLETEEl servidor ha terminado de enviar todos los datos de audio. onStreamInputTtsDataCallback no se vuelve a llamar. Este evento es la señal definitiva de fin de flujo.
TTS_EVENT_TASK_FAILEDLa tarea falló. Lea task_id, error_code y error_message de all_response en onStreamInputTtsEventCallback para diagnosticar el fallo.
{
        "header": {
            "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
            "event": "task-failed",
            "error_code": "InvalidParameter",
            "error_message": "[tts:]Engine return error code: 418",
            "attributes": {}
        },
        "payload": {}
    }

NuiSdkLogLevel

Enumeración de nivel de registro del SDK que controla la salida de registros.

NivelDescripción
0: LOG_LEVEL_VERBOSEMost detailed log level. Includes all debug information.
1: LOG_LEVEL_DEBUGDebug-level logs.
2: LOG_LEVEL_INFORegistros informativos generales (predeterminado).
3: LOG_LEVEL_WARNINGWarning-level logs.
4: LOG_LEVEL_ERRORError-level logs.
5: LOG_LEVEL_NONEDisables log output.

Código de ejemplo

  1. Obtenga su clave de API: Obtener una clave de API.

NotaPara aplicaciones de terceros o usuarios finales que necesitan acceso temporal, o cuando usted want un control estricto sobre operaciones sensibles como el acceso y la eliminación de datos, utilice una clave API temporal en su lugar. Una clave API temporal es válida durante 60 segundos fijos y debe regenerarse después de que expire.

  1. Descargue el SDK y ejecute el código de ejemplo:
    • Descargue el paquete más reciente del SDK.
    • Extraiga el archivo ZIP y agregue nuisdk.framework a su proyecto de Xcode.
    • En Build Phases > Link Binary With Libraries, agregue nuisdk.framework.
    • En General > Frameworks, Libraries, and Embedded Content, configure nuisdk.framework en Embed & Sign.
    • Abra el proyecto de ejemplo en Xcode. El código de ejemplo se encuentra en DashQwen-Audio-TTSStreamInputTTSViewController.m. Reemplace la clave de API del marcador de posición con la suya propia y ejecute la aplicación para probarla.

Modos de llamada

Modo de llamadaDescripción
One-shot inputPasos:
  1. Inicialice el SDK y el componente 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. Espere el callback TTS_EVENT_SYNTHESIS_COMPLETE, que indica que la síntesis ha finalizado.
Casos de uso:
  • Síntesis de texto corto.
  • Escenarios que requieren marcado SSML.
Streaming inputPasos:
  1. Inicialice el SDK y el componente 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 repetidamente para enviar texto en fragmentos.
  5. Lea los datos de audio binarios desde onStreamInputTtsDataCallback.
  6. Llame a stopStreamInputTts o asyncStopStreamInputTts para dejar de enviar texto y esperar a que finalice la síntesis.
  7. Espere el callback TTS_EVENT_SYNTHESIS_COMPLETE, que indica que la síntesis ha finalizado.
Casos de uso:
  • Conversaciones en tiempo real o escenarios de formato largo de "hablar mientras se sintetiza".
  • Este modo no admite marcado SSML.

Funciones avanzadas

Marcado SSML

Propósito: Incrustar etiquetas XML en el texto de entrada para controlar con precisión la pronunciación, la velocidad del habla, las pausas y otros detalles de la prosodia.

Limitaciones: SSML solo es compatible con la entrada única (los métodos playStreamInputTts y asyncPlayStreamInputTts). No es compatible con la entrada en streaming (el método sendStreamInputTts).

Cómo usar: Cuando llama a playStreamInputTts o asyncPlayStreamInputTts, el SDK habilita SSML automáticamente. Pase el texto que contiene etiquetas SSML directamente en el parámetro text.

Para más detalles, consulte SSML.

Expresiones matemáticas

Propósito: Hacer que el modelo lea correctamente fórmulas y expresiones matemáticas comunes.

Cómo usar: Pase texto que contenga expresiones matemáticas en formato LaTeX directamente en el parámetro text. Para más detalles, consulte Convertir fórmulas LaTeX a voz (solo idioma chino).