Skip to main content
Speech synthesis

Referência da API Voice Design

Use a API HTTP Voice Design para criar, listar, consultar e excluir vozes personalizadas.

Guia do usuário: Voice Design.

Endpoint

  • China (Beijing)
  • Singapore
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customizationSubstitua {WorkspaceId} pelo seu ID do workspace real.
  • Singapore
  • China (Beijing)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customizationSubstitua {WorkspaceId} pelo seu ID do workspace real.
O Alibaba Cloud Model Studio lançou domínios específicos por workspace para as regiões China (Beijing) e Singapore. Os novos domínios dedicados oferecem desempenho superior e maior estabilidade para solicitações de inferência. Recomendamos migrar para os novos domínios:
  • China (Beijing): de dashscope.aliyuncs.com para {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore: de dashscope-intl.aliyuncs.com para {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Substitua {WorkspaceId} pelo seu ID do Workspace real. Os domínios existentes permanecem totalmente funcionais.

Cabeçalhos da solicitação

Parâmetro

Tipo

Obrigatório

Descrição

Authorization

string

Sim

Token de autorização no formato Bearer <your_api_key>. Substitua <your_api_key> pela sua chave de API real.

Content-Type

string

Sim

Tipo de mídia do corpo da solicitação. Defina como application/json.

Crie uma voz

Corpo da solicitação

O Voice Design do CosyVoice está disponível apenas na região de Beijing. O Voice Design do Qwen oferece suporte à região de Singapore. Os exemplos do CosyVoice abaixo usam a URL da região China (Beijing). Os exemplos do Qwen abaixo usam a URL da região de Singapore (substitua {WorkspaceId} pelo ID real do seu workspace).
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": "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"
    }
}'
modelstring(Obrigatório)Modelo de voice design. Valores válidos:
  • voice-enrollment: Voice design do CosyVoice.
  • qwen-voice-design: Voice design do Qwen.
inputobject(Obrigatório)Objeto de parâmetros de entrada.

Propriedades

action string(Obrigatório)Tipo de operação.
  • CosyVoice (voice-enrollment): Defina como create_voice.
  • Qwen (qwen-voice-design): Defina como create.
target_model string(Obrigatório)Modelo de texto para fala (TTS) que gera a voz. Este valor deve corresponder ao modelo usado na chamada à API TTS. Incompatibilidades causam falha na síntese.voice_prompt string(Obrigatório)Descrição das características desejadas para a voz. Há suporte apenas para chinês e inglês.
  • CosyVoice (voice-enrollment): Máximo de 500 caracteres.
  • Qwen (qwen-voice-design): Máximo de 2.048 caracteres.
preview_text string(Obrigatório)Texto para o áudio de pré-visualização.
  • CosyVoice (voice-enrollment): Máximo de 200 caracteres. Há suporte para chinês e inglês.
  • Qwen (qwen-voice-design): Máximo de 1.024 caracteres. Há suporte para chinês, inglês, alemão, italiano, português, espanhol, japonês, coreano, francês e russo.
prefix string(Condicionalmente obrigatório)
Aplicável apenas ao CosyVoice (quando o modelo é voice-enrollment).
Prefixo do nome da voz. São permitidos apenas dígitos e letras, com máximo de 10 caracteres. O nome da voz gerada segue o formato: {target_model}-vd-{prefix}-{unique_id}preferred_name string(Condicionalmente obrigatório)
Aplicável apenas ao Qwen (quando o modelo é qwen-voice-design).
Prefixo do nome da voz. São permitidos apenas dígitos, letras e sublinhados, com máximo de 16 caracteres.language_hints array[string](Opcional)
Aplicável apenas ao CosyVoice (quando o modelo é voice-enrollment).
Dicas de idioma para a voz gerada. Este campo determina as características linguísticas e os padrões de pronúncia da voz. Defina-o com o idioma correspondente ao seu caso de uso. O idioma especificado deve corresponder ao idioma do preview_text.Atualmente, apenas o primeiro elemento é usado.Valores válidos:
  • zh: Chinês
  • en: Inglês
Padrão: ["zh"].language string(Opcional)
Aplicável apenas ao Qwen (quando o modelo é qwen-voice-design).
Dicas de idioma para a voz gerada. Este campo determina as características linguísticas e os padrões de pronúncia da voz. Defina-o com o idioma correspondente ao seu caso de uso. O idioma especificado deve corresponder ao idioma do preview_text.Valores válidos:
  • zh: Chinês
  • en: Inglês
  • de: Alemão
  • it: Italiano
  • pt: Português
  • es: Espanhol
  • ja: Japonês
  • ko: Coreano
  • fr: Francês
  • ru: Russo
