API HTTP de clonación de voz reference_Alibaba Cloud Model Studio(Model Studio) - Alibaba Cloud Model Studio

Utilice la API HTTP para crear, listar, consultar, actualizar y eliminar voces clonadas.

Endpoint de servicio

Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice

Singapore

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization

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

China (Beijing)

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization

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

ImportanteAlibaba Cloud Model Studio ha lanzado dominios específicos del espacio de trabajo para las regiones China (Pekín) y Singapore. Los nuevos dominios dedicados ofrecen un rendimiento superior y una mayor estabilidad para las solicitudes de inferencia. Recomendamos migrar a los nuevos dominios:

China (Pekín): de dashscope.aliyuncs.com a {WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapur: de dashscope-intl.aliyuncs.com a {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

Encabezados de solicitud

Parámetro Tipo Obligatorio Descripción

Parámetro	Tipo	Obligatorio	Descripción
Authorization	string	Sí	Token de autenticación en el formato `Bearer <your_api_key>`. Reemplace `<your_api_key>` con su clave API real.
Content-Type	string	Sí	Tipo de medio del cuerpo de la solicitud. Establezca según la serie de modelos: Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice: `application/json`.

Authorization

string

Sí

Token de autenticación en el formato Bearer <your_api_key>. Reemplace <your_api_key> con su clave API real.

Content-Type

string

Sí

Tipo de medio del cuerpo de la solicitud. Establezca según la serie de modelos:

Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice: application/json.

Crear una voz

Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice

Cuerpo de la solicitud

modelstring(obligatorio)

Establezca en voice-enrollment.

inputobject(obligatorio)

Los parámetros de entrada.

Propiedades

action string(obligatorio)

Establezca en create_voice.

target_model string(obligatorio)

El modelo de texto a voz (TTS) que impulsa la voz clonada. Debe coincidir con el modelo que especifique al llamar a la API de TTS; de lo contrario, la síntesis fallará.

audio string(requerido)

Audio de referencia para la clonación de voz. Acepta una URL de acceso público o un Data URI codificado en Base64, por ejemplo, data:audio/wav;base64,....

NotaEl parámetro anterior url sigue siendo compatible. Puede omitir audio si utiliza url. El parámetro url se retirará de forma gradual; use audio en las solicitudes nuevas.

prefix string(obligatorio)

Un prefijo para el nombre de la voz. Solo se permiten caracteres alfanuméricos, con una longitud máxima de 10 caracteres. El nombre de voz resultante sigue este formato: {target_model}-{prefix}-{unique_id}.

language_hints array[string](opcional)

Ayuda al modelo a identificar el idioma del audio de muestra para extraer características de voz con mayor precisión y mejorar la calidad de la clonación. Si el idioma especificado no coincide con el idioma real del audio (por ejemplo, establecer en cuando el audio está en chino), el sistema ignora este valor y detecta el idioma automáticamente.

Este parámetro es una matriz y debe contener exactamente un elemento.

NotaSe 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.0-realtime-plus, qwen-audio-3.0-realtime-flash, cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-plus, cosyvoice-v3-flash.

Haga clic para ver los idiomas compatibles por modelo

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.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)

La duración máxima (en segundos) del audio de referencia después del preprocesamiento. Valores válidos: [3.0, 30.0].

Predeterminado: 10.0.

enable_preprocess boolean(opcional)

Indica 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.

Predeterminado: false.

enable_volume_normalization string(opcional)

Indica si se debe normalizar el volumen del audio de muestra utilizado para la clonación de voz. Valores válidos:

"true": Habilitar la normalización de volumen.
"false": Deshabilitar la normalización de volumen.

Cuando está habilitado, el audio sintetizado con la voz creada puede tener un volumen diferente al audio sintetizado con una voz creada con este parámetro deshabilitado.

Predeterminado: "false".

Este ejemplo utiliza el endpoint de la región de Singapur. Para la región de Beijing, use: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization.

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

Clonación de voz

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.0-tts-flash",
        "prefix": "myvoice",
        "audio": "https://your-audio-url.wav",
        "language_hints": ["en"],
        "enable_volume_normalization": "false"
    }
}'

Para un archivo WAV local, genere un Data URI codificado en Base64 con el siguiente código y pase el valor de audio a input.audio en 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 respuesta

request_idstring

El identificador único de esta solicitud.

outputobject

Los datos devueltos por el modelo.

Propiedades

voice_idstring

El ID de voz. Úselo en el parámetro voice de la API de TTS.

usageobject

Información de uso para esta solicitud.

Propiedades

count integer

El número de voces creadas. Siempre 1.

Clonación de voz

{
    "output": {
        "voice_id": "qwen-audio-3.0-tts-flash-myvoice-xxxxxx"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

Consultar lista de voces

Se aplica a Qwen-Audio-TTS, Qwen-Audio-Realtime y CosyVoice.

Cuerpo de la solicitud

modelstring(obligatorio)

Establezca en voice-enrollment.

inputobject(obligatorio)

Los parámetros de entrada.

Propiedades

action string(obligatorio)

Establecido en list_voice.

prefix string(opcional)

Filtra las voces por prefijo de nombre.

page_index integer(opcional)

El índice de página.

page_size integer(opcional)

El número de entradas por página.

Este ejemplo utiliza el endpoint de la región de Singapur. Para la región de Beijing, use: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization.

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

Consultar lista de voces

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": "list_voice",
        "prefix": "myvoice",
        "page_size": 10,
        "page_index": 0
    }
}'

