Doubao TTS
Requer DOUBAO_SPEECH_API_KEY no .env.
Defina DOUBAO_SPEECH_VOICE_TYPE para a voz padrão, ou passe voice_id para a ferramenta.
API Atual
Use o fluxo de chave API do novo console:
X-Api-Key: ${DOUBAO_SPEECH_API_KEY}
X-Api-Resource-Id: seed-tts-2.0
Não use X-Api-App-Id e X-Api-Access-Key com uma chave API do novo console. Se a API retornar load grant: requested grant not found, o tipo de chave ou o cabeçalho de autenticação provavelmente está errado.
Para narração de vídeos longos, prefira o endpoint assíncrono:
POST https://openspeech.bytedance.com/api/v3/tts/submit
POST https://openspeech.bytedance.com/api/v3/tts/query
Isso retorna audio_url além dos metadados de tempo sentences[].words[] que podem ser usados para construir legendas.
Uso com OpenMontage
Gere com o seletor de TTS:
from tools.audio.tts_selector import TTSSelector
result = TTSSelector().execute({
"preferred_provider": "doubao",
"text": "如果 AI 真的会改变未来,普通人到底该怎么参与?",
"voice_id": "zh_female_vv_uranus_bigtts",
"output_path": "projects/my-video/assets/audio/narration.mp3",
"speech_rate": 0,
"enable_timestamp": True,
})
Ou chame o provedor diretamente:
from tools.audio.doubao_tts import DoubaoTTS
result = DoubaoTTS().execute({
"text": "短样本试听文本。",
"voice_id": "zh_female_vv_uranus_bigtts",
"output_path": "projects/my-video/assets/audio/doubao_sample.mp3",
})
O provedor escreve:
output_path: arquivo de áudio baixadometadata_path: resposta JSON completa da consulta, padrão é<output_path>.json
Fluxo de Trabalho Recomendado
- Gere uma amostra de 10 a 15 segundos antes de uma narração completa paga.
- Peça ao usuário para aprovar a naturalidade da voz, sotaque e velocidade.
- Gere a narração completa somente após a aprovação.
- Mantenha o JSON da consulta. Ele é a fonte da verdade para o tempo das legendas.
- Construa legendas a partir de
sentences[].words[], não do comprimento estimado do texto. - Agrupe legendas por frases semânticas chinesas antes de aplicar timestamps. Não divida apenas por contagem fixa de caracteres; isso pode quebrar frases como "在不押单个公司的情况下" ou "可能会被慢慢稀释" e prejudicar a compreensão.
- Deixe a duração do vídeo seguir o ritmo da voz aprovada, a menos que o usuário peça explicitamente para corresponder a um tempo de execução anterior.
Parâmetros
voice_id: Tipo de voz /speakerdo Doubao. Padrão éDOUBAO_SPEECH_VOICE_TYPE.resource_id: useseed-tts-2.0para vozes do Doubao Speech 2.0.speech_rate:0é normal,100é 2x,-50é 0.5x.sample_rate: padrão24000.enable_timestamp: padrãotrue.return_usage: padrãotrue, solicita metadados de uso quando disponível.
Não passe additions.explicit_language por padrão. Algumas combinações de endpoint/chave rejeitam zh-cn com unsupported additions explicit language zh-cn.
Para vídeos explicativos em mandarim calmo, comece com speech_rate: 0. Se o resultado for muito longo para o formato aprovado, faça uma amostra de comparação curta com speech_rate: 25 ou 50 antes de regenerar a narração completa. Não acelere apenas para corresponder à duração de um provedor anterior se o usuário preferir o ritmo natural do Doubao.
Solução de Problemas
load grant: requested grant not found: tipo de chave errado ou cabeçalho de autenticação errado. UseX-Api-Keypara chaves API do novo console.speaker permission denied: o id da voz está errado ou não autorizado para o recurso selecionado.quota exceeded: cota, caracteres vitalícios ou concorrência excedidos.- Faltando timestamps: verifique
enable_timestamp: true, mantenha o JSON da consulta e confirme que o endpoint selecionado retornousentences.
Segurança
Nunca imprima ou escreva a chave da API em logs, metadados, patches ou artefatos do projeto. .env.example deve conter apenas nomes de variáveis vazios.