Skip to main content

Referência da API de geração de áudio

Envie prompts de texto e áudio de referência via HTTPS para receber arquivos de áudio gerados. Esta página descreve solicitações, respostas e tratamento de erros.

Pré-requisitos

Obtenha uma chave de API e um ID de workspace da região selecionada. Defina-os como as variáveis de ambiente DASHSCOPE_API_KEY e SFM_WORKSPACE_ID. Os exemplos abaixo usam Pequim. Envie solicitações HTTPS POST para o seguinte endpoint. Substitua {WorkspaceId} pelo seu ID de workspace.
  • Singapura
  • China (Pequim)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer

Cabeçalhos

CabeçalhoObrigatórioDescrição
AuthorizationSimBearer <API Key>
Content-TypeSimapplication/json

Exemplo de solicitação

curl --request POST \
  "https://$SFM_WORKSPACE_ID.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer" \
  --max-time 300 \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "qwen-audio-3.1-tts-next",
    "input": {
      "text_prompt": "A woman clearly says: Hello, welcome.",
      "format": "wav",
      "sample_rate": 48000,
      "channels": 2
    }
  }'
Exemplo de resposta, com IDs ilustrativos e uma URL de download de espaço reservado:
{
  "request_id": "example-request-id",
  "output": {
    "finish_reason": "stop",
    "audio": {
      "data": "",
      "url": "https://example.com/generated.wav",
      "id": "audio_example-request-id",
      "expires_at": 1789616932,
      "duration": 1.12
    }
  },
  "usage": {
    "duration": 1
  }
}
Baixe o arquivo usando output.audio.url da resposta real. A URL é válida por 24 horas. Não use a URL de espaço reservado acima para baixar o áudio.

Parâmetros da solicitação

model é um campo de nível superior. Todos os parâmetros de geração pertencem ao objeto input.
CampoTipoObrigatórioPadrãoDescrição
modelstringSim—ID do modelo. Consulte Modelos suportados.
inputobjectSim—Entrada de geração de áudio.
input.text_promptstringSim—Descrição de áudio ou texto a ser sintetizado. Use @voice1, @voice2 e @voice3 para referenciar clipes de áudio em ordem. Os limites de comprimento estão listados na tabela de modelos.
input.referencesarrayNão—Clipes de áudio de referência. Omita para geração apenas de texto. O modelo atual aceita até 3 clipes, cada um com no máximo 30 segundos e não maior que 10 MB.
input.references[].audio_urlstringCondicional—URL de áudio pública acessível ao serviço. Forneça este campo ou audio_data, mas não ambos.
input.references[].audio_datastringCondicional—URI de dados de áudio: data:{mime_type};base64,{base64_encoded_data}. Mutuamente exclusivo com audio_url.
input.formatstringNãowavFormato de saída: wav, mp3 ou pcm. A saída Opus não é suportada.
input.sample_rateintegerNão48000Taxa de amostragem de saída em Hz: 8000, 16000, 24000, 44100 ou 48000.
input.channelsintegerNão2Contagem de canais: 1 (mono) ou 2 (estéreo).
input.volumeintegerNão50Volume. Intervalo: [0, 100].
input.enable_cbrbooleanNãofalseApenas MP3. true habilita taxa de bits constante (CBR); false usa taxa de bits variável (VBR).
input.bit_rateintegerNão128Apenas CBR MP3, em kbps. A saída real depende da taxa de amostragem e dos níveis de taxa de bits MP3 suportados. Veja abaixo.
input.qualityintegerNão5Apenas VBR MP3. Intervalo: [0, 9], onde 0 é a qualidade mais alta.
input.ratefloatNão1.0Velocidade da fala. Intervalo: [0.5, 2.0].
input.seedintegerNão42Semente aleatória no nível da solicitação.
input.enable_aigc_tagbooleanNãofalseSe deve adicionar uma marca d'água de identificação AIGC ao áudio gerado.
O áudio de referência suporta WAV, MP3 e OGG Opus, mas não PCM bruto. Os formatos de referência e de saída têm limites diferentes: OGG Opus pode ser usado como entrada, mas Opus não pode ser usado como saída. Envie o áudio de referência por meio de uma URL ou dados Base64, não por meio de um ID de voz do sistema ou clonada.

Taxa de bits CBR MP3

