Referencia de la API HTTP de Voice Design - Alibaba Cloud Model Studio

Utilice la API HTTP de Voice Design para crear, listar, consultar y eliminar voces personalizadas.

Guía del usuario: Diseño de Voz.

Endpoint

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 por espacio de trabajo para las regiones de China (Beijing). 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

Reemplace {WorkspaceId} con su ID de espacio de trabajo real. Los dominios existentes permanecen totalmente funcionales.

Encabezados de solicitud

Parámetro	Tipo	Obligatorio	Descripción
Authorization	string	Sí	Establezca el valor en `Bearer <your_api_key>`. Reemplace `<your_api_key>` con su clave de API.
Content-Type	string	Sí	Tipo de medio del cuerpo de la solicitud. Establézcalo en `application/json`.

Crear una voz

Cuerpo de la solicitud

modelstring(Obligatorio)

El modelo de diseño de voz. Valores válidos:

voice-enrollment: Diseño de voz de Qwen-Audio-TTS/CosyVoice.

inputobject(Obligatorio)

El objeto de parámetros de entrada.

Propiedades

action string(Obligatorio)

El tipo de operación.

Qwen-Audio-TTS/CosyVoice (voice-enrollment): Establezca en create_voice.

target_model string(Obligatorio)

El modelo de texto a voz (TTS) para la voz. Debe coincidir con el modelo en las llamadas a la API de TTS, o la síntesis fallará.

qwen-audio-3.0-tts-plus y qwen-audio-3.0-tts-flash no admiten Diseño de Voz.

voice_prompt string(Obligatorio)

Descripción de las características deseadas de la voz. Solo chino e inglés.

Qwen-Audio-TTS/CosyVoice (voice-enrollment): Máximo 500 caracteres.

preview_text string(Obligatorio)

El texto para el audio de vista previa.

Qwen-Audio-TTS/CosyVoice (voice-enrollment): Máximo 200 caracteres. Se admiten chino e inglés.

prefix string(Obligatorio)

ImportanteAplicable solo a Qwen-Audio-TTS/CosyVoice (cuando el modelo es voice-enrollment).

Prefijo del nombre de la voz. Solo caracteres alfanuméricos, máximo 10 caracteres. Formato del nombre generado: {target_model}-vd-{prefix}-{unique_id}

language_hints array[string](Opcional)

ImportanteAplicable solo a Qwen-Audio-TTS/CosyVoice (cuando el modelo es voice-enrollment).

Sugerencia de idioma para la generación de voz. Debe coincidir con el idioma de preview_text.

Actualmente, solo se utiliza el primer elemento.

Valores válidos:

zh: Chino
en: Inglés

Valor predeterminado: ["zh"].

parametersobject(Opcional)

Configuración para el diseño de voz.

Propiedades

sample_rate int(Opcional)

Frecuencia de muestreo del audio de vista previa, en Hz.

Qwen-Audio-TTS/CosyVoice: 16000, 24000 o 48000.

Predeterminado: 24000.

response_format string(Opcional)

Formato del audio de vista previa.

Qwen-Audio-TTS/CosyVoice: pcm, wav o mp3.

Predeterminado: wav.

Los siguientes ejemplos utilizan la configuración de la región China (Beijing). Reemplace {WorkspaceId} con su ID de espacio de trabajo real.

Qwen-Audio-TTS/CosyVoice voice design

curl -X POST https://{WorkspaceId}.cn-beijing.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": "cosyvoice-v3.5-plus",
        "voice_prompt": "A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary.",
        "preview_text": "Dear listeners, hello everyone. Welcome to the evening news.",
        "prefix": "announcer",
        "language_hints": ["en"]
    },
    "parameters": {
        "sample_rate": 24000,
        "response_format": "wav"
    }
}'

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.

preview_audioobject

Los datos de audio de vista previa.

Propiedades

data string

Los datos de audio de vista previa, codificados en Base64.

sample_rate int

La frecuencia de muestreo del audio de vista previa, en Hz.

response_format string

El formato del audio de vista previa.

target_modelstring

El modelo TTS que impulsa la voz.

usageobject

Información de uso para esta solicitud.

Propiedades

count integer

El número de voces creadas. Siempre 1.

Qwen-Audio-TTS/CosyVoice voice design

