Cara Menggunakan Fish Audio S2 API: Panduan Lengkap dengan Apidog

Fish Audio S2 API adalah REST API text-to-speech tingkat produksi yang didukung oleh model 4 miliar parameter yang dilatih dengan 10 juta jam audio. Ini mendukung kloning suara, streaming, dan 50+ bahasa. Untuk menggunakan Fish Audio S2 API secara efisien termasuk mengirim permintaan, mengelola referensi, dan menjalankan unit test, Apidog adalah cara tercepat untuk menjelajahi, mendokumentasikan, dan memvalidasi setiap endpoint.

Pendahuluan

Suara yang dihasilkan AI telah melampaui ambang batas. Model TTS modern tidak lagi terdengar seperti robot; mereka berbisik, tertawa, dan mengubah nada di tengah kalimat. Fish Audio S2 API berada di garis depan perubahan ini: sebuah model 4B-parameter yang dilatih dengan lebih dari 10 juta jam audio multibahasa, mampu menghasilkan suara yang tidak dapat dibedakan dari rekaman manusia.

Baik Anda membangun alat otomatisasi podcast, asisten suara interaktif, atau pipeline dubbing real-time, mengintegrasikan Fish Audio S2 API ke dalam tumpukan Anda membutuhkan lebih dari sekadar satu permintaan POST. Anda perlu memahami autentikasi, manajemen audio referensi, perilaku streaming, dan yang paling penting bagaimana menulis unit test yang andal agar integrasi Anda tidak rusak secara diam-diam di produksi.

Apa Itu Fish Audio S2 API?

Fish Audio S2 API adalah antarmuka HTTP ke Fish Speech S2-Pro, sebuah sistem TTS open-source yang dibangun di sekitar arsitektur Dual-Autoregressive (Dual-AR). Model ini memisahkan generasi semantik (4B parameter, AR lambat sepanjang sumbu waktu) dari generasi codebook residual (400M parameter, AR cepat sepanjang sumbu kedalaman), memungkinkan sintesis berkualitas tinggi dengan faktor real-time 0.195 pada satu NVIDIA H200.

Kemampuan utama Fish Audio S2 API:

URL dasar Fish Audio S2 API setelah deployment lokal adalah http://127.0.0.1:8080. Semua endpoint berada di bawah namespace /v1/.

Memulai dengan Fish Audio S2 API dan Apidog

Prasyarat untuk Fish Audio S2 API

Sebelum melakukan panggilan Fish Audio S2 API pertama Anda, Anda memerlukan dua hal: server Fish Speech S2-Pro yang telah di-deploy dan klien API yang mampu menangani respons audio biner.

Mulai server 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

Flag --compile mengaktifkan optimasi torch.compile — ini memangkas latensi inferensi sekitar 10× tetapi menambah biaya pemanasan satu kali pada peluncuran pertama. Flag --half mengaktifkan FP16 untuk mengurangi penggunaan memori GPU.

Setelah server aktif, verifikasi dengan health check:

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

Menyiapkan Fish Audio S2 API di Apidog

Unduh Apidog secara gratis dan buat proyek HTTP baru. Tambahkan URL dasar http://127.0.0.1:8080 di bawah Environments. Kemudian atur header global:

Authorization: Bearer YOUR_API_KEY

Apidog menyimpan ini di tingkat lingkungan, sehingga setiap permintaan Fish Audio S2 API yang Anda kirim akan mewarisi token secara otomatis – tidak perlu menempelkan header secara manual per permintaan. Ini sangat berguna ketika Anda memiliki beberapa lingkungan Fish Audio S2 API (dev lokal, staging, produksi) untuk berpindah-pindah.

Melakukan Permintaan Fish Audio S2 API Pertama Anda di Apidog

Menguji Endpoint Text-to-Speech Fish Audio S2 API

Endpoint utama Fish Audio S2 API adalah POST /v1/tts. Di Apidog, buat permintaan baru dengan URL ini, atur metode ke POST, dan gunakan body JSON berikut:

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

Skema permintaan Fish Audio S2 API TTS lengkap:

Tekan Send di Apidog. Fish Audio S2 API mengembalikan byte audio mentah. Apidog secara otomatis mendeteksi respons audio/wav dan menampilkan pemutar audio inline — Anda dapat mendengarkan ucapan yang dihasilkan langsung di antarmuka, tanpa menulis sebaris kode klien pun.

Kloning Suara dengan Fish Audio S2 API

Mengunggah Audio Referensi ke Fish Audio S2 API melalui Apidog

Fish Audio S2 API mendukung kloning suara zero-shot melalui kolom references dalam permintaan TTS. Anda meneruskan klip audio yang dikodekan base64 beserta transkripnya, dan model mengkloning suara tersebut untuk output.

