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 ni X-Api-Access-Key con una clave API de la 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 en video largas, 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 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 la respuesta de consulta, por defecto<output_path>.json
Flujo de Trabajo Recomendado
- Genera una muestra de 10-15 segundos antes de una narración paga completa.
- 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 única fuente verdadera 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 chinas antes de aplicar las marcas de tiempo. No dividas solo por un número fijo de caracteres, ya que podría romper frases como "在不押单个公司的情况下" o "可能会被慢慢稀释" y perjudicar la comprensión.
- Deja que la duración del video siga el ritmo de la voz aprobada, a menos que el usuario pida explícitamente ajustarse a 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 comparativa corta con speech_rate: 25 o 50 antes de regenerar la narración completa. No aceleres solo para igualar la duración de otro proveedor 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.