Skip to main content

Referência da API de criação de voz

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

Guia do usuário: Voice Design.

Endpoint

  • China (Beijing)
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customizationSubstitua {WorkspaceId} pelo seu ID do workspace real.
  • China (Beijing)
POST https://{WorkspaceId}.cn-beijing.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 a região China (Beijing). 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
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

Os exemplos a seguir usam a configuração da região China (Beijing). Substitua {WorkspaceId} pelo ID real do seu workspace.
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"
    }
}'
modelstring(Obrigatório)Modelo de voice design. Valores válidos:
  • voice-enrollment: Voice design do CosyVoice.
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.
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.
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.
prefix string(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}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"].
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.
Padrão: 24000.response_format string(Opcional)Formato do áudio de pré-visualização.
  • CosyVoice: pcm, wav ou mp3.
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"
}
request_idstringIdentificador exclusivo desta solicitação.
outputobjectDados retornados pelo modelo.

Propriedades

voice_idstringID da voz. Use-o no parâmetro voice da 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

Os exemplos a seguir usam a configuração da região China (Beijing). Substitua {WorkspaceId} pelo ID real do seu workspace.
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
    }
}'
modelstring(Obrigatório)Modelo de voice design. Valores válidos:
  • voice-enrollment: Voice design do CosyVoice.
inputobject(Obrigatório)Objeto de parâmetros de entrada.

Propriedades

action string(Obrigatório)Defina como list_voice.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"
}
request_idstringIdentificador exclusivo desta solicitação.
outputobjectDados retornados pelo modelo.

Propriedades

voice_listarray[object]Lista de vozes retornadas pela consulta.

Propriedades

voice_idstringID da voz. Use-o no parâmetro voice da API TTS.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".voice_promptstringTexto de descrição da voz.preview_textstringTexto do áudio de pré-visualização.
usageobjectInformações de uso desta solicitação.

Propriedades

count integerSempre 1.

Consultar detalhes da voz

Corpo da solicitação

Os exemplos a seguir usam a configuração da região China (Beijing). Substitua {WorkspaceId} pelo ID real do seu workspace.
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"
    }
}'
modelstring(Obrigatório)Modelo de voice design. Valores válidos:
  • voice-enrollment: Voice design do CosyVoice.
inputobject(Obrigatório)Objeto de parâmetros de entrada.

Propriedades

action string(Obrigatório)Defina como query_voice.voice_id string(Obrigatório)
Aplicável apenas ao CosyVoice.
ID 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": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}
request_idstringIdentificador exclusivo desta solicitação.
outputobjectDados retornados pelo modelo.

Propriedades

voice_idstringID da voz. Use-o no parâmetro voice da API TTS.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.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 integerSempre 1.

Exclua uma voz

Corpo da solicitação

Os exemplos a seguir usam a configuração da região China (Beijing). Substitua {WorkspaceId} pelo ID real do seu workspace.
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"
    }
}'
modelstring(Obrigatório)Modelo de voice design. Valores válidos:
  • voice-enrollment: Voice design do CosyVoice.
inputobject(Obrigatório)Objeto de parâmetros de entrada.

Propriedades

action string(Obrigatório)Defina como delete_voice.voice_id string(Obrigatório)
Aplicável apenas ao CosyVoice.
ID da voz a ser excluída.

Corpo da resposta

{
    "output": {},
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}
request_idstringIdentificador exclusivo desta solicitação.
outputobjectDados retornados pelo modelo. É um objeto vazio.
usageobjectInformações de uso desta solicitação.

Propriedades

count integerSempre 1.

Referência de status de voz

As vozes criadas passam por um processo de revisão. Os status a seguir se aplicam a CosyVoice quando model é voice-enrollment.

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.