Skip to main content

Voice Design Referencia de la API

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/customizationReemplace {WorkspaceId} con su ID de espacio de trabajo real.
Alibaba 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)
Aplicable 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)
Aplicable 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.
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_idstringEl identificador único de esta solicitud.outputobjectLos datos devueltos por el modelo.

Propiedades

voice_idstringEl ID de voz. Úselo en el parámetro voice de la API de TTS.preview_audioobjectLos datos de audio de vista previa.

Propiedades

data stringLos datos de audio de vista previa, codificados en Base64.sample_rate intLa frecuencia de muestreo del audio de vista previa, en Hz.response_format stringEl formato del audio de vista previa.
target_modelstringEl modelo TTS que impulsa la voz.
usageobjectInformación de uso para esta solicitud.

Propiedades

count integerEl número de voces creadas. Siempre 1.
{
    "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)
Aplicable 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.
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_idstringEl identificador único de esta solicitud.outputobjectLos datos devueltos por el modelo.

Propiedades

voice_listarray[object]La lista de voces devuelta por la consulta.

Propiedades

voice_idstringEl ID de voz. Úselo en el parámetro voice de la API de TTS.gmt_createstringLa hora de creación.gmt_modifiedstringLa hora de la última modificación.statusstring
Devuelto solo por Qwen-Audio-TTS/CosyVoice.
El estado de la voz. Para valores válidos, consulte "Referencia de estados de voz".voice_promptstringEl texto de descripción de la voz.preview_textstringEl texto del audio de vista previa.
usageobjectInformación de uso para esta solicitud.

Propiedades

count integerSiempre 1.
{
    "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)
Aplicable 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.
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_idstringEl identificador único de esta solicitud.outputobjectLos datos devueltos por el modelo.

Propiedades

voice_idstringEl ID de voz. Úselo en el parámetro voice de la API de TTS.gmt_createstringLa hora de creación.gmt_modifiedstringLa hora de la última modificación.statusstring
Devuelto solo por Qwen-Audio-TTS/CosyVoice.
El estado de la voz. Para valores válidos, consulte "Referencia de estados de voz".target_modelstringEl modelo TTS que impulsa la voz.voice_promptstring
Devuelto solo por el diseño de voz de Qwen-Audio-TTS/CosyVoice.
El texto de descripción de la voz.preview_textstring
Devuelto solo por el diseño de voz de Qwen-Audio-TTS/CosyVoice.
El texto del audio de vista previa.
usageobjectInformación de uso para esta solicitud.

Propiedades

count integerSiempre 1.
{
    "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)
Aplicable 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.
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_idstringEl identificador único de esta solicitud.outputobjectLos datos devueltos por el modelo. Este es un objeto vacío.usageobjectInformación de uso para esta solicitud.

Propiedades

count integerSiempre 1.
{
    "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.