Padrão: zh.
parametersobject(Opcional)Configuração para voice design.

Propriedades

sample_rate int(Opcional)Taxa de amostragem do áudio de pré-visualização, em Hz.
  • CosyVoice: 16000, 24000 ou 48000.
  • Qwen: 8000, 16000, 24000 ou 48000.
Padrão: 24000.response_format string(Opcional)Formato do áudio de pré-visualização.
  • CosyVoice: pcm, wav ou mp3.
  • Qwen: pcm, wav, mp3 ou opus.
Padrão: wav.

Corpo da resposta 

{
    "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"
}
O CosyVoice retorna o campo voice_id, enquanto o Qwen retorna o campo voice.
request_idstringIdentificador exclusivo desta solicitação.
outputobjectDados retornados pelo modelo.

Propriedades

voice_id / voicestringID da voz. O CosyVoice retorna voice_id e o Qwen retorna voice. Use este valor diretamente como parâmetro de voz na API TTS.preview_audioobjectDados do áudio de pré-visualização.

Propriedades

data stringDados do áudio de pré-visualização, codificados em Base64.sample_rate intTaxa de amostragem do áudio de pré-visualização, em Hz.response_format stringFormato do áudio de pré-visualização.
target_modelstringModelo TTS que gera a voz.
usageobjectInformações de uso desta solicitação.

Propriedades

count integerNúmero de vozes criadas. Sempre 1.

Listar vozes

Corpo da solicitação

O Voice Design do CosyVoice está disponível apenas na região de Beijing. O Voice Design do Qwen oferece suporte à região de Singapore. Os exemplos do CosyVoice abaixo usam a URL da região China (Beijing). Os exemplos do Qwen abaixo usam a URL da região de Singapore (substitua {WorkspaceId} pelo ID real do seu workspace).
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
    }
}'
modelstring(Obrigatório)Modelo de voice design. Valores válidos:
  • voice-enrollment: Voice design do CosyVoice.
  • qwen-voice-design: Voice design do Qwen.
inputobject(Obrigatório)Objeto de parâmetros de entrada.

Propriedades

action string(Obrigatório)Tipo de operação. CosyVoice: list_voice. Qwen: list.prefix string(Opcional)
Aplicável apenas ao CosyVoice.
Filtrar vozes por prefixo de nome.page_index integer(Opcional)Índice da página.page_size integer(Opcional)Número de entradas por página.

Corpo da resposta 

{
    "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"
}
O CosyVoice retorna um array voice_list em que cada item contém um campo voice_id. O Qwen também retorna um array voice_list, mas cada item contém um campo voice. A saída do Qwen também inclui os campos de paginação page_index, page_size e total_count.
request_idstringIdentificador exclusivo desta solicitação.
outputobjectDados retornados pelo modelo.

Propriedades

page_indexinteger
Retornado apenas pelo Qwen.
Índice da página atual.page_sizeinteger
Retornado apenas pelo Qwen.
Número de entradas por página.total_countinteger
Retornado apenas pelo Qwen.
Número total de vozes.voice_listarray[object]Lista de vozes retornadas pela consulta.

Propriedades

voice_id / voicestringID da voz. O CosyVoice usa voice_id e o Qwen usa voice.gmt_createstringHora de criação.gmt_modifiedstringHora da última modificação.statusstring
Retornado apenas pelo CosyVoice.
Status da voz. Para valores válidos, consulte "Referência de status de voz".target_modelstring
Retornado apenas pelo Qwen.
Modelo TTS que gera a voz.languagestringIdioma da voz.voice_promptstringTexto de descrição da voz.preview_textstringTexto do áudio de pré-visualização.
usageobjectInformações de uso desta solicitação.

Propriedades

count integerCosyVoice: sempre 1. Qwen: sempre 0.

Consultar detalhes da voz

Corpo da solicitação

