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

A API Fish Audio S2 oferece uma interface REST de texto para fala pronta para produção, baseada em um modelo de 4 bilhões de parâmetros treinado em 10 milhões de horas de áudio. Com suporte a clonagem de voz, streaming e mais de 50 idiomas, integrar a API Fish Audio S2 de forma eficiente exige domínio no envio de requisições, no gerenciamento de referências e na execução de testes automatizados. O Apidog é a ferramenta mais ágil para explorar, documentar e validar cada endpoint dessa API.

Experimente o Apidog hoje mesmo

Introdução

Modelos TTS de última geração, como o Fish Audio S2, já ultrapassaram a barreira das vozes robóticas: agora sussurram, riem e mudam o tom como humanos. O Fish Audio S2, com 4 bilhões de parâmetros treinados em áudio multilíngue, gera fala natural e realista.

Seja para automação de podcasts, assistentes de voz ou dublagem em tempo real, integrar a API Fish Audio S2 vai além de uma simples requisição POST. É preciso configurar autenticação, gerenciar áudios de referência, entender o streaming e garantir a confiabilidade da integração com testes unitários robustos.

💡Antes de começar, baixe o Apidog gratuitamente. Teste tags de emoção, blocos de streaming, payloads de clonagem e respostas de áudio binário visualmente, sem código. Simule, valide e ouça o resultado na hora pra garantir a integração TTS perfeita desde o início.

O Que É a API Fish Audio S2?

A API Fish Audio S2 é a interface HTTP do Fish Speech S2-Pro, um sistema TTS open source com arquitetura Dual-Autoregressive. A separação entre geração semântica e residual permite síntese de alta qualidade com baixo tempo de resposta (RTF 0,195 em uma NVIDIA H200).

Principais recursos:

Recurso	Detalhe
Idiomas	~50 (Inglês, Chinês, Japonês, Coreano, Árabe, Francês, Alemão, etc.)
Clonagem de voz	Áudio de referência de 10–30s, sem ajuste fino
Controle de emoção inline	Tags no texto: [laugh], [whispers], [super happy]
Multi-locutor	Token <|speaker:i|> nativo
Streaming	Áudio em blocos via "streaming": true
Formatos de saída	WAV, MP3, PCM
Autenticação	Bearer Token (Authorization: Bearer YOUR_API_KEY)

A URL base local padrão é http://127.0.0.1:8080. Todos os endpoints estão sob /v1/.

Primeiros Passos com a API Fish Audio S2 e Apidog

Pré-requisitos para a API Fish Audio S2

Você precisará de um servidor Fish Speech S2-Pro rodando e de um cliente API que suporte respostas de áudio binário.

Inicie o servidor:

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: ativa torch.compile, reduzindo latência de inferência (~10x mais rápido).
• --half: usa FP16 para menor uso de memória GPU.

Valide o servidor 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 e crie um projeto HTTP. Adicione http://127.0.0.1:8080 em Environments e configure o cabeçalho global:

Authorization: Bearer YOUR_API_KEY

Assim, todas as requisições herdaram o token automaticamente, facilitando a troca entre ambientes (desenvolvimento, staging, produção).

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

Testando o Endpoint de Text-to-Speech

O endpoint principal é POST /v1/tts. No Apidog, crie uma requisição POST com o corpo abaixo:

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

Parâmetro	Tipo	Padrão	Descrição
text	string	obrigatório	Texto para sintetizar
format	string	"wav"	Formato de saída: wav, mp3, pcm
chunk_length	int	200	Tamanho do bloco (100–300)
seed	int	null	Seed para saída reproduzível
streaming	bool	false	Streaming em blocos
max_new_tokens	int	1024	Máximo de tokens a gerar
temperature	float	0.8	Aleatoriedade (0.1–1.0)
top_p	float	0.8	Núcleo da amostragem (0.1–1.0)
repetition_penalty	float	1.1	Penalidade para repetições (0.9–2.0)
reference_cache	string	"off"	Caching de referência

Clique em Enviar no Apidog. O áudio será exibido em um player na interface – pronto para ouvir sem precisar de código cliente.