{
    "output": {
        "preview_audio": {
            "data": "{base64_encoded_audio}",
            "sample_rate": 24000,
            "response_format": "wav"
        },
        "target_model": "cosyvoice-v3.5-plus",
        "voice_id": "cosyvoice-v3.5-plus-vd-announcer-xxxxxx"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

Listar voces

Cuerpo de la solicitud

modelstring(Obligatorio)

El modelo de diseño de voz. Valores válidos:

voice-enrollment: Diseño de voz de Qwen-Audio-TTS/CosyVoice.

inputobject(Obligatorio)

El objeto de parámetros de entrada.

Propiedades

action string(Obligatorio)

Establecido en list_voice.

prefix string(Opcional)

ImportanteAplicable solo a Qwen-Audio-TTS/CosyVoice.

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

Los siguientes ejemplos utilizan la configuración de la región China (Beijing). Reemplace {WorkspaceId} con su ID de espacio de trabajo real.

Qwen-Audio-TTS/CosyVoice

curl -X POST https://{WorkspaceId}.cn-beijing.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 devuelta por la consulta.

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

ImportanteDevuelto solo por Qwen-Audio-TTS/CosyVoice.

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

voice_promptstring

El texto de descripción de la voz.

preview_textstring

El texto del audio de vista previa.

usageobject

Información de uso para esta solicitud.

Propiedades

count integer

Siempre 1.

Qwen-Audio-TTS/CosyVoice

{
    "output": {
        "voice_list": [
            {
                "voice_id": "cosyvoice-v3.5-plus-vd-announcer-xxxxxx",
                "gmt_create": "2025-12-10 14:54:09",
                "gmt_modified": "2025-12-10 17:47:48",
                "status": "OK",
                "voice_prompt": "A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary.",
                "preview_text": "Dear listeners, hello everyone. Welcome to the evening news."
            }
        ]
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

Consultar detalles de la voz

Cuerpo de la solicitud

modelstring(Obligatorio)

El modelo de diseño de voz. Valores válidos:

voice-enrollment: Diseño de voz de Qwen-Audio-TTS/CosyVoice.

inputobject(Obligatorio)

El objeto de parámetros de entrada.

Propiedades

action string(Obligatorio)

Establecido en query_voice.

voice_id string(Obligatorio)

ImportanteAplicable solo a Qwen-Audio-TTS/CosyVoice.

El ID de voz a consultar.

Los siguientes ejemplos utilizan la configuración de la región China (Beijing). Reemplace {WorkspaceId} con su ID de espacio de trabajo real.

Qwen-Audio-TTS/CosyVoice

curl -X POST https://{WorkspaceId}.cn-beijing.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

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

ImportanteDevuelto solo por Qwen-Audio-TTS/CosyVoice.

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

target_modelstring

El modelo TTS que impulsa la voz.

voice_promptstring

ImportanteDevuelto solo por el diseño de voz de Qwen-Audio-TTS/CosyVoice.

El texto de descripción de la voz.

preview_textstring

ImportanteDevuelto solo por el diseño de voz de Qwen-Audio-TTS/CosyVoice.

El texto del audio de vista previa.

usageobject

Información de uso para esta solicitud.

Propiedades

count integer

Siempre 1.

Qwen-Audio-TTS/CosyVoice voice design

{
    "output": {
        "voice_id": "cosyvoice-v3.5-plus-vd-announcer-xxxxxx",
        "gmt_create": "2025-12-10 14:54:09",
        "gmt_modified": "2025-12-10 17:47:48",
        "preview_text": "Dear listeners, hello everyone. Welcome to the evening news.",
        "target_model": "cosyvoice-v3.5-plus",
        "status": "OK",
        "voice_prompt": "A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary."
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

Eliminar una voz

Cuerpo de la solicitud

modelstring(Obligatorio)

El modelo de diseño de voz. Valores válidos:

voice-enrollment: Diseño de voz de Qwen-Audio-TTS/CosyVoice.

inputobject(Obligatorio)

El objeto de parámetros de entrada.

Propiedades

action string(Obligatorio)

Establecido en delete_voice.

voice_id string(Obligatorio)

ImportanteAplicable solo a Qwen-Audio-TTS/CosyVoice.

El ID de voz a eliminar.

Los siguientes ejemplos utilizan la configuración de la región China (Beijing). Reemplace {WorkspaceId} con su ID de espacio de trabajo real.

Qwen-Audio-TTS/CosyVoice

curl -X POST https://{WorkspaceId}.cn-beijing.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.

Qwen-Audio-TTS/CosyVoice

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

Referencia de estados de voz

Las voces creadas pasan por un proceso de revisión. Los siguientes estados aplican a Qwen-Audio-TTS/CosyVoice cuando model es voice-enrollment.

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