Doubao TTS
Requiere DOUBAO_SPEECH_API_KEY en .env.
Establece 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 la nueva consola. Si la API devuelve load grant: requested grant not found, probablemente el tipo de clave o el encabezado de autenticación son incorrectos.
Para narración de video larga, 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 sincronización de sentences[].words[] que se pueden usar para crear subtítulos.
Uso en 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 la respuesta de la consulta, por defecto<output_path>.json
Flujo de Trabajo Recomendado
- Genera una muestra de 10-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 la consulta. Es la fuente de verdad para la sincronización de subtítulos.
- Construye los subtítulos a partir de
sentences[].words[], no de la estimación de la longitud del texto. - Agrupa los subtítulos por frases semánticas chinas antes de aplicar las marcas de tiempo. No dividas solo por un número fijo de caracteres; puede 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 pida explícitamente igualar un tiempo de ejecución anterior.
Parámetros
voice_id:speaker/ tipo de voz de Doubao. Por defectoDOUBAO_SPEECH_VOICE_TYPE.resource_id: usaseed-tts-2.0para las 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 calmadas en mandarín, empieza con speech_rate: 0. Si el resultado es demasiado largo para el formato aprobado, haz una muestra de comparación breve 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 las claves API de la 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 la 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.