¿Qué hace 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 ni 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 sean incorrectos.
Para narraciones largas en vídeo, 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 metadatos de tiempo sentences[].words[] que se pueden usar para construir subtítulos.
Uso en OpenMontage
Genera con el selector 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,
})
O llama directamente al proveedor:
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: respuesta JSON completa de la 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 de la voz, el acento y la velocidad.
- 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 longitud estimada del texto. - Agrupa los subtítulos por frases semánticas en chino 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 vídeo siga el ritmo de voz aprobado, a menos que el usuario pida explícitamente que coincida con una duración anterior.
Parámetros
voice_id: tipo de voz /speakerde 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 explicadores tranquilos 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 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.