Como Usar a API Fish Audio S2: Guia Completo com Apidog

A API Fish Audio S2 é uma API REST de texto para fala de nível de produção, alimentada por um modelo de 4 bilhões de parâmetros treinado em 10 milhões de horas de áudio. Ela suporta clonagem de voz, streaming e mais de 50 idiomas. Para usar a API Fish Audio S2 de forma eficiente, incluindo o envio de solicitações, o gerenciamento de referências e a execução de testes de unidade, o Apidog é a maneira mais rápida de explorar, documentar e validar cada endpoint.

Introdução

A voz gerada por IA ultrapassou um limite. Modelos TTS modernos não soam mais como robôs; eles sussurram, riem e mudam o tom no meio da frase. A API Fish Audio S2 está na vanguarda dessa mudança: um modelo de 4 bilhões de parâmetros treinado em mais de 10 milhões de horas de áudio multilíngue, capaz de produzir fala indistinguível de uma gravação humana.

Seja você construindo uma ferramenta de automação de podcast, um assistente de voz interativo ou um pipeline de dublagem em tempo real, integrar a API Fish Audio S2 em sua stack requer mais do que apenas uma única requisição POST. Você precisa entender autenticação, gerenciamento de áudio de referência, comportamento de streaming e, criticamente, como escrever testes de unidade confiáveis para que sua integração não falhe silenciosamente em produção.

O Que É a API Fish Audio S2?

A API Fish Audio S2 é a interface HTTP para o Fish Speech S2-Pro, um sistema TTS de código aberto construído em torno de uma arquitetura Dual-Autoregressive (Dual-AR). O modelo separa a geração semântica (4 bilhões de parâmetros, AR lento ao longo do eixo do tempo) da geração de codebook residual (400 milhões de parâmetros, AR rápido ao longo do eixo de profundidade), permitindo síntese de alta qualidade com um fator em tempo real de 0,195 em uma única NVIDIA H200.

Principais recursos da API Fish Audio S2:

A URL base da API Fish Audio S2 após a implantação local é http://127.0.0.1:8080. Todos os endpoints estão sob o namespace /v1/.

Primeiros Passos com a API Fish Audio S2 e Apidog

Pré-requisitos para a API Fish Audio S2

Antes de fazer sua primeira chamada à API Fish Audio S2, você precisa de duas coisas funcionando: um servidor Fish Speech S2-Pro implantado e um cliente de API capaz de lidar com respostas de áudio binário.

Inicie o servidor da API Fish Audio S2:

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

A flag --compile ativa a otimização torch.compile – isso reduz a latência de inferência em aproximadamente 10x, mas adiciona um custo único de aquecimento no primeiro lançamento. A flag --half habilita FP16 para menor uso de memória da GPU.

Assim que o servidor estiver ativo, verifique-o com um health check:

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

Configurando a API Fish Audio S2 no Apidog

Baixe o Apidog gratuitamente e crie um novo projeto HTTP. Adicione a URL base http://127.0.0.1:8080 em Environments. Em seguida, defina um cabeçalho global:

Authorization: Bearer YOUR_API_KEY

O Apidog armazena isso no nível do ambiente, então cada requisição da API Fish Audio S2 que você enviar herdará o token automaticamente – sem necessidade de colar o cabeçalho manualmente por requisição. Isso é especialmente útil quando você tem múltiplos ambientes da API Fish Audio S2 (desenvolvimento local, staging, produção) para alternar.

Fazendo Sua Primeira Requisição à API Fish Audio S2 no Apidog

Testando o Endpoint de Text-to-Speech da API Fish Audio S2

O endpoint principal da API Fish Audio S2 é POST /v1/tts. No Apidog, crie uma nova requisição com esta URL, defina o método como POST e use o seguinte corpo 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
}

Schema completo da requisição TTS da API Fish Audio S2:

