Fish Audio S2 API는 1천만 시간의 오디오로 학습된 40억 개의 매개변수 모델로 구동되는 프로덕션 등급의 텍스트 음성 변환(TTS) REST API입니다. 음성 복제, 스트리밍, 50개 이상의 언어를 지원합니다. 요청 전송, 참조 관리, 단위 테스트 실행 등 Fish Audio S2 API를 효율적으로 사용하려면 Apidog가 모든 엔드포인트를 탐색, 문서화 및 검증하는 가장 빠른 방법입니다.
소개
AI 생성 음성은 임계점을 넘어섰습니다. 최신 TTS 모델은 더 이상 로봇처럼 들리지 않고 속삭이고, 웃고, 문장 중간에 톤을 바꿉니다. Fish Audio S2 API는 이러한 변화의 선두에 서 있습니다. 1천만 시간 이상의 다국어 오디오로 학습된 40억 개의 매개변수 모델은 사람의 녹음과 구별할 수 없는 음성을 생성할 수 있습니다.
팟캐스트 자동화, 대화형 음성 비서, 실시간 더빙 파이프라인 등 다양한 시나리오에서 Fish Audio S2 API를 스택에 통합하려면 단순한 POST 요청 이상이 필요합니다. 인증, 참조 오디오 관리, 스트리밍 동작, 프로덕션 환경에서 안정적인 단위 테스트 작성이 필수적입니다.
💡Fish Audio S2 API를 처음 호출하기 전에 Apidog를 무료로 다운로드하세요. 코드 없이 몇 초 만에 감정 태그, 스트리밍 청크, 음성 복제 페이로드 및 이진 오디오 응답을 시각적으로 테스트할 수 있습니다. 즉시 목업, 검증, 청취하여 TTS 통합이 첫날부터 완벽하게 작동하도록 합니다.
Fish Audio S2 API란 무엇인가요?
Fish Audio S2 API는 이중-자기회귀(Dual-AR) 아키텍처를 기반으로 구축된 오픈 소스 TTS 시스템인 Fish Speech S2-Pro의 HTTP 인터페이스입니다. 의미론적 생성과 잔여 코드북 생성을 분리하여 단일 NVIDIA H200에서 0.195의 실시간 계수(real-time factor)로 고품질 합성을 제공합니다.
주요 Fish Audio S2 API 기능:
| 기능 | 세부 정보 |
|---|---|
| 언어 | ~50개 (영어, 중국어, 일본어, 한국어, 아랍어, 프랑스어, 독일어 등) |
| 음성 복제 | 10~30초 참조 오디오, 미세 조정 필요 없음 |
| 인라인 감정 제어 | 자연어 태그: [laugh], [whispers], [super happy]
|
| 다중 화자 생성 | 기본 <|speaker:i|> 토큰 지원 |
| 스트리밍 |
"streaming": true로 실시간 청크 오디오 지원 |
| 출력 형식 | WAV, MP3, PCM |
| 인증 | 베어러 토큰 (Authorization: Bearer YOUR_API_KEY) |
로컬 배포 시 기본 URL: http://127.0.0.1:8080, 모든 엔드포인트는 /v1/ 네임스페이스 아래에 있습니다.
Fish Audio S2 API 및 Apidog 시작하기
필수 조건
Fish Audio S2 API를 사용하려면 먼저 두 가지가 필요합니다: Fish Speech S2-Pro 서버와 이진 오디오 응답을 처리할 수 있는 API 클라이언트.
Fish Audio S2 API 서버 구동:
python tools/api_server.py \
--llama-checkpoint-path checkpoints/s2-pro \
--decoder-checkpoint-path checkpoints/s2-pro/codec.pth \
--listen 0.0.0.0:8080 \
--compile \
--half \
--api-key YOUR_API_KEY \
--workers 4
--compile은 torch.compile로 추론 지연을 단축하고, --half는 GPU 메모리 사용량을 줄입니다.
상태 체크:
curl http://127.0.0.1:8080/v1/health
# {"status":"ok"}
Apidog에서 Fish Audio S2 API 연결
Apidog를 무료로 다운로드 후 새 HTTP 프로젝트를 생성하세요. 환경(Environments)에 http://127.0.0.1:8080을 추가하고, 전역 헤더에 다음을 입력합니다:
Authorization: Bearer YOUR_API_KEY
이렇게 하면 모든 요청에 인증 헤더가 자동 적용됩니다. 환경별 전환도 간편합니다.
Apidog에서 첫 Fish Audio S2 API 요청
/v1/tts 엔드포인트 TTS 요청
Apidog에서 POST /v1/tts 요청을 아래와 같이 작성하세요:
{
"text": "Hello! This is a test of the Fish Audio S2 API.",
"format": "wav",
"streaming": false,
"temperature": 0.8,
"top_p": 0.8,
"repetition_penalty": 1.1,
"max_new_tokens": 1024
}
TTS 요청 주요 스키마:
| 매개변수 | 유형 | 기본값 | 설명 |
|---|---|---|---|
text |
string | 필수 | 합성할 텍스트 |
format |
string | "wav" |
오디오 형식: wav, mp3, pcm
|
chunk_length |
int | 200 | 합성 청크 크기 (100–300) |
seed |
int | null | 시드 고정(재현성) |
streaming |
bool | false | 실시간 청크 오디오 반환 |
max_new_tokens |
int | 1024 | 최대 토큰 수 |
temperature |
float | 0.8 | 샘플링 무작위성 (0.1–1.0) |
top_p |
float | 0.8 | 핵심 샘플링 임계값 (0.1–1.0) |
repetition_penalty |
float | 1.1 | 반복 시퀀스 페널티 (0.9–2.0) |
use_memory_cache |
string | "off" |
메모리 캐시 사용 |
보내기(Send)를 누르면, Fish Audio S2 API가 원시 오디오 바이트를 반환합니다. Apidog가 audio/wav 응답을 자동 감지해 인라인 오디오 플레이어로 바로 재생할 수 있습니다.
Fish Audio S2 API 음성 복제
Apidog로 참조 오디오 업로드 및 복제
제로샷 음성 복제를 하려면 references 필드로 base64 인코딩된 오디오 클립을 전달하세요.
1. POST /v1/references/add로 참조 업로드:
{
"id": "my-voice-clone",
"text": "This is the reference transcription matching the audio.",
"audio": "<base64-encoded-wav-bytes>"
}
Apidog에서 이진(Binary) 또는 폼 데이터(Form Data)를 이용해 파일을 업로드할 수 있습니다.
2. 반환 예시:
{
"success": true,
"message": "Reference added successfully",
"reference_id": "my-voice-clone"
}
3. TTS 요청 시 reference_id 사용:
{
"text": "This sentence will be spoken in the cloned voice.",
"reference_id": "my-voice-clone",
"format": "mp3"
}
Apidog의 참조 관리 패널을 활용하여 여러 복제 음성 테스트도 쉽게 반복할 수 있습니다.
Fish Audio S2 API 단위 테스트
단위 테스트가 필요한 이유
자동화된 단위 테스트 없이 Fish Audio S2 API 통합에는 다양한 실패 지점이 존재합니다(존재하지 않는 참조 ID, 범위를 벗어난 temperature, 잘못된 스트리밍 응답 등). 단위 테스트로 회귀 오류를 사전에 방지하세요.
Python 단위 테스트 예시 (pytest + httpx)
import pytest
import httpx
import base64
BASE_URL = "http://127.0.0.1:8080"
API_KEY = "YOUR_API_KEY"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
class TestFishAudioS2API:
"""Fish Audio S2 API 엔드포인트에 대한 단위 테스트."""
def test_health_check(self):
"""상태 엔드포인트 체크"""
response = httpx.get(f"{BASE_URL}/v1/health", headers=HEADERS)
assert response.status_code == 200
assert response.json()["status"] == "ok"
def test_tts_basic_request(self):
"""TTS가 이진 오디오 반환"""
payload = {
"text": "Unit test: verifying Fish Audio S2 API TTS output.",
"format": "wav",
"seed": 42,
}
response = httpx.post(
f"{BASE_URL}/v1/tts",
json=payload,
headers=HEADERS,
timeout=60,
)
assert response.status_code == 200
assert response.headers["content-type"] == "audio/wav"
assert len(response.content) > 1000
def test_tts_invalid_temperature_raises_error(self):
"""범위 밖 온도 값 에러 확인"""
payload = {"text": "test", "temperature": 99.0}
response = httpx.post(
f"{BASE_URL}/v1/tts",
json=payload,
headers=HEADERS,
timeout=30,
)
assert response.status_code == 422
def test_reference_add_and_list(self):
"""참조 추가/조회/삭제 테스트"""
with open("test_reference.wav", "rb") as f:
audio_b64 = base64.b64encode(f.read()).decode()
add_response = httpx.post(
f"{BASE_URL}/v1/references/add",
json={
"id": "unit-test-voice",
"text": "This is a unit test reference audio.",
"audio": audio_b64,
},
headers=HEADERS,
)
assert add_response.json()["success"] is True
list_response = httpx.get(
f"{BASE_URL}/v1/references/list", headers=HEADERS
)
assert "unit-test-voice" in list_response.json()["reference_ids"]
# 단위 테스트 후 참조 삭제
httpx.request(
"DELETE",
f"{BASE_URL}/v1/references/delete",
json={"reference_id": "unit-test-voice"},
headers=HEADERS,
)
실행:
pytest test_fish_audio_s2_api.py -v
Apidog에서 테스트 시나리오 자동화
Apidog의 테스트 시나리오(Test Scenarios) 기능으로 Python 환경 없이도 Fish Audio S2 API 단위 테스트를 자동화할 수 있습니다:
- Fish Audio S2 API 컬렉션 열기
- 테스트 시나리오 → 새 시나리오 클릭
- 요청 추가: 상태 확인 → TTS → 참조 추가 → 참조 목록
- TTS 요청의 어설션에 다음 추가:
- 응답 상태 =
200 - 헤더
content-type에audio포함 - 응답 시간 <
30000ms
- 응답 상태 =
- 실행(Run) 클릭
테스트 결과 리포트와 diff 뷰, CI 연동 등 자동화된 테스트 러너로 활용할 수 있습니다.
고급 기능
오디오 스트리밍
실시간 애플리케이션에서는 "streaming": true로 청크 스트리밍을 사용하세요:
import httpx
with httpx.stream(
"POST",
"http://127.0.0.1:8080/v1/tts",
json={
"text": "실시간으로 Fish Audio S2 API에서 오디오 스트리밍.",
"format": "wav",
"streaming": True,
},
headers={"Authorization": "Bearer YOUR_API_KEY"},
timeout=None,
) as response:
with open("streamed_output.wav", "wb") as audio_file:
for chunk in response.iter_bytes(chunk_size=4096):
audio_file.write(chunk)
전체 합성 전에 오디오 바이트 반환이 시작됩니다(첫 오디오까지 약 100ms).
인라인 감정 제어
text 필드에 감정 태그를 직접 삽입하세요:
{
"text": "[whispers] 비밀은 여기에 숨겨져 있습니다. [super happy] 찾았다!",
"format": "wav"
}
예시 태그: [laugh], [cough], [pitch up], [professional broadcast tone], [whisper in small voice]
결론
Fish Audio S2 API는 REST 인터페이스로 강력한 TTS 엔진을 제공합니다. 기본 합성, 제로샷 음성 복제, 실시간 스트리밍 등 모든 워크플로우를 6개 엔드포인트로 커버합니다. 성공적인 통합을 위해서는 샘플링 파라미터(예: temperature, top_p, repetition_penalty) 세팅, 참조 오디오 관리, 단위 테스트 코드 구축이 중요합니다.
Apidog를 통해 2분 만에 첫 Fish Audio S2 API 요청, 인라인 오디오 검증, 클라이언트 코드 생성, 자동화된 단위 테스트까지 한 번에 진행하세요. 팀 공유, 문서 자동화, 테스트 자동화까지 개발 워크플로우를 빠르게 최적화할 수 있습니다.
Apidog를 무료로 다운로드 후 Fish Audio S2 API 컬렉션을 바로 가져와 테스트를 시작해보세요.
자주 묻는 질문
Fish Audio S2 API란? 1천만 시간 오디오로 학습된 40억 파라미터 TTS 모델 Fish Speech S2-Pro의 REST API입니다. /v1/ 엔드포인트에서 음성 복제, 스트리밍, 감정 제어, 50+ 언어 지원.
인증 방법? 모든 요청 헤더에 Authorization: Bearer YOUR_API_KEY 사용. 서버 구동 시 --api-key로 지정. Apidog 환경 변수로 자동 적용 가능.
코드 없이 단위 테스트? 예. Apidog 테스트 시나리오 기능으로 시각적 인터페이스로 단위 테스트를 구축/실행할 수 있습니다. 상태 코드, 응답 시간, 헤더 등 어설션 지정 후 CI 연동 가능.
지원 오디오 형식? WAV, MP3, PCM 형식 반환. format 필드로 지정. WAV가 기본값.
음성 복제 절차? 10~30초 참조 오디오와 스크립트를 POST /v1/references/add로 업로드. 이후 reference_id로 TTS 요청 시 음성 복제. 별도 모델 미세조정 필요 없음.
실시간 계수(RTF)? NVIDIA H200 기준 0.195 RTF. 1초 연산에 약 5초 오디오 생성. 첫 오디오까지 약 100ms.
Apidog에서 오디오 응답 테스트? 이진 오디오 응답시 자동 인라인 오디오 플레이어 제공. 파일 저장 없이 Apidog 내에서 바로 듣고, 헤더/어설션 검증 가능.
Top comments (0)