O Voice Design do CosyVoice está disponível apenas na região de Beijing. O Voice Design do Qwen oferece suporte à região de Singapore. Os exemplos do CosyVoice abaixo usam a URL da região China (Beijing). Os exemplos do Qwen abaixo usam a URL da região de Singapore (substitua {WorkspaceId} pelo ID real do seu workspace).
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"
    }
}'
modelstring(Obrigatório)Modelo de voice design. Valores válidos:
  • voice-enrollment: Voice design do CosyVoice.
  • qwen-voice-design: Voice design do Qwen.
inputobject(Obrigatório)Objeto de parâmetros de entrada.

Propriedades

action string(Obrigatório)Tipo de operação. CosyVoice: query_voice. Voice design do Qwen: query.voice_id string(Condicionalmente obrigatório)
Aplicável apenas ao CosyVoice.
ID da voz a ser consultada.voice string(Condicionalmente obrigatório)
Aplicável apenas ao voice design do Qwen (quando o modelo é qwen-voice-design).
Nome da voz a ser consultada.

Corpo da resposta 

{
    "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": {},
    "request_id": "xxxx-xxxx-xxxx"
}
O CosyVoice retorna voice_id, voice_prompt e outros campos. O Qwen retorna os campos voice e language.
request_idstringIdentificador exclusivo desta solicitação.
outputobjectDados retornados pelo modelo.

Propriedades

voice_id / voicestringID da voz. O CosyVoice retorna voice_id e o Qwen retorna voice.gmt_createstringHora de criação.gmt_modifiedstringHora da última modificação.statusstring
Retornado apenas pelo CosyVoice.
Status da voz. Para valores válidos, consulte "Referência de status de voz".target_modelstringModelo TTS que gera a voz.languagestring
Retornado apenas pelo voice design do Qwen.
Idioma da voz.voice_promptstring
Retornado apenas pelo voice design do CosyVoice.
Texto de descrição da voz.preview_textstring
Retornado apenas pelo voice design do CosyVoice.
Texto do áudio de pré-visualização.
usageobjectInformações de uso desta solicitação.

Propriedades

count integerQwen: sempre 0. Não retornado pelo CosyVoice (o objeto usage está vazio).

Exclua uma voz

Corpo da solicitação

O Voice Design do CosyVoice está disponível apenas na região de Beijing. O Voice Design do Qwen oferece suporte à região de Singapore. Os exemplos do CosyVoice abaixo usam a URL da região China (Beijing). Os exemplos do Qwen abaixo usam a URL da região de Singapore (substitua {WorkspaceId} pelo ID real do seu workspace).
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"
    }
}'
modelstring(Obrigatório)Modelo de voice design. Valores válidos:
  • voice-enrollment: Voice design do CosyVoice.
  • qwen-voice-design: Voice design do Qwen.
inputobject(Obrigatório)Objeto de parâmetros de entrada.

Propriedades

action string(Obrigatório)Tipo de operação. CosyVoice: delete_voice. Qwen: delete.voice_id string(Condicionalmente obrigatório)
Aplicável apenas ao CosyVoice.
ID da voz a ser excluída.voice string(Condicionalmente obrigatório)
Aplicável apenas ao Qwen.
Nome da voz a ser excluída.

Corpo da resposta 

{
    "output": {},
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}
O CosyVoice retorna um objeto output vazio, enquanto o Qwen retorna o campo voice.
request_idstringIdentificador exclusivo desta solicitação.
outputobjectDados retornados pelo modelo. O CosyVoice retorna um objeto vazio. O Qwen retorna o nome da voz excluída.

Propriedades

voicestring
Retornado apenas pelo Qwen.
Nome da voz excluída.
usageobjectInformações de uso desta solicitação.

Propriedades

count integerCosyVoice: sempre 1. Qwen: sempre 0.

Referência de status de voz

Após a criação, a voz passa por um processo de revisão. A tabela a seguir descreve cada status. Este sistema de status aplica-se apenas ao CosyVoice (quando o modelo é voice-enrollment). As respostas de consulta e lista do Qwen não incluem um campo de status.

Status

Descrição

DEPLOYING

Em revisão ou processamento.

OK

Revisão aprovada. A voz está pronta para uso.

UNDEPLOYED

Revisão rejeitada. Não é possível usar a voz.

Uso da API
Referência da API de Geração de Texto
Geração de Imagens
  • FAQ
Geração de Vídeo
Áudio
Multimodal em Tempo Real
API em tempo real
Incorporação de Texto
Mais Modelos
Toolkit/Framework
Produção de Modelos
File Management
Gerenciamento de modelos
Mais