Pertama, unggah referensi bernama menggunakan POST /v1/references/add:

{
  "id": "my-voice-clone",
  "text": "This is the reference transcription matching the audio.",
  "audio": "<base64-encoded-wav-bytes>"
}

Di Apidog, gunakan tipe body Binary untuk mengunggah file audio secara langsung, atau beralih ke Form Data untuk meneruskan file dan kolom teks secara bersamaan. Fish Audio S2 API mengembalikan:

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

Sekarang referensikan dalam panggilan TTS Anda menggunakan reference_id:

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

Panel Reference Management Apidog (di bawah Collections) memungkinkan Anda menyimpan permintaan ini sebagai template yang dapat digunakan kembali, sehingga Anda dapat mengganti suara hanya dengan mengubah nilai reference_id — berguna saat menguji beberapa suara yang dikloning dengan skrip yang sama.

Cara Menguji Integrasi Fish Audio S2 API dengan Unit Test

Mengapa Unit Test Penting untuk Fish Audio S2 API

Integrasi Fish Audio S2 API memiliki beberapa mode kegagalan yang tidak terlihat tanpa unit test otomatis: ID referensi yang tidak lagi ada, nilai temperature di luar jangkauan, respons streaming yang dikonsumsi secara tidak benar, atau ketidakcocokan format audio. Unit test menangkap regresi ini sebelum mencapai pengguna.

Menulis Unit Test untuk Fish Audio S2 API dengan Python

