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/SpeechSynthesizerCabeçalhos
| Cabeçalho | Obrigatório | Descrição |
|---|---|---|
| Authorization | Sim | Bearer <API Key> |
| Content-Type | Sim | application/json |
Exemplo de solicitação
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.
| Campo | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
| model | string | Sim | — | ID do modelo. Consulte Modelos suportados. |
| input | object | Sim | — | Entrada de geração de áudio. |
| input.text_prompt | string | Sim | — | 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.references | array | Nã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_url | string | Condicional | — | URL de áudio pública acessível ao serviço. Forneça este campo ou audio_data, mas não ambos. |
| input.references[].audio_data | string | Condicional | — | URI de dados de áudio: data:{mime_type};base64,{base64_encoded_data}. Mutuamente exclusivo com audio_url. |
| input.format | string | Não | wav | Formato de saída: wav, mp3 ou pcm. A saída Opus não é suportada. |
| input.sample_rate | integer | Não | 48000 | Taxa de amostragem de saída em Hz: 8000, 16000, 24000, 44100 ou 48000. |
| input.channels | integer | Não | 2 | Contagem de canais: 1 (mono) ou 2 (estéreo). |
| input.volume | integer | Não | 50 | Volume. Intervalo: [0, 100]. |
| input.enable_cbr | boolean | Não | false | Apenas MP3. true habilita taxa de bits constante (CBR); false usa taxa de bits variável (VBR). |
| input.bit_rate | integer | Não | 128 | Apenas 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.quality | integer | Não | 5 | Apenas VBR MP3. Intervalo: [0, 9], onde 0 é a qualidade mais alta. |
| input.rate | float | Não | 1.0 | Velocidade da fala. Intervalo: [0.5, 2.0]. |
| input.seed | integer | Não | 42 | Semente aleatória no nível da solicitação. |
| input.enable_aigc_tag | boolean | Não | false | Se deve adicionar uma marca d'água de identificação AIGC ao áudio gerado. |
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) |
|---|---|---|
| 8000 | 8 | 64 |
| 16000, 24000 | 8 | 160 |
| 44100, 48000 | 32 | 320 |
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.
{"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
| Campo | Tipo | Descrição |
|---|---|---|
| request_id | string | ID da solicitação para solução de problemas. |
| output.finish_reason | string | "stop" na conclusão normal. |
| output.audio.data | string | Uma string vazia para este modo de solicitação. Baixe o áudio completo de output.audio.url. |
| output.audio.url | string | URL completa de download de áudio, válida por 24 horas. |
| output.audio.id | string | ID do áudio gerado. |
| output.audio.expires_at | integer | Timestamp de expiração da URL de download. |
| output.audio.duration | float | Duração do áudio gerado em segundos. |
| usage.duration | integer | Duração do áudio gerado arredondada para o segundo inteiro mais próximo. Este campo não é usado para calcular cobranças de tokens. |
Modelos suportados
| ID do modelo | Limite de prompt | Duração máxima gerada por solicitação |
|---|---|---|
| qwen-audio-3.1-tts-next | 3,000 caracteres | Podcasts: 240 segundos (4 minutos); outros cenários: 120 segundos |
Tratamento de erros
Exemplo de resposta de erro:
| Status HTTP | código | Ação |
|---|---|---|
| 400 | CLIENT_ERROR | Verifique 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. |
| 404 | InvalidParameter | Para "Model not exist.", verifique o ID do modelo, a região e a disponibilidade do modelo para sua conta. |
| 401 | InvalidApiKey | Verifique a validade da chave de API. |
| 403 | AccessDenied | Verifique as permissões de acesso ao modelo. |
| 429 | Throttling.RateQuota | Reduza a taxa de solicitações. |
| 400 | DataInspectionFailed | Verifique se o prompt ou o áudio de referência atende aos requisitos de segurança de conteúdo. |
| 500 | InternalError | Mantenha o request_id e tente novamente mais tarde ou entre em contato com o suporte técnico. |