Clique em Enviar no Apidog. A API Fish Audio S2 retorna bytes de áudio brutos. O Apidog detecta automaticamente a resposta audio/wav e renderiza um reprodutor de áudio inline – você pode ouvir a fala gerada diretamente na interface, sem escrever uma única linha de código cliente.

Clonagem de Voz com a API Fish Audio S2

Carregando um Áudio de Referência para a API Fish Audio S2 via Apidog

A API Fish Audio S2 suporta clonagem de voz zero-shot através do campo references na requisição TTS. Você passa um clipe de áudio codificado em base64 junto com sua transcrição, e o modelo clona essa voz para a saída.

Primeiro, carregue uma referência nomeada usando POST /v1/references/add:

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

No Apidog, use o tipo de corpo Binary para carregar o arquivo de áudio diretamente, ou mude para Form Data para passar o arquivo e os campos de texto juntos. A API Fish Audio S2 retorna:

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

Agora, referencie-o em suas chamadas TTS usando reference_id:

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

O painel de Gerenciamento de Referência do Apidog (em Coleções) permite que você salve esta requisição como um modelo reutilizável, para que você possa trocar vozes simplesmente alterando o valor de reference_id – útil ao testar múltiplas vozes clonadas com o mesmo script.

Como Testar Unidades de Integrações da API Fish Audio S2

Por Que Testes de Unidade São Importantes para a API Fish Audio S2

Uma integração da API Fish Audio S2 possui vários modos de falha que são invisíveis sem testes de unidade automatizados: um ID de referência que não existe mais, um valor de temperature fora do intervalo, uma resposta de streaming consumida incorretamente ou uma incompatibilidade de formato de áudio. Testes de unidade capturam essas regressões antes que cheguem aos usuários.

Escrevendo Testes de Unidade para a API Fish Audio S2 com Python

Aqui está um conjunto de testes de unidade Python cobrindo os fluxos centrais da API Fish Audio S2 usando pytest e 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,
        )

Execute o conjunto de testes de unidade com:

pytest test_fish_audio_s2_api.py -v

Executando Testes de Unidade da API Fish Audio S2 com Apidog

Além dos testes de unidade Python, o Apidog possui um recurso integrado de Cenários de Teste (testes automatizados) que executa as mesmas verificações da API Fish Audio S2 sem um ambiente Python local. No Apidog:

1. Abra sua coleção da API Fish Audio S2
2. Clique em Cenários de Teste → Novo Cenário
3. Adicione requisições: health check → requisição TTS → adicionar referência → listar referência
4. Na aba Assertions para a requisição TTS, adicione:

• Status da resposta = 200
• Cabeçalho da resposta content-type contém audio
• Tempo de resposta < 30000ms

1. Clique em Executar para executar a sequência completa de testes de unidade

O Apidog gera um relatório de aprovação/reprovação para cada asserção da API Fish Audio S2, com tempos de resposta e visualizações de diferenças. Você pode exportar este relatório ou agendá-lo para ser executado em um gatilho de CI – tornando o Apidog o executor de testes de unidade para sua API Fish Audio S2 sem escrever nenhum boilerplate de framework de teste.

Recursos Avançados da API Fish Audio S2

Streaming de Áudio da API Fish Audio S2

Para aplicações de reprodução em tempo real, a API Fish Audio S2 suporta streaming em blocos. Defina "streaming": true no corpo da sua requisição:

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)

A API Fish Audio S2 começa a retornar bytes de áudio antes que a síntese completa seja concluída – o tempo para o primeiro áudio é de aproximadamente 100ms. Isso a torna viável para aplicações de voz ao vivo onde um usuário espera feedback imediato.

Controle de Emoção Inline via API Fish Audio S2

A API Fish Audio S2 passa tags de emoção em linguagem natural diretamente no campo text:

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