Taxa de amostragem (Hz)Taxa de bits mínima de saída (kbps)Taxa de bits máxima de saída (kbps)
8000864
16000, 240008160
44100, 4800032320
A taxa de amostragem e os níveis de taxa de bits MP3 determinam a taxa de bits de saída. A tabela lista os limites de saída, não o suporte para cada número inteiro em cada intervalo. Valores fora do intervalo são restritos aos limites correspondentes.

Enviar áudio de referência

Este exemplo em Python usa dois clipes de áudio de referência para gerar uma conversa com dois falantes. Instale requests, prepare reference1.wav e reference2.wav, cada um contendo um falante diferente e atendendo aos limites do modelo, e defina as variáveis de ambiente descritas acima. Os slots seguem a ordem da lista references: o primeiro item, reference1.wav, corresponde a @voice1; o segundo item, reference2.wav, corresponde a @voice2. O exemplo codifica cada clipe em Base64 e referencia ambos os falantes no prompt.
import base64
import os
from pathlib import Path

import requests

reference1 = base64.b64encode(Path("reference1.wav").read_bytes()).decode("ascii")
reference2 = base64.b64encode(Path("reference2.wav").read_bytes()).decode("ascii")
workspace_id = os.environ["SFM_WORKSPACE_ID"]
endpoint = (
    f"https://{workspace_id}.cn-beijing.maas.aliyuncs.com"
    "/api/v1/services/audio/tts/SpeechSynthesizer"
)
response = requests.post(
    endpoint,
    headers={
        "Authorization": f"Bearer {os.environ['DASHSCOPE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "qwen-audio-3.1-tts-next",
        "input": {
            "text_prompt": "@voice1 says: It is sunny today. Shall we take a walk? @voice2 replies: Sure, let us go to the park.",
            "references": [
                {"audio_data": f"data:audio/wav;base64,{reference1}"},
                {"audio_data": f"data:audio/wav;base64,{reference2}"}
            ],
            "format": "wav",
        },
    },
    timeout=300,
)
response.raise_for_status()
result = response.json()
audio_response = requests.get(result["output"]["audio"]["url"], timeout=60)
audio_response.raise_for_status()
Path("output.wav").write_bytes(audio_response.content)
Para usar uma URL, substitua o item da lista por {"audio_url": "publicly accessible audio URL"} e omita audio_data. Os números de referência seguem a ordem da lista e devem apontar para itens existentes.

Parâmetros da resposta

CampoTipoDescrição
request_idstringID da solicitação para solução de problemas.
output.finish_reasonstring"stop" na conclusão normal.
output.audio.datastringUma string vazia para este modo de solicitação. Baixe o áudio completo de output.audio.url.
output.audio.urlstringURL completa de download de áudio, válida por 24 horas.
output.audio.idstringID do áudio gerado.
output.audio.expires_atintegerTimestamp de expiração da URL de download.
output.audio.durationfloatDuração do áudio gerado em segundos.
usage.durationintegerDuração do áudio gerado arredondada para o segundo inteiro mais próximo. Este campo não é usado para calcular cobranças de tokens.
As solicitações de podcast podem gerar até 240 segundos (4 minutos) de áudio; outros cenários são limitados a 120 segundos por solicitação. Para preços, consulte Preços do modelo.

Modelos suportados

ID do modeloLimite de promptDuração máxima gerada por solicitação
qwen-audio-3.1-tts-next3,000 caracteresPodcasts: 240 segundos (4 minutos); outros cenários: 120 segundos
Para casos de uso, exemplos de áudio e orientação de prompts, consulte Geração de áudio. Os exemplos neste documento usam este modelo.

Tratamento de erros

Exemplo de resposta de erro:
{
  "request_id": "example-request-id",
  "code": "CLIENT_ERROR",
  "message": "text_prompt exceeds the maximum length of 3000 characters."
}
Status HTTPcódigoAção
400CLIENT_ERRORVerifique o comprimento do prompt, a contagem e a duração das referências, a exclusividade de URL/Base64, os índices de referência e o uso do campo de voz não suportado.
404InvalidParameterPara "Model not exist.", verifique o ID do modelo, a região e a disponibilidade do modelo para sua conta.
401InvalidApiKeyVerifique a validade da chave de API.
403AccessDeniedVerifique as permissões de acesso ao modelo.
429Throttling.RateQuotaReduza a taxa de solicitações.
400DataInspectionFailedVerifique se o prompt ou o áudio de referência atende aos requisitos de segurança de conteúdo.
500InternalErrorMantenha o request_id e tente novamente mais tarde ou entre em contato com o suporte técnico.