Skip to main content

API HTTP de clonación de voz: Qwen-Audio y CosyVoice

Parámetros HTTP, respuestas y ejemplos de clonación de voz para Qwen-Audio y CosyVoice.

Esta referencia abarca Qwen-Audio-TTS, Qwen-Audio-Realtime y CosyVoice. Primero obtenga una API Key y configure las variables de entorno. Los ejemplos de solicitudes leen DASHSCOPE_API_KEY. Al administrar la misma voz mediante distintas API, use la misma cuenta. Para las definiciones del SDK, consulte Java SDK y Python SDK.

Endpoint del servicio

  • China (Pekín)
  • Singapur
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization
Sustituya {WorkspaceId} por el ID real del espacio de trabajo, que se encuentra en la página Workspace Details de la consola de Alibaba Cloud Model Studio. Las API Keys son diferentes para Pekín y Singapur.
Alibaba Cloud Model Studio ofrece dominios específicos de cada espacio de trabajo para las regiones de China (Pekín) y Singapur. Los nuevos dominios dedicados ofrecen mayor rendimiento y estabilidad para las solicitudes de inferencia. Le recomendamos migrar a los nuevos dominios:
  • Región de China (Pekín): migre de dashscope.aliyuncs.com a {WorkspaceId}.cn-beijing.maas.aliyuncs.com.
  • Región de Singapur: migre de dashscope-intl.aliyuncs.com a {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com.
Los dominios existentes siguen funcionando con normalidad.

Encabezados de la solicitud

ParámetroTipoObligatorioDescripción
AuthorizationstringSíToken de autenticación en el formato Bearer <your_api_key>. Reemplace <your_api_key> con su clave API real.
Content-TypestringSíEstablezca en application/json.

Requisitos de audio y costos

Consulte los requisitos de audio en la Guía de clonación de voz. El proceso de Qwen-Audio-Realtime se describe en Clonación de voz para conversaciones de voz en tiempo real. Crear una voz con Qwen-Audio-Realtime es gratuito; las llamadas al modelo se facturan según el modelo de destino. Consulte los detalles en Información de facturación y los límites de cantidad en Información de cuotas.

Cuerpo de la solicitud

model string — ObligatorioEstablezca en voice-enrollment.input object — Obligatorio

Propiedades

action string — ObligatorioOperación:
  • create_voice: Crear una voz.
  • list_voice: Enumerar voces.
  • query_voice: Consultar los detalles de una voz.
  • update_voice: Actualizar una voz.
  • delete_voice: Eliminar una voz.
target_model string — Obligatorio al crearModelo que usará la voz. Debe coincidir con el modelo de las llamadas posteriores de síntesis o conversación; de lo contrario, la llamada falla.Elija un modelo Qwen-Audio-TTS, Qwen-Audio-Realtime o CosyVoice que admita clonación de voz. Consulte los ID de modelo y las regiones en Modelos compatibles.audio string — Obligatorio al crear o actualizar si no se proporciona urlAudio de referencia para crear la voz, o nuevo audio de referencia para actualizarla. Acepta una URL de acceso público o un Data URI Base64, como data:audio/wav;base64,....
Compatible con el parámetro anterior url; al usar url, se puede omitir audio. url se retirará gradualmente; se recomienda usar audio.
prefix string — Obligatorio al crear; opcional al enumerarAl crear: prefijo del nombre de voz. Solo admite dígitos y letras inglesas, con un máximo de 10 caracteres. El nombre generado tiene el formato {target_model}-{prefix}-{unique_id}.Al enumerar: filtra las voces por el prefijo del nombre.language_hints array[string] — Opcional al crearAyuda al modelo a identificar el idioma del audio de muestra para extraer con más precisión las características de voz y mejorar la clonación. Si el idioma especificado no coincide con el del audio, por ejemplo en para audio en chino, el sistema ignora este ajuste y detecta el idioma automáticamente.Este parámetro es un arreglo y su longitud debe ser 1.
Se aplica a qwen-audio-3.1-tts-plus, qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash, cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-plus, cosyvoice-v3-flash.
  • qwen-audio-3.1-tts-plus, qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash:
    • 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
    • it: Italiano
    • es: Español
    • ms: malayo
    • fil: Filipino
    • ar: Árabe
  • cosyvoice-v3-plus:
    • zh: Chino
    • en: Inglés
    • fr: Francés
    • de: Alemán
    • ja: Japonés
    • ko: Coreano
    • ru: Ruso
  • cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash:
    • 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
Valor predeterminado: ["zh"].max_prompt_audio_length float — Opcional al crearDuración máxima, en segundos, del audio de referencia usado para la clonación después del preprocesamiento. Rango de valores: [3.0, 30.0].Valor predeterminado: 10.0.
Se aplica a qwen-audio-3.1-tts-plus, qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash, cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash.
enable_preprocess boolean — Opcional al crearIndica si se debe habilitar el preprocesamiento de audio (reducción de ruido, mejora de audio y normalización de volumen). Habilite esta opción para grabaciones con ruido de fondo. Desactívela para grabaciones en entornos silenciosos para preservar las características originales de la voz.Valor predeterminado: false.
Se aplica a qwen-audio-3.1-tts-plus, qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash, cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash.
enable_volume_normalization string — Opcional al crearIndica si se debe normalizar el volumen del audio de muestra usado para la clonación. Valores:
  • "true": Habilitar la normalización de volumen.
  • "false": desactivar la normalización del volumen.
Cuando está activado, el audio sintetizado con la voz creada puede tener un volumen diferente del que se obtiene cuando este parámetro está desactivado.Valor predeterminado: "false".page_index integer — Opcional al enumerarÍndice de página.page_size integer — Opcional al enumerarNúmero de entradas por página.voice_id string — Obligatorio al consultar, actualizar o eliminarID de la voz que se consultará, actualizará o eliminará.

Ejemplos de solicitudes

  • Crear
  • Enumerar
  • Consultar detalles
  • Actualizar
  • Eliminar
El ejemplo usa qwen-audio-3.1-tts-plus. Sustituya target_model en input por el ID real de su modelo de destino.La siguiente configuración corresponde a la región de Singapur. Sustituya "{WorkspaceId}" por el ID real de su espacio de trabajo. La configuración varía según la región.
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "create_voice",
        "target_model": "qwen-audio-3.1-tts-plus",
        "prefix": "myvoice",
        "audio": "https://your-audio-url.wav",
        "language_hints": ["en"],
        "enable_volume_normalization": "false"
    }
}'
Si usa un archivo WAV local, puede generar una URI de datos Base64 con el siguiente código y establecer el valor de audio en el campo audio del objeto input de la solicitud de creación o actualización. Sustituya sample.wav por la ruta de su archivo de audio local.
import base64
from pathlib import Path

