Fish Audio S2 API 사용법: Apidog 활용 완벽 가이드

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란 무엇인가요?

Fish Audio S2 API는 이중-자기회귀(Dual-AR) 아키텍처를 기반으로 구축된 오픈 소스 TTS 시스템인 Fish Speech S2-Pro의 HTTP 인터페이스입니다. 이 모델은 의미론적 생성(4B 매개변수, 시간 축을 따라 느린 AR)과 잔여 코드북 생성(400M 매개변수, 깊이 축을 따라 빠른 AR)을 분리하여 단일 NVIDIA H200에서 0.195의 실시간 계수(real-time factor)로 고품질 합성을 가능하게 합니다.

주요 Fish Audio S2 API 기능:

로컬 배포 후 Fish Audio S2 API 기본 URL은 http://127.0.0.1:8080입니다. 모든 엔드포인트는 /v1/ 네임스페이스 아래에 있습니다.

Fish Audio S2 API 및 Apidog 시작하기

Fish Audio S2 API 필수 조건

첫 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 최적화를 활성화하여 추론 지연 시간을 약 10배 단축하지만, 첫 실행 시 한 번의 워밍업 비용이 발생합니다. --half 플래그는 GPU 메모리 사용량을 줄이기 위해 FP16을 활성화합니다.

서버가 시작되면 상태 확인으로 확인합니다:

curl http://127.0.0.1:8080/v1/health
# {"status":"ok"}

Apidog에서 Fish Audio S2 API 설정

Apidog를 무료로 다운로드하고 새 HTTP 프로젝트를 만드세요. 환경(Environments) 아래에 기본 URL http://127.0.0.1:8080을 추가합니다. 그런 다음 전역 헤더를 설정합니다:

Authorization: Bearer YOUR_API_KEY

Apidog는 이를 환경 수준에 저장하므로, 전송하는 모든 Fish Audio S2 API 요청은 토큰을 자동으로 상속받습니다. 요청마다 헤더를 수동으로 붙여넣을 필요가 없습니다. 이는 여러 Fish Audio S2 API 환경(로컬 개발, 스테이징, 프로덕션)을 전환해야 할 때 특히 유용합니다.

Apidog에서 첫 Fish Audio S2 API 요청하기

Fish Audio S2 API 텍스트 음성 변환 엔드포인트 테스트

주요 Fish Audio S2 API 엔드포인트는 POST /v1/tts입니다. Apidog에서 이 URL로 새 요청을 생성하고, 메서드를 POST로 설정한 다음 다음 JSON 본문을 사용합니다:

{
  "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
}

전체 Fish Audio S2 API TTS 요청 스키마:

Apidog에서 보내기(Send)를 누르세요. Fish Audio S2 API는 원시 오디오 바이트를 반환합니다. Apidog는 audio/wav 응답을 자동으로 감지하고 인라인 오디오 플레이어를 렌더링합니다. 클라이언트 코드를 한 줄도 작성하지 않고도 인터페이스에서 직접 생성된 음성을 들을 수 있습니다.

Fish Audio S2 API를 이용한 음성 복제

Apidog를 통해 Fish Audio S2 API에 참조 오디오 업로드

Fish Audio S2 API는 TTS 요청의 references 필드를 통해 제로샷 음성 복제(zero-shot voice cloning)를 지원합니다. 스크립트와 함께 base64로 인코딩된 오디오 클립을 전달하면 모델이 해당 음성을 복제하여 출력합니다.

먼저, 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)로 전환하여 파일과 텍스트 필드를 함께 전달합니다. Fish Audio S2 API는 다음을 반환합니다:

{
  "success": true,
  "message": "Reference added successfully",
  "reference_id": "my-voice-clone"
}

이제 reference_id를 사용하여 TTS 호출에서 이를 참조합니다:

{
  "text": "This sentence will be spoken in the cloned voice.",
  "reference_id": "my-voice-clone",
  "format": "mp3"
}

Apidog의 참조 관리(Reference Management) 패널(컬렉션 아래)을 사용하면 이 요청을 재사용 가능한 템플릿으로 저장할 수 있으므로, 동일한 스크립트에 대해 여러 복제된 음성을 테스트할 때 reference_id 값만 변경하여 음성을 교체할 수 있습니다.

