Doubao TTS
Requiere DOUBAO_SPEECH_API_KEY en .env.
Define DOUBAO_SPEECH_VOICE_TYPE para la voz predeterminada, o pasa voice_id a la herramienta.
API Actual
Usa el flujo de clave API de la nueva consola:
X-Api-Key: ${DOUBAO_SPEECH_API_KEY}
X-Api-Resource-Id: seed-tts-2.0
No uses X-Api-App-Id y X-Api-Access-Key con una clave API de nueva consola. Si la API devuelve load grant: requested grant not found, el tipo de clave o el encabezado de autenticación probablemente sean incorrectos.
Para narraciones largas de video, prefiere el endpoint asíncrono:
POST https://openspeech.bytedance.com/api/v3/tts/submit
POST https://openspeech.bytedance.com/api/v3/tts/query
Esto devuelve audio_url más los metadatos de temporización sentences[].words[] que se pueden usar para crear subtítulos.
Uso con OpenMontage
Genera con el selector 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,
})
O llama al proveedor directamente:
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",
})
El proveedor escribe:
output_path: archivo de audio descargadometadata_path: JSON completo de respuesta de consulta, por defecto<output_path>.json
Flujo de Trabajo Recomendado
- Genera una muestra de 10 a 15 segundos antes de una narración completa de pago.
- Pide al usuario que apruebe la naturalidad, el acento y la velocidad de la voz.
- Genera la narración completa solo después de la aprobación.
- Conserva el JSON de consulta. Es la fuente de verdad para la sincronización de subtítulos.
- Crea subtítulos a partir de
sentences[].words[], no a partir de la longitud estimada del texto. - Agrupa los subtítulos por frases semánticas chinas antes de aplicar marcas de tiempo. No dividas solo por un número fijo de caracteres; podría romper frases como "在不押单个公司的情况下" o "可能会被慢慢稀释" y perjudicar la comprensión.
- Deja que la duración del video siga el ritmo de voz aprobado, a menos que el usuario solicite explícitamente coincidir con un tiempo de ejecución anterior.
Parámetros
voice_id:speaker/ tipo de voz de Doubao. Por defecto esDOUBAO_SPEECH_VOICE_TYPE.resource_id: usaseed-tts-2.0para voces de Doubao Speech 2.0.speech_rate:0es normal,100es 2x,-50es 0.5x.sample_rate: por defecto24000.enable_timestamp: por defectotrue.return_usage: por defectotrue, solicita metadatos de uso cuando están disponibles.
No pases additions.explicit_language por defecto. Algunas combinaciones de endpoint/clave rechazan zh-cn con unsupported additions explicit language zh-cn.
Para explicaciones tranquilas en mandarín, comienza con speech_rate: 0. Si el resultado es demasiado largo para el formato aprobado, haz una muestra de comparación corta con speech_rate: 25 o 50 antes de regenerar la narración completa. No aceleres solo para igualar la duración de un proveedor anterior si el usuario prefiere el ritmo natural de Doubao.
Solución de Problemas
load grant: requested grant not found: tipo de clave incorrecto o encabezado de autenticación incorrecto. UsaX-Api-Keypara claves API de nueva consola.speaker permission denied: el ID de voz es incorrecto o no está autorizado para el recurso seleccionado.quota exceeded: se superó la cuota, los caracteres de por vida o la concurrencia.- Faltan marcas de tiempo: verifica
enable_timestamp: true, conserva el JSON de consulta y confirma que el endpoint seleccionado devolviósentences.
Seguridad
Nunca imprimas ni escribas la clave API en registros, metadatos, parches o artefactos del proyecto. .env.example debe contener solo nombres de variables vacíos.