Cuerpo de respuesta

request_idstring

El identificador único de esta solicitud.

outputobject

Los datos devueltos por el modelo.

Propiedades

voice_listarray[object]

La lista de voces consultadas.

Propiedades

voice_idstring

El ID de voz. Úselo en el parámetro voice de la API de TTS.

gmt_createstring

La hora de creación.

gmt_modifiedstring

La hora de la última modificación.

statusstring

El estado de la voz. Para valores válidos, consulte "Descripciones de estados de voz".

usageobject

Información de uso para esta solicitud.

Propiedades

count integer

Siempre 1.

Consultar lista de voces

{
    "output": {
        "voice_list": [
            {
                "voice_id": "qwen-audio-3.0-tts-flash-myvoice-xxxxxx",
                "gmt_create": "2024-12-11 13:38:02",
                "gmt_modified": "2024-12-11 13:38:02",
                "status": "OK"
            }
        ]
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

Consultar detalles de la voz

Se aplica a Qwen-Audio-TTS, Qwen-Audio-Realtime y CosyVoice.

Cuerpo de la solicitud

modelstring(obligatorio)

Establezca en voice-enrollment.

inputobject(obligatorio)

Los parámetros de entrada.

Propiedades

action string(obligatorio)

Establecido en query_voice.

voice_id string(obligatorio)

El ID de voz a consultar.

Este ejemplo utiliza el endpoint de la región de Singapur. Para la región de Beijing, use: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization.

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

Consultar detalles de la voz

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": "query_voice",
        "voice_id": "yourVoiceId"
    }
}'

Cuerpo de respuesta

request_idstring

El identificador único de esta solicitud.

outputobject

Los datos devueltos por el modelo.

Propiedades

resource_linkstring

La URL del archivo de audio.

gmt_createstring

La hora de creación.

gmt_modifiedstring

La hora de la última modificación.

statusstring

El estado de la voz. Para valores válidos, consulte "Descripciones de estados de voz".

target_modelstring

El modelo TTS que impulsa la voz clonada.

usageobject

Información de uso para esta solicitud.

Propiedades

count integer

Siempre 1.

{
    "output": {
        "gmt_create": "2024-12-11 13:38:02",
        "resource_link": "https://yourAudioFileUrl",
        "target_model": "qwen-audio-3.0-tts-flash",
        "gmt_modified": "2024-12-11 13:38:02",
        "status": "OK"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

Actualizar una voz

Se aplica a Qwen-Audio-TTS, Qwen-Audio-Realtime y CosyVoice.

Cuerpo de la solicitud

modelstring(obligatorio)

Establezca en voice-enrollment.

inputobject(obligatorio)

Los parámetros de entrada.

Propiedades

action string(obligatorio)

Establecido en update_voice.

voice_id string(obligatorio)

El ID de voz a actualizar.

audio string(requerido)

Nuevo audio de referencia. Acepta una URL de acceso público o un Data URI codificado en Base64, por ejemplo, data:audio/wav;base64,....

NotaEl parámetro anterior url sigue siendo compatible. Puede omitir audio si utiliza url. El parámetro url se retirará de forma gradual; use audio en las solicitudes nuevas.

Este ejemplo utiliza el endpoint de la región de Singapur. Para la región de Beijing, use: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization.

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": "update_voice",
        "voice_id": "yourVoiceId",
        "audio": "https://new-audio-url.wav"
    }
}'

Cuerpo de respuesta

request_idstring

El identificador único de esta solicitud.

outputobject

Los datos devueltos por el modelo. La operación de actualización no devuelve datos comerciales. La respuesta puede incluir un campo preview_audio, que es un objeto vacío que puede ignorar.

usageobject

Información de uso para esta solicitud.

Propiedades

count integer

Siempre 1.

{
    "output": {
        "preview_audio": {}
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

Eliminar una voz

Se aplica a Qwen-Audio-TTS, Qwen-Audio-Realtime y CosyVoice.

Cuerpo de la solicitud

modelstring(obligatorio)

Establezca en voice-enrollment.

inputobject(obligatorio)

Los parámetros de entrada.

Propiedades

action string(obligatorio)

Establecido en delete_voice.

voice_id string(obligatorio)

El ID de voz a eliminar.

Este ejemplo utiliza el endpoint de la región de Singapur. Para la región de Beijing, use: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization.

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

Eliminar una voz

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": "delete_voice",
        "voice_id": "yourVoiceId"
    }
}'

Cuerpo de respuesta

request_idstring

El identificador único de esta solicitud.

outputobject

Los datos devueltos por el modelo. Este es un objeto vacío.

usageobject

Información de uso para esta solicitud.

Propiedades

count integer

Siempre 1.

Eliminar una voz

{
    "output": {},
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

Descripciones de estados de voz

Las voces creadas pasan por un proceso de revisión. Los siguientes estados aplican a Qwen-Audio-TTS, Qwen-Audio-Realtime y CosyVoice.

Status	Descripción
DEPLOYING	En revisión o procesamiento.
OK	Revisión aprobada. La voz está lista para usarse.
UNDEPLOYED	Revisión rechazada. La voz no se puede utilizar.