Hướng Dẫn Sử Dụng Fish Audio S2 API Chi Tiết với Apidog

Fish Audio S2 API là một REST API chuyển văn bản thành giọng nói cấp độ sản xuất, được cung cấp bởi một mô hình 4 tỷ tham số được huấn luyện trên 10 triệu giờ âm thanh. Nó hỗ trợ nhân bản giọng nói, truyền phát trực tuyến và hơn 50 ngôn ngữ. Để sử dụng Fish Audio S2 API một cách hiệu quả bao gồm gửi yêu cầu, quản lý tài liệu tham khảo và chạy kiểm thử đơn vị, Apidog là cách nhanh nhất để khám phá, lập tài liệu và xác thực mọi điểm cuối.

Giới thiệu

Giọng nói do AI tạo ra đã vượt qua một ngưỡng giới hạn. Các mô hình TTS hiện đại không còn nghe như robot nữa; chúng có thể thì thầm, cười và thay đổi tông giọng giữa câu. Fish Audio S2 API đứng ở tuyến đầu của sự thay đổi này: một mô hình 4 tỷ tham số được huấn luyện trên hơn 10 triệu giờ âm thanh đa ngôn ngữ, có khả năng tạo ra giọng nói không thể phân biệt được với bản ghi âm của con người.

Cho dù bạn đang xây dựng một công cụ tự động hóa podcast, một trợ lý giọng nói tương tác hay một hệ thống lồng tiếng theo thời gian thực, việc tích hợp Fish Audio S2 API vào hệ thống của bạn đòi hỏi nhiều hơn là chỉ một yêu cầu POST đơn giản. Bạn cần hiểu về xác thực, quản lý âm thanh tham chiếu, hành vi truyền phát trực tuyến, và quan trọng nhất là cách viết các kiểm thử đơn vị đáng tin cậy để tích hợp của bạn không bị lỗi thầm lặng trong quá trình sản xuất.

Fish Audio S2 API là gì?

Fish Audio S2 API là giao diện HTTP cho Fish Speech S2-Pro, một hệ thống TTS mã nguồn mở được xây dựng dựa trên kiến trúc Tự hồi quy kép (Dual-Autoregressive - Dual-AR). Mô hình này tách biệt việc tạo ngữ nghĩa (4 tỷ tham số, AR chậm theo trục thời gian) khỏi việc tạo sách mã dư (400 triệu tham số, AR nhanh theo trục độ sâu), cho phép tổng hợp chất lượng cao với hệ số thời gian thực là 0.195 trên một GPU NVIDIA H200 duy nhất.

Các khả năng chính của Fish Audio S2 API:

URL cơ sở của Fish Audio S2 API sau khi triển khai cục bộ là http://127.0.0.1:8080. Tất cả các điểm cuối nằm dưới không gian tên /v1/.

Bắt đầu với Fish Audio S2 API và Apidog

Điều kiện tiên quyết cho Fish Audio S2 API

Trước khi thực hiện cuộc gọi Fish Audio S2 API đầu tiên của bạn, bạn cần có hai thứ đang chạy: một máy chủ Fish Speech S2-Pro đã triển khai và một máy khách API có khả năng xử lý các phản hồi âm thanh nhị phân.

Khởi động máy chủ 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

Cờ --compile kích hoạt tối ưu hóa torch.compile – điều này giảm độ trễ suy luận khoảng 10 lần nhưng thêm chi phí khởi động một lần vào lần chạy đầu tiên. Cờ --half cho phép FP16 để giảm mức sử dụng bộ nhớ GPU.

Khi máy chủ đã khởi động, hãy xác minh nó bằng kiểm tra tình trạng:

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

Thiết lập Fish Audio S2 API trong Apidog

Tải xuống Apidog miễn phí và tạo một dự án HTTP mới. Thêm URL cơ sở http://127.0.0.1:8080 trong mục Environments. Sau đó, đặt một tiêu đề chung:

Authorization: Bearer YOUR_API_KEY

Apidog lưu trữ điều này ở cấp độ môi trường, vì vậy mọi yêu cầu Fish Audio S2 API bạn gửi sẽ tự động kế thừa mã thông báo – không cần dán tiêu đề thủ công cho mỗi yêu cầu. Điều này đặc biệt hữu ích khi bạn có nhiều môi trường Fish Audio S2 API (phát triển cục bộ, dàn dựng, sản xuất) để chuyển đổi giữa chúng.

Thực hiện yêu cầu Fish Audio S2 API đầu tiên của bạn trong Apidog

Kiểm tra điểm cuối Chuyển văn bản thành giọng nói của Fish Audio S2 API

Điểm cuối Fish Audio S2 API chính là POST /v1/tts. Trong Apidog, tạo một yêu cầu mới với URL này, đặt phương thức là POST và sử dụng nội dung JSON sau:

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

Schema yêu cầu TTS đầy đủ của Fish Audio S2 API:

