fish.audio TTS
.env 파일에 FISH_AUDIO_API_KEY가 필요합니다 (https://fish.audio/go-api/api-keys/에서 생성 가능).
fish.audio 플레이그라운드에서 음성 모델을 생성하고, 해당 ID를 reference_id로 전달하여 복제된 음성을 재사용하세요.
현재 API
원시 오디오 바이트를 반환하는 단일 동기 호출:
POST https://api.fish.audio/v1/tts
Authorization: Bearer ${FISH_AUDIO_API_KEY}
Content-Type: application/json
model: <백엔드 모델> # HTTP 헤더로 백엔드 선택 (예: s1)
백엔드 모델은 본문 필드가 아닌 model HTTP 헤더로 선택됩니다. OpenMontage에서는 도구의 model 입력에 매핑됩니다.
백엔드 모델
model은 필수이며 기본값이 없습니다. 다음 중 하나를 전달하세요:
s2.1-pro— 최신 세대. 최고 품질: 인라인 감정 태그, 80개 이상의 언어, 다중 화자. 최고의 내레이션.s2.1-pro-free— 프로모션 s2.1-pro 무료 액세스. 프로모션 기간 동안만 초안, 샘플 및 검증 실행 시 $0. fish.audio 공지에 따라: 2026년 8월 31일까지 무료, 공정 사용(Fair Use) 적용, SLA/지연 시간 보장 없음, 요청이 보관될 수 있음, 상업적 사용 제한. 프로덕션 또는 클라이언트 내레이션에는 절대 사용하지 마세요.s2-pro— 최초 S2 세대. 감정 태그 지원이 포함된 안정적인 고품질.s1— 이전 주력 모델. 기존 통합과의 호환성을 위해 유지.
과금은 입력 텍스트의 UTF-8 바이트당 (문자가 아님) 부과됩니다. CJK 텍스트와 이모티콘은 동일한 시각적 길이의 ASCII 문자보다 3~4배 더 비쌉니다. 현재 목록 가격: s1 / s2-pro / s2.1-pro = 1M 바이트당 $15, s2.1-pro-free = 프로모션 기간 동안만 $0 (도구의 estimate_cost()는 2026년 8월 31일 이후 유료 s2.1-pro 요금으로 전환됨). 대량 배치 전에 https://docs.fish.audio/developer-guide/models-pricing/pricing-and-rate-limits 에서 현재 가격을 확인하세요.
인라인 감정 태그 (S2 모델 전용)
s2-pro / s2.1-pro / s2.1-pro-free는 텍스트에 포함된 인라인 감정 태그를 해석합니다:
[laugh],[whispers]같은 태그는 문장 중간에 전달 방식을 변경합니다.- 예시:
"That's hilarious [laugh] but let me explain seriously." s1은 감정 태그를 해석하지 않습니다. 일반 텍스트로 읽힐 수 있으므로 s1을 대상으로 할 때는 태그를 제거하세요.
음성 선택 (reference_id)
- fish.audio 플레이그라운드에서 음성을 빌드하거나 선택한 다음, 해당 모델 ID를 복사하세요.
reference_id로 전달합니다. 선택기의 일반voice_id가reference_id가 없을 때 별칭으로 허용됩니다.reference_id가 없으면 fish.audio는 선택한 모델의 기본 음성을 사용합니다.
인라인 즉석 복제(요청당 참조 오디오 + 텍스트 업로드)는 이 도구에서 지원되지 않습니다. 먼저 플레이그라운드에서 음성 모델을 생성하세요.
OpenMontage 사용법
TTS 선택기로 생성:
from tools.audio.tts_selector import TTSSelector
result = TTSSelector().execute({
"preferred_provider": "fish_audio",
"text": "복리 이자가 어떻게 모든 빠른 부자 되기 계획을 조용히 이기는지 설명합니다.",
"model": "s1",
"reference_id": "<플레이그라운드 음성 모델 ID>",
"output_path": "projects/my-video/assets/audio/narration.mp3",
})
또는 공급자를 직접 호출:
from tools.audio.fish_audio_tts import FishAudioTTS
result = FishAudioTTS().execute({
"text": "승인을 위한 짧은 샘플 라인입니다.",
"model": "s1",
"reference_id": "<플레이그라운드 음성 모델 ID>",
"output_path": "projects/my-video/assets/audio/fish_sample.mp3",
})
공급자는 output_path에 오디오를 쓰고 data.output과 함께 확인된 model 및 reference_id를 반환합니다.
품질 및 지연 시간 튜닝
latency:normal(기본, 최고 품질),balanced(약간 더 빠름), 또는low(가장 빠름, 약간의 품질 저하).normalize: 기본true; 켜두면 숫자, 날짜 및 통화가 자연스럽게 읽힙니다.prosody: 선택적{ "speed": 1.0, "volume": 0 }으로 속도/음량을 조정합니다.mp3_bitrate:128이 좋은 기본값입니다. 음악이 많이 섞인 믹스의 경우192로 올리세요.temperature: 기본0.7. 감정 태그에 의존할 때는0.9쪽으로 올리면 더 표현력 있는 읽기가 가능합니다 (권장). 더 안정적이고 예측 가능한 전달을 위해서는 낮춥니다.top_p/repetition_penalty: 일반적으로 기본값(0.7/1.2)을 그대로 둡니다.
권장 워크플로우
- 전체 유료 내레이션 전에 선택한
model+reference_id로 10~15초 샘플을 생성합니다. - 사용자에게 음성 자연스러움, 감정 및 속도 승인을 요청합니다.
- 승인 후에만 전체 내레이션을 생성합니다.
- 비용이 중요한 배치/지역화 변형의 경우
s2.1-pro-free에서 프로토타입을 만들고(프로모션 기간 $0, 비상업적 초안 전용) 최종 버전을s2.1-pro로 업그레이드합니다.
문제 해결
401 Unauthorized:FISH_AUDIO_API_KEY가 잘못되었거나 누락되었습니다.402/ 결제 오류: 계정 크레딧이 소진되었습니다.404/ 잘못된 음성:reference_id가 잘못되었거나 이 계정 소유가 아닙니다.- 빈/짧은 오디오:
text가 비어 있지 않은지,normalize가 전체 입력을 제거하지 않는지 확인하세요.
안전
API 키를 로그, 메타데이터, 패치 또는 프로젝트 아티팩트에 절대 출력하거나 기록하지 마세요. .env.example에는 빈 변수 이름만 포함되어야 합니다.