Fish Audio S2 API 통합 단위 테스트 방법

Fish Audio S2 API에 단위 테스트가 중요한 이유

Fish Audio S2 API 통합에는 자동화된 단위 테스트 없이는 보이지 않는 여러 가지 실패 모드가 있습니다: 더 이상 존재하지 않는 참조 ID, 범위를 벗어난 temperature 값, 잘못 소비된 스트리밍 응답 또는 오디오 형식 불일치 등입니다. 단위 테스트는 이러한 회귀를 사용자에게 도달하기 전에 잡아냅니다.

Python으로 Fish Audio S2 API 단위 테스트 작성

다음은 pytest 및 httpx를 사용하여 핵심 Fish Audio S2 API 흐름을 다루는 Python 단위 테스트 스위트입니다:

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):
        """단위 테스트: Fish Audio S2 API 상태 엔드포인트가 'ok'를 반환합니다."""
        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):
        """단위 테스트: Fish Audio S2 API 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):
        """단위 테스트: Fish Audio S2 API가 범위 밖 온도를 거부합니다."""
        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):
        """단위 테스트: Fish Audio S2 API 참조 관리 엔드포인트."""
        # 참조 추가
        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로 Fish Audio S2 API 단위 테스트 실행

Python 단위 테스트 외에도 Apidog는 로컬 Python 환경 없이도 동일한 Fish Audio S2 API 검사를 실행하는 내장 테스트 시나리오(Test Scenarios)(자동화된 테스트) 기능을 제공합니다. Apidog에서 다음을 수행하세요:

1. Fish Audio S2 API 컬렉션을 엽니다.
2. 테스트 시나리오(Test Scenarios) → 새 시나리오(New Scenario)를 클릭합니다.
3. 요청 추가: 상태 확인 → TTS 요청 → 참조 추가 → 참조 목록
4. TTS 요청의 어설션(Assertions) 탭에서 다음을 추가합니다:

• 응답 상태 = 200
• 응답 헤더 content-type에 audio 포함
• 응답 시간 < 30000ms

1. 실행(Run)을 클릭하여 전체 단위 테스트 시퀀스를 실행합니다.

Apidog는 각 Fish Audio S2 API 어설션에 대해 응답 시간 및 차이(diff) 보기를 포함한 합격/불합격 보고서를 생성합니다. 이 보고서를 내보내거나 CI 트리거에서 실행하도록 예약할 수 있습니다. Apidog는 테스트 프레임워크 상용구(boilerplate)를 작성할 필요 없이 Fish Audio S2 API의 단위 테스트 러너 역할을 합니다.

Fish Audio S2 API 고급 기능

Fish Audio S2 API에서 오디오 스트리밍

실시간 재생 애플리케이션의 경우 Fish Audio S2 API는 청크 스트리밍을 지원합니다. 요청 본문에 "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)

Fish Audio S2 API는 전체 합성이 완료되기 전에 오디오 바이트 반환을 시작합니다. 첫 오디오까지의 시간은 약 100ms입니다. 이는 사용자가 즉각적인 피드백을 기대하는 라이브 음성 애플리케이션에 적합합니다.

Fish Audio S2 API를 통한 인라인 감정 제어

Fish Audio S2 API는 text 필드에 자연어 감정 태그를 직접 전달합니다:

{
  "text": "[whispers] 비밀은 여기에 숨겨져 있습니다. [super happy] 찾았다!",
  "format": "wav"
}

특별한 매개변수가 필요하지 않습니다. 모델은 대괄호 안의 태그를 운율 지시로 해석합니다. Fish Speech 소스의 유효한 태그 예시: [laugh](웃음), [cough](기침), [pitch up](음 높이기), [professional broadcast tone](전문적인 방송 톤), [whisper in small voice](작은 목소리로 속삭임).

결론

Fish Audio S2 API는 깔끔한 REST 인터페이스를 통해 진정한 프로덕션 등급의 TTS 엔진을 제공합니다. 기본적인 합성부터 제로샷 음성 복제 및 실시간 스트리밍에 이르기까지 6개의 엔드포인트는 개발자에게 필요한 전체 음성 생성 워크플로우를 포괄합니다. 안정적인 통합의 핵심은 올바른 샘플링 매개변수(temperature, top_p, repetition_penalty) 설정, 참조 오디오 수명 주기 올바른 관리, 그리고 각 엔드포인트의 계약을 검증하는 단위 테스트 스위트 유지입니다.

Apidog는 학습 곡선을 극적으로 단축합니다. Apidog를 사용하여 2분 이내에 첫 Fish Audio S2 API 요청을 보내고, 인라인으로 이진 오디오 응답을 듣고, 복사-붙여넣기 클라이언트 코드를 생성하고, 테스트 프레임워크를 구성할 필요 없이 모든 Fish Audio S2 API 엔드포인트에 대해 자동화된 단위 테스트를 실행하세요. 팀과 API 사양을 공유하거나 이해 관계자를 위해 Fish Audio S2 API 통합을 문서화할 준비가 되면 Apidog의 자동 생성 문서가 모든 것을 동기화 상태로 유지합니다.

Apidog를 무료로 다운로드하고 Fish Audio S2 API 컬렉션을 가져와 지금 테스트를 시작하세요.

자주 묻는 질문

Fish Audio S2 API란 무엇인가요? Fish Audio S2 API는 1천만 시간의 오디오로 학습된 40억 개의 매개변수 텍스트 음성 변환 모델인 Fish Speech S2-Pro의 REST 인터페이스입니다. /v1/ 아래의 HTTP 엔드포인트를 통해 음성 복제, 스트리밍, 감정 제어, 50개 이상의 언어를 지원합니다.

Fish Audio S2 API로 어떻게 인증하나요? 모든 요청 헤더에 Bearer 토큰을 전송합니다: Authorization: Bearer YOUR_API_KEY. API 키는 --api-key 플래그를 통해 서버 시작 시 구성됩니다. Apidog를 사용하면 이 토큰을 환경 수준에 저장하여 모든 Fish Audio S2 API 요청에 자동으로 적용되도록 할 수 있습니다.

코드 작성 없이 Fish Audio S2 API 통합을 단위 테스트할 수 있나요? 네, 가능합니다. Apidog의 테스트 시나리오(Test Scenarios) 기능을 사용하면 시각적 인터페이스를 통해 모든 Fish Audio S2 API 엔드포인트에 대한 단위 테스트를 구축하고 실행할 수 있습니다. 어설션(상태 코드, 응답 시간, 헤더 값)을 정의하면 Apidog가 필요에 따라 또는 CI 일정에 따라 실행합니다. 테스트 프레임워크 설정은 필요하지 않습니다.

Fish Audio S2 API는 어떤 오디오 형식을 지원하나요? Fish Audio S2 API는 WAV, MP3 또는 PCM 형식의 오디오를 반환합니다. TTS 요청 본문의 "format" 필드에 형식을 지정합니다. WAV가 기본값입니다.

Fish Audio S2 API에서 음성 복제는 어떻게 작동하나요? 10~30초 길이의 참조 오디오 클립과 해당 스크립트를 POST /v1/references/add에 업로드합니다. 그런 다음 "reference_id"를 통해 모든 TTS 요청에 참조 ID를 전달합니다. Fish Audio S2 API는 미세 조정이나 추가 모델 학습 없이 해당 음성을 복제합니다.

Fish Audio S2 API의 실시간 계수는 얼마인가요? 단일 NVIDIA H200에서 Fish Audio S2 API는 스트리밍이 활성화된 상태에서 0.195의 RTF(실시간 계수)를 달성합니다. 이는 1초의 컴퓨팅으로 약 5초의 오디오를 생성한다는 의미입니다. 첫 오디오까지의 시간은 약 100ms입니다.

Apidog에서 Fish Audio S2 API 응답을 어떻게 테스트하나요? Fish Audio S2 API가 이진 오디오를 반환하면 Apidog는 자동으로 인라인 오디오 플레이어를 렌더링합니다. 출력을 확인하기 위해 파일을 로컬에 저장할 필요 없이 동일한 Apidog 요청 패널에서 듣고, 응답 헤더를 확인하고, 어설션을 추가할 수 있습니다.