Nhấn Gửi trong Apidog. Fish Audio S2 API trả về các byte âm thanh thô. Apidog tự động phát hiện phản hồi audio/wav và hiển thị trình phát âm thanh nội tuyến – bạn có thể nghe trực tiếp giọng nói được tạo trong giao diện, mà không cần viết một dòng mã khách nào.

Nhân bản giọng nói với Fish Audio S2 API

Tải lên âm thanh tham chiếu lên Fish Audio S2 API qua Apidog

Fish Audio S2 API hỗ trợ nhân bản giọng nói zero-shot thông qua trường references trong yêu cầu TTS. Bạn truyền một đoạn âm thanh được mã hóa base64 cùng với bản ghi của nó, và mô hình sẽ nhân bản giọng nói đó cho đầu ra.

Đầu tiên, tải lên một tham chiếu có tên bằng cách sử dụng POST /v1/references/add:

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

Trong Apidog, sử dụng loại nội dung Binary để tải trực tiếp tệp âm thanh, hoặc chuyển sang Form Data để truyền tệp và các trường văn bản cùng nhau. Fish Audio S2 API trả về:

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

Bây giờ hãy tham chiếu nó trong các cuộc gọi TTS của bạn bằng cách sử dụng reference_id:

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

Bảng điều khiển Quản lý tham chiếu của Apidog (trong Collections) cho phép bạn lưu yêu cầu này dưới dạng một mẫu có thể tái sử dụng, để bạn có thể thay đổi giọng nói bằng cách đơn giản thay đổi giá trị reference_id – điều này hữu ích khi kiểm tra nhiều giọng nói được nhân bản với cùng một kịch bản.

Cách kiểm thử đơn vị tích hợp Fish Audio S2 API

Tại sao kiểm thử đơn vị quan trọng đối với Fish Audio S2 API

Một tích hợp Fish Audio S2 API có một số chế độ lỗi không thể nhìn thấy nếu không có kiểm thử đơn vị tự động: một ID tham chiếu không còn tồn tại, một giá trị temperature ngoài phạm vi, một phản hồi truyền phát được sử dụng không đúng cách, hoặc một sự không khớp định dạng âm thanh. Kiểm thử đơn vị phát hiện những lỗi này trước khi chúng đến tay người dùng.

Viết kiểm thử đơn vị cho Fish Audio S2 API bằng Python

Dưới đây là một bộ kiểm thử đơn vị Python bao gồm các luồng Fish Audio S2 API cốt lõi sử dụng pytest và 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,
        )

Chạy bộ kiểm thử đơn vị với:

pytest test_fish_audio_s2_api.py -v

Chạy kiểm thử đơn vị Fish Audio S2 API với Apidog

Ngoài các kiểm thử đơn vị Python, Apidog có tính năng Kịch bản kiểm thử (kiểm thử tự động) tích hợp sẵn, chạy các kiểm tra Fish Audio S2 API tương tự mà không cần môi trường Python cục bộ. Trong Apidog:

1. Mở bộ sưu tập Fish Audio S2 API của bạn
2. Nhấp vào Kịch bản kiểm thử → Kịch bản mới
3. Thêm các yêu cầu: kiểm tra tình trạng → yêu cầu TTS → thêm tham chiếu → liệt kê tham chiếu
4. Trong tab Xác nhận cho yêu cầu TTS, thêm:

• Trạng thái phản hồi = 200
• Tiêu đề phản hồi content-type chứa audio
• Thời gian phản hồi < 30000ms

1. Nhấp Chạy để thực hiện toàn bộ chuỗi kiểm thử đơn vị

Apidog tạo báo cáo đạt/không đạt cho mỗi xác nhận Fish Audio S2 API, với thời gian phản hồi và chế độ xem khác biệt. Bạn có thể xuất báo cáo này hoặc lên lịch chạy nó theo trình kích hoạt CI – biến Apidog thành công cụ chạy kiểm thử đơn vị cho Fish Audio S2 API của bạn mà không cần viết bất kỳ đoạn mã khung kiểm thử nào.

Các tính năng nâng cao của Fish Audio S2 API

Truyền phát âm thanh từ Fish Audio S2 API

Đối với các ứng dụng phát lại theo thời gian thực, Fish Audio S2 API hỗ trợ truyền phát theo từng khối. Đặt "streaming": true trong nội dung yêu cầu của bạn:

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 bắt đầu trả về các byte âm thanh trước khi quá trình tổng hợp hoàn tất hoàn toàn – thời gian cho âm thanh đầu tiên khoảng 100ms. Điều này làm cho nó khả thi cho các ứng dụng giọng nói trực tiếp nơi người dùng mong đợi phản hồi tức thì.

Điều khiển cảm xúc nội tuyến qua Fish Audio S2 API

Fish Audio S2 API truyền các thẻ cảm xúc bằng ngôn ngữ tự nhiên trực tiếp trong trường text:

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

Không cần tham số đặc biệt – mô hình diễn giải các thẻ trong dấu ngoặc vuông làm hướng dẫn về ngữ điệu. Ví dụ thẻ hợp lệ từ nguồn Fish Speech: [laugh], [cough], [pitch up], [professional broadcast tone], [whisper in small voice].

