Doubao TTS
.env 파일에 DOUBAO_SPEECH_API_KEY가 필요합니다.
기본 음성을 설정하려면 DOUBAO_SPEECH_VOICE_TYPE을 설정하거나, 도구에 voice_id를 전달하세요.
현재 API
새 콘솔 API 키 흐름을 사용하세요:
X-Api-Key: ${DOUBAO_SPEECH_API_KEY}
X-Api-Resource-Id: seed-tts-2.0
새 콘솔 API 키와 함께 X-Api-App-Id 및 X-Api-Access-Key를 사용하지 마세요. API가 load grant: requested grant not found를 반환하면 키 유형이나 인증 헤더가 잘못된 것입니다.
긴 형식의 비디오 내레이션의 경우 비동기 엔드포인트를 선호합니다:
POST https://openspeech.bytedance.com/api/v3/tts/submit
POST https://openspeech.bytedance.com/api/v3/tts/query
이 엔드포인트는 audio_url과 자막 제작에 사용할 수 있는 sentences[].words[] 타이밍 메타데이터를 반환합니다.
OpenMontage 사용법
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,
})
또는 제공자를 직접 호출:
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",
})
제공자는 다음을 기록합니다:
output_path: 다운로드된 오디오 파일metadata_path: 전체 쿼리 응답 JSON, 기본값<output_path>.json
권장 워크플로우
- 전체 유료 내레이션 전에 10-15초 샘플을 생성하세요.
- 사용자에게 음색, 억양, 속도에 대한 승인을 요청하세요.
- 승인 후에만 전체 내레이션을 생성하세요.
- 쿼리 JSON을 보관하세요. 자막 타이밍의 진실 공급원입니다.
- 예상 텍스트 길이가 아닌
sentences[].words[]에서 자막을 작성하세요. - 타임스탬프를 적용하기 전에 중국어 의미 구문 단위로 자막을 그룹화하세요. 고정된 문자 수로만 분할하지 마십시오. "在不押单个公司的情况下" 또는 "可能会被慢慢稀释"와 같은 구문이 깨져 이해도를 떨어뜨릴 수 있습니다.
- 사용자가 명시적으로 이전 런타임과 일치하도록 요청하지 않는 한 비디오 길이는 승인된 음성 리듬을 따르도록 하세요.
파라미터
voice_id: Doubaospeaker/ 음성 유형. 기본값은DOUBAO_SPEECH_VOICE_TYPE입니다.resource_id: Doubao Speech 2.0 음성에는seed-tts-2.0을 사용하세요.speech_rate:0은 보통,100은 2배속,-50은 0.5배속입니다.sample_rate: 기본값24000.enable_timestamp: 기본값true.return_usage: 기본값true, 사용 가능한 경우 사용 메타데이터를 요청합니다.
기본적으로 additions.explicit_language를 전달하지 마세요. 일부 엔드포인트/키 조합은 zh-cn을 unsupported additions explicit language zh-cn 오류와 함께 거부합니다.
조용한 중국어 설명 영상의 경우 speech_rate: 0으로 시작하세요. 결과가 승인된 형식에 비해 너무 길면 전체 내레이션을 다시 생성하기 전에 speech_rate: 25 또는 50으로 짧은 비교 샘플을 만드세요. 사용자가 Doubao의 자연스러운 속도를 선호하는 경우 이전 제공자의 길이에 맞추기 위해서만 속도를 높이지 마세요.
문제 해결
load grant: requested grant not found: 잘못된 키 유형 또는 잘못된 인증 헤더. 새 콘솔 API 키에는X-Api-Key를 사용하세요.speaker permission denied: 음성 ID가 잘못되었거나 선택한 리소스에 대해 권한이 없습니다.quota exceeded: 할당량, 평생 문자 수 또는 동시 실행 수가 초과되었습니다.- 타임스탬프 누락:
enable_timestamp: true인지 확인하고, 쿼리 JSON을 보관하며, 선택한 엔드포인트가sentences를 반환했는지 확인하세요.
안전
API 키를 로그, 메타데이터, 패치 또는 프로젝트 아티팩트에 절대 출력하거나 기록하지 마세요. .env.example에는 빈 변수 이름만 포함되어야 합니다.