Berikut adalah suite unit test Python yang mencakup alur Fish Audio S2 API inti menggunakan pytest dan 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:
    """Unit tests for Fish Audio S2 API endpoints."""

    def test_health_check(self):
        """Unit test: Fish Audio S2 API health endpoint returns 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):
        """Unit test: Fish Audio S2 API TTS returns binary audio."""
        payload = {
            "text": "Unit test: verifying Fish Audio S2 API TTS output.",
            "format": "wav",
            "seed": 42,  # Fixed seed for deterministic unit test output
        }
        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  # Minimum viable audio size

    def test_tts_invalid_temperature_raises_error(self):
        """Unit test: Fish Audio S2 API rejects out-of-range temperature."""
        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  # Validation error expected

    def test_reference_add_and_list(self):
        """Unit test: Fish Audio S2 API reference management endpoints."""
        # Add a reference
        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

        # Verify reference appears in list
        list_response = httpx.get(
            f"{BASE_URL}/v1/references/list", headers=HEADERS
        )
        assert "unit-test-voice" in list_response.json()["reference_ids"]

        # Cleanup: delete reference after unit test
        httpx.request(
            "DELETE",
            f"{BASE_URL}/v1/references/delete",
            json={"reference_id": "unit-test-voice"},
            headers=HEADERS,
        )

Jalankan suite unit test dengan:

pytest test_fish_audio_s2_api.py -v

Menjalankan Unit Test Fish Audio S2 API dengan Apidog

Selain unit test Python, Apidog memiliki fitur Test Scenarios (pengujian otomatis) bawaan yang menjalankan pemeriksaan Fish Audio S2 API yang sama tanpa lingkungan Python lokal. Di Apidog:

1. Buka koleksi Fish Audio S2 API Anda
2. Klik Test Scenarios → New Scenario
3. Tambahkan permintaan: health check → permintaan TTS → tambah referensi → daftar referensi
4. Di tab Assertions untuk permintaan TTS, tambahkan:

• Status respons = 200
• Header respons content-type berisi audio
• Waktu respons < 30000ms

1. Klik Run untuk menjalankan urutan unit test lengkap

Apidog menghasilkan laporan lulus/gagal untuk setiap pernyataan Fish Audio S2 API, dengan waktu respons dan tampilan diff. Anda dapat mengekspor laporan ini atau menjadwalkannya untuk berjalan pada pemicu CI — menjadikan Apidog sebagai unit test runner untuk Fish Audio S2 API Anda tanpa menulis boilerplate kerangka kerja pengujian apa pun.

Fitur Lanjutan Fish Audio S2 API

Streaming Audio dari Fish Audio S2 API

Untuk aplikasi pemutaran real-time, Fish Audio S2 API mendukung streaming chunked. Atur "streaming": true di body permintaan Anda:

import httpx

with httpx.stream(
    "POST",
    "http://127.0.0.1:8080/v1/tts",
    json={
        "text": "Streaming audio from the Fish Audio S2 API in real time.",
        "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 mulai mengembalikan byte audio sebelum sintesis penuh selesai — waktu ke audio pertama sekitar 100ms. Ini membuatnya layak untuk aplikasi suara langsung di mana pengguna mengharapkan umpan balik instan.

Kontrol Emosi Inline melalui Fish Audio S2 API

Fish Audio S2 API meneruskan tag emosi bahasa alami langsung di kolom text:

{
  "text": "[whispers] The secret is hidden here. [super happy] I found it!",
  "format": "wav"
}

Tidak diperlukan parameter khusus — model menafsirkan tag dalam kurung sebagai instruksi prosodi. Contoh tag yang valid dari sumber Fish Speech: [laugh], [cough], [pitch up], [professional broadcast tone], [whisper in small voice].

Kesimpulan

Fish Audio S2 API menghadirkan mesin TTS tingkat produksi yang benar-benar berkualitas melalui antarmuka REST yang bersih. Dari sintesis dasar hingga kloning suara zero-shot dan streaming real-time, enam endpoint mencakup seluruh rentang alur kerja generasi suara yang dibutuhkan pengembang. Kunci untuk integrasi yang andal adalah: mengatur parameter sampling yang tepat (temperature, top_p, repetition_penalty), mengelola siklus hidup audio referensi dengan benar, dan memelihara suite unit test yang memvalidasi kontrak setiap endpoint.

Apidog sangat mempersingkat kurva pembelajaran. Gunakan untuk mengirim permintaan Fish Audio S2 API pertama Anda dalam waktu kurang dari dua menit, dengarkan respons audio biner secara inline, hasilkan kode klien yang dapat disalin-tempel, dan jalankan unit test otomatis terhadap setiap endpoint Fish Audio S2 API tanpa mengonfigurasi kerangka kerja pengujian. Saat Anda siap berbagi spesifikasi API dengan tim Anda atau mendokumentasikan integrasi Fish Audio S2 API untuk pemangku kepentingan, dokumentasi yang dihasilkan otomatis oleh Apidog menjaga semuanya tetap sinkron.

Unduh Apidog secara gratis dan impor koleksi Fish Audio S2 API untuk mulai menguji hari ini.

FAQ

Apa itu Fish Audio S2 API? Fish Audio S2 API adalah antarmuka REST ke Fish Speech S2-Pro, sebuah model text-to-speech 4B-parameter yang dilatih dengan 10 juta jam audio. Ini mendukung kloning suara, streaming, kontrol emosi, dan 50+ bahasa melalui endpoint HTTP di bawah /v1/.

Bagaimana cara mengautentikasi dengan Fish Audio S2 API? Kirim token Bearer di setiap header permintaan: Authorization: Bearer YOUR_API_KEY. Kunci API dikonfigurasi saat server dimulai melalui flag --api-key. Apidog memungkinkan Anda menyimpan token ini di tingkat lingkungan sehingga secara otomatis berlaku untuk semua permintaan Fish Audio S2 API.

Dapatkah saya menguji integrasi Fish Audio S2 API tanpa menulis kode? Ya. Fitur Test Scenarios Apidog memungkinkan Anda membangun dan menjalankan unit test terhadap endpoint Fish Audio S2 API apa pun melalui antarmuka visual. Anda mendefinisikan pernyataan (kode status, waktu respons, nilai header) dan Apidog menjalankannya sesuai permintaan atau pada jadwal CI — tidak diperlukan pengaturan kerangka kerja pengujian.

Format audio apa yang didukung oleh Fish Audio S2 API? Fish Audio S2 API mengembalikan audio dalam format WAV, MP3, atau PCM. Tentukan format dengan kolom "format" di body permintaan TTS Anda. WAV adalah default.

Bagaimana cara kerja kloning suara di Fish Audio S2 API? Unggah klip audio referensi 10–30 detik dan transkripnya ke POST /v1/references/add. Kemudian berikan ID referensi ke permintaan TTS apa pun melalui "reference_id". Fish Audio S2 API mengkloning suara tersebut tanpa fine-tuning atau pelatihan model tambahan.

Berapa faktor real-time Fish Audio S2 API? Pada satu NVIDIA H200, Fish Audio S2 API mencapai RTF (faktor real-time) 0.195 dengan streaming diaktifkan, artinya ia menghasilkan sekitar 5 detik audio per detik komputasi. Waktu ke audio pertama sekitar 100ms.

Bagaimana cara menguji respons Fish Audio S2 API di Apidog? Ketika Fish Audio S2 API mengembalikan audio biner, Apidog secara otomatis menampilkan pemutar audio inline. Anda tidak perlu menyimpan file secara lokal untuk memverifikasi output — Anda dapat mendengarkan, memeriksa header respons, dan menambahkan pernyataan semuanya dari panel permintaan Apidog yang sama.