Clonagem de Voz com a API Fish Audio S2

Carregando um Áudio de Referência via Apidog

Para usar a clonagem zero-shot, envie um áudio em base64 e transcrição via POST /v1/references/add:

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

No Apidog, selecione Binary para enviar o arquivo de áudio ou Form Data para enviar arquivo e texto juntos. A resposta será:

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

Depois, use o reference_id em qualquer chamada TTS:

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

Salve essa requisição como modelo no painel de Gerenciamento de Referência do Apidog e altere vozes apenas mudando o reference_id.

Como Testar Unidades de Integração da API Fish Audio S2

Por Que Testes de Unidade São Importantes

Falhas de integração como referência inexistente, parâmetro fora dos limites, erro de streaming ou formato incompatível só aparecem com testes automatizados. Testes unitários evitam regressões e garantem robustez da integração.

Escrevendo Testes de Unidade com Python

Use pytest e httpx para cobrir os fluxos essenciais:

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:
    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):
        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,
        )

Execute com:

pytest test_fish_audio_s2_api.py -v

Executando Testes de Unidade no Apidog

O Apidog permite criar Cenários de Teste automatizados sem código:

1. Abra a coleção da API Fish Audio S2
2. Vá em Cenários de Teste → Novo Cenário
3. Adicione as requisições: health check, TTS, adicionar referência, listar referência
4. Adicione asserções na aba Assertions:
   • Status = 200
   • Cabeçalho content-type contém audio
   • Tempo de resposta < 30000ms
5. Clique em Executar para rodar todos os testes do cenário

O Apidog gera relatórios detalhados de cada asserção, com tempos e diferenças. Você pode exportar ou agendar esses testes via CI, sem precisar de boilerplate de testes.

Recursos Avançados da API Fish Audio S2

Streaming de Áudio

Para aplicações em tempo real, ative o streaming com "streaming": true:

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)

O áudio começa a ser retornado em menos de 100ms, ideal para feedback imediato em aplicações ao vivo.

Controle de Emoção Inline

Use tags diretamente no texto:

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

O modelo interpreta as tags entre colchetes como instruções de prosódia. Exemplos: [laugh], [cough], [pitch up], [professional broadcast tone], [whisper in small voice].

Conclusão

A API Fish Audio S2 oferece um motor TTS de alto nível via REST, cobrindo síntese básica, clonagem de voz zero-shot e streaming. Para integração confiável: ajuste os parâmetros (temperature, top_p, repetition_penalty), gerencie bem as referências e mantenha testes unitários automatizados.

O Apidog acelera todo o processo: envie a primeira requisição em minutos, ouça o áudio inline, gere código cliente, documente e rode testes de unidade sem precisar configurar frameworks. Compartilhe especificações e mantenha tudo sincronizado com a documentação auto-gerada.

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

FAQ

O que é a API Fish Audio S2? É a interface REST do Fish Speech S2-Pro, modelo TTS de 4 bilhões de parâmetros treinado em 10 milhões de horas de áudio. 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? Envie Authorization: Bearer YOUR_API_KEY no cabeçalho de cada requisição. O Apidog permite armazenar esse token no ambiente e aplicá-lo automaticamente.

Posso testar integrações sem escrever código? Sim. Com Cenários de Teste do Apidog, crie e execute testes unitários para qualquer endpoint da API Fish Audio S2 visualmente, definindo asserções e agendando execuções via CI.

Quais formatos de áudio são suportados? WAV, MP3 ou PCM. Especifique via campo "format" no corpo da requisição TTS. WAV é o padrão.

Como funciona a clonagem de voz? Envie um clipe de 10–30s e transcrição para POST /v1/references/add. Use o "reference_id" em TTS. Não é preciso ajuste fino ou treinamento extra.

Qual o fator em tempo real? Em uma NVIDIA H200, RTF de 0,195 com streaming, ou seja, gera 5s de áudio por segundo de computação. O tempo até o primeiro áudio é ~100ms.

Como testo respostas da API no Apidog? O Apidog exibe automaticamente um player de áudio inline para respostas binárias de áudio. Ouça, verifique cabeçalhos e adicione asserções sem sair da interface.