Kết luận

Fish Audio S2 API cung cấp một công cụ TTS thực sự ở cấp độ sản xuất thông qua một giao diện REST rõ ràng. Từ tổng hợp cơ bản đến nhân bản giọng nói zero-shot và truyền phát trực tuyến theo thời gian thực, sáu điểm cuối bao gồm toàn bộ các quy trình làm việc tạo giọng nói mà nhà phát triển cần. Các yếu tố quan trọng để tích hợp đáng tin cậy là: đặt đúng các tham số lấy mẫu (temperature, top_p, repetition_penalty), quản lý đúng vòng đời âm thanh tham chiếu và duy trì một bộ kiểm thử đơn vị xác thực hợp đồng của mỗi điểm cuối.

Apidog rút ngắn đáng kể đường cong học tập. Sử dụng nó để gửi yêu cầu Fish Audio S2 API đầu tiên của bạn trong vòng chưa đầy hai phút, nghe các phản hồi âm thanh nhị phân nội tuyến, tạo mã máy khách có thể sao chép-dán và chạy kiểm thử đơn vị tự động đối với mọi điểm cuối của Fish Audio S2 API mà không cần cấu hình khung kiểm thử. Khi bạn sẵn sàng chia sẻ thông số kỹ thuật API với nhóm của mình hoặc lập tài liệu tích hợp Fish Audio S2 API cho các bên liên quan, tài liệu được tự động tạo của Apidog sẽ giữ mọi thứ đồng bộ.

Tải xuống Apidog miễn phí và nhập bộ sưu tập Fish Audio S2 API để bắt đầu kiểm thử ngay hôm nay.

Câu hỏi thường gặp

Fish Audio S2 API là gì? Fish Audio S2 API là giao diện REST của Fish Speech S2-Pro, một mô hình chuyển văn bản thành giọng nói 4 tỷ tham số được huấn luyện trên 10 triệu giờ âm thanh. Nó hỗ trợ nhân bản giọng nói, truyền phát trực tuyến, điều khiển cảm xúc và hơn 50 ngôn ngữ thông qua các điểm cuối HTTP dưới /v1/.

Làm cách nào để xác thực với Fish Audio S2 API? Gửi một token Bearer trong mỗi tiêu đề yêu cầu: Authorization: Bearer YOUR_API_KEY. Khóa API được cấu hình khi khởi động máy chủ thông qua cờ --api-key. Apidog cho phép bạn lưu trữ token này ở cấp độ môi trường để nó tự động áp dụng cho tất cả các yêu cầu Fish Audio S2 API.

Tôi có thể kiểm thử đơn vị tích hợp Fish Audio S2 API mà không cần viết mã không? Có. Tính năng Test Scenarios của Apidog cho phép bạn xây dựng và chạy kiểm thử đơn vị đối với bất kỳ điểm cuối Fish Audio S2 API nào thông qua giao diện trực quan. Bạn xác định các xác nhận (mã trạng thái, thời gian phản hồi, giá trị tiêu đề) và Apidog thực hiện chúng theo yêu cầu hoặc theo lịch trình CI – không yêu cầu thiết lập khung kiểm thử.

Fish Audio S2 API hỗ trợ các định dạng âm thanh nào? Fish Audio S2 API trả về âm thanh ở định dạng WAV, MP3 hoặc PCM. Chỉ định định dạng bằng trường "format" trong nội dung yêu cầu TTS của bạn. WAV là định dạng mặc định.

Làm thế nào để nhân bản giọng nói hoạt động trong Fish Audio S2 API? Tải lên một đoạn âm thanh tham chiếu dài 10–30 giây và bản ghi của nó tới POST /v1/references/add. Sau đó, truyền ID tham chiếu vào bất kỳ yêu cầu TTS nào qua "reference_id". Fish Audio S2 API sẽ nhân bản giọng nói đó mà không cần bất kỳ tinh chỉnh hoặc huấn luyện mô hình bổ sung nào.

Hệ số thời gian thực của Fish Audio S2 API là bao nhiêu? Trên một NVIDIA H200 duy nhất, Fish Audio S2 API đạt được RTF (hệ số thời gian thực) là 0.195 khi bật tính năng truyền phát trực tuyến, có nghĩa là nó tạo ra khoảng 5 giây âm thanh mỗi giây tính toán. Thời gian cho âm thanh đầu tiên xấp xỉ 100ms.

Làm cách nào để kiểm tra phản hồi Fish Audio S2 API trong Apidog? Khi Fish Audio S2 API trả về âm thanh nhị phân, Apidog tự động hiển thị trình phát âm thanh nội tuyến. Bạn không cần phải lưu tệp cục bộ để xác minh đầu ra – bạn có thể nghe, kiểm tra tiêu đề phản hồi và thêm các xác nhận, tất cả đều từ cùng một bảng điều khiển yêu cầu của Apidog.