audio = "data:audio/wav;base64," + base64.b64encode(
    Path("sample.wav").read_bytes()
).decode("ascii")

Cuerpo de la respuesta

request_id stringEl identificador único de esta solicitud.output objectContiene los campos de creación, enumeración o consulta de detalles. La actualización no devuelve datos de negocio. La respuesta puede incluir preview_audio como objeto vacío que puede ignorar. La eliminación devuelve un objeto vacío.
voice_id string — Devuelto al crearID de voz.voice_list array[object] — Devuelto al enumerarLista de voces encontradas.
voice_id stringID de voz.gmt_create stringFecha de creación de la voz.gmt_modified stringLa hora de la última modificación.status stringEstado de voz; consulte “Descripción de los estados de voz” para ver los valores válidos.
resource_link string — Devuelto al consultar detallesLa URL del archivo de audio.gmt_create string — Devuelto al consultar detallesFecha de creación de la voz.gmt_modified string — Devuelto al consultar detallesLa hora de la última modificación.status string — Devuelto al consultar detallesEstado de voz; consulte “Descripción de los estados de voz” para ver los valores válidos.target_model string — Devuelto al consultar detallesModelo de destino que usa la voz para texto a voz o conversación de voz en tiempo real.
usage objectInformación de uso de esta solicitud.
count integerSiempre es 1. Para la creación, indica el número de voces creadas.

Ejemplos de respuestas

  • Crear
  • Enumerar
  • Consultar detalles
  • Actualizar
  • Eliminar
{
    "output": {
        "voice_id": "qwen-audio-3.1-tts-plus-myvoice-xxxxxx"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

Descripción de los estados de voz

Las voces creadas pasan por un proceso de revisión.
StatusDescripción
DEPLOYINGEn revisión o procesamiento.
OKSe aprobó la revisión. La voz está lista para usarse.
UNDEPLOYEDSe rechazó la revisión. La voz no se puede usar.

Mensajes de error

Si se produce un error, consulte Códigos de error para el diagnóstico.