Nenhum parâmetro especial é necessário – o modelo interpreta as tags entre colchetes como instruções de prosódia. Exemplos de tags válidas da fonte Fish Speech: [laugh], [cough], [pitch up], [professional broadcast tone], [whisper in small voice].

Conclusão

A API Fish Audio S2 expõe um motor TTS verdadeiramente de nível de produção através de uma interface REST limpa. Desde a síntese básica até a clonagem de voz zero-shot e streaming em tempo real, os seis endpoints cobrem toda a gama de fluxos de trabalho de geração de voz que um desenvolvedor precisa. As chaves para uma integração confiável são: definir os parâmetros de amostragem corretos (temperature, top_p, repetition_penalty), gerenciar corretamente o ciclo de vida do áudio de referência e manter um conjunto de testes de unidade que valida o contrato de cada endpoint.

O Apidog reduz drasticamente a curva de aprendizado. Use-o para enviar sua primeira requisição à API Fish Audio S2 em menos de dois minutos, ouvir respostas de áudio binário inline, gerar código cliente para copiar e colar e executar testes de unidade automatizados contra cada endpoint da API Fish Audio S2 sem configurar um framework de teste. Quando estiver pronto para compartilhar a especificação da API com sua equipe ou documentar a integração da API Fish Audio S2 para stakeholders, a documentação auto-gerada do Apidog mantém tudo sincronizado.

Baixe o Apidog gratuitamente e importe a coleção da API Fish Audio S2 para começar a testar hoje.

FAQ

O que é a API Fish Audio S2? A API Fish Audio S2 é a interface REST para o Fish Speech S2-Pro, um modelo de texto para fala de 4 bilhões de parâmetros treinado em 10 milhões de horas de áudio. Ela suporta clonagem de voz, streaming, controle de emoção e mais de 50 idiomas via endpoints HTTP sob /v1/.

Como faço para me autenticar com a API Fish Audio S2? Envie um token Bearer no cabeçalho de cada requisição: Authorization: Bearer YOUR_API_KEY. A chave da API é configurada na inicialização do servidor via flag --api-key. O Apidog permite que você armazene este token no nível do ambiente para que ele se aplique automaticamente a todas as requisições da API Fish Audio S2.

Posso testar unidades de integrações da API Fish Audio S2 sem escrever código? Sim. O recurso Cenários de Teste do Apidog permite que você construa e execute testes de unidade contra qualquer endpoint da API Fish Audio S2 através de uma interface visual. Você define as asserções (código de status, tempo de resposta, valores de cabeçalho) e o Apidog as executa sob demanda ou em um agendamento de CI – sem necessidade de configuração de framework de teste.

Quais formatos de áudio a API Fish Audio S2 suporta? A API Fish Audio S2 retorna áudio nos formatos WAV, MP3 ou PCM. Especifique o formato com o campo "format" no corpo da sua requisição TTS. WAV é o padrão.

Como funciona a clonagem de voz na API Fish Audio S2? Carregue um clipe de áudio de referência de 10 a 30 segundos e sua transcrição para POST /v1/references/add. Em seguida, passe o ID da referência para qualquer requisição TTS via "reference_id". A API Fish Audio S2 clona essa voz sem qualquer ajuste fino ou treinamento de modelo adicional.

Qual é o fator em tempo real da API Fish Audio S2? Em uma única NVIDIA H200, a API Fish Audio S2 alcança um RTF (fator em tempo real) de 0,195 com streaming habilitado, o que significa que ela gera cerca de 5 segundos de áudio por segundo de computação. O tempo para o primeiro áudio é de aproximadamente 100ms.

Como testo as respostas da API Fish Audio S2 no Apidog? Quando a API Fish Audio S2 retorna áudio binário, o Apidog renderiza automaticamente um reprodutor de áudio inline. Você não precisa salvar o arquivo localmente para verificar a saída – você pode ouvir, verificar os cabeçalhos de resposta e adicionar asserções tudo a partir do mesmo painel de requisições do Apidog.