Instruções de integração da API Fish TTS

Esta API fornece conversão de texto em fala, chamada de vozes salvas e clonagem instantânea de voz única, no endereço POST https://api.acedata.cloud/fish/tts。

Processo de solicitação

Para usar a API Fish TTS, primeiro obtenha seu API Token no Console do Ace Data Cloud e guarde-o para uso posterior.

Se você ainda não estiver conectado ou registrado, será automaticamente redirecionado para a página de login, onde será convidado a se registrar e entrar; após a conclusão, retornará automaticamente à página atual. Um único API Token pode chamar todos os serviços da plataforma, sem necessidade de solicitar um separadamente para cada serviço. A primeira solicitação concede créditos gratuitos, permitindo uma experiência sem custo; quando os créditos forem insuficientes, você poderá recarregar o saldo geral no console.

📘 Documentação completa: Fish TTS API →

Cabeçalhos da solicitação

Header	Obrigatório	Descrição
`authorization`	Sim	`Bearer {token}`, onde `{token}` é a chave solicitada nesta plataforma.
`content-type`	Sim	`application/json`.
`accept`	Não	`application/json`.
`model`	Não	Modelo TTS, opcional entre `s1`, `s2-pro` ou `s2.1-pro`, com padrão `s2-pro`. `s2.1-pro` é a geração mais recente, e `s2-pro` possui forte expressividade; `s1` é mais estável e tem menor propensão a se desviar em textos longos. Os três têm o mesmo preço.

Campos do corpo da solicitação

Campo	Tipo	Obrigatório	Descrição
`text`	string	Sim	O texto a ser sintetizado, uma string não vazia.
`format`	string	Não	Formato do áudio de saída, opcional entre `mp3` (padrão), `wav`, `pcm`. Tanto `wav` quanto `pcm` retornam contêineres WAV. `opus` não é suportado e seu envio retornará diretamente `400`.
`reference_id`	string \| string[]	Não	ID do modelo de uma voz salva ou pública, que pode ser criado pela Fish Model API ou pesquisado no Fish Model Query. Não pode ser usado junto com `references`.
`references`	object[]	Não	Clonagem instantânea de voz única, suporta apenas uma amostra `{audio, text}`: `audio` é uma URL pública HTTPS de MP3/WAV, e `text` é a transcrição literal precisa do áudio. Não pode ser usado junto com `reference_id`.
`sample_rate`	integer	Não	Taxa de amostragem, comumente `16000`, `22050`, `44100`. O padrão de `format=mp3` é 44100.
`mp3_bitrate`	integer	Não	Taxa de bits de MP3, opcional entre `64`, `128`, `192`. Só tem efeito com `format=mp3`.
`prosody`	object	Não	Substituição de prosódia, suporta `speed` (velocidade da fala, 1.0 é a velocidade original) e `volume` (ganho de volume em dB). Por exemplo, `{"speed":1.2,"volume":0}`.
`chunk_length`	integer	Não	Comprimento do fragmento upstream, determinado pelo upstream por padrão.
`temperature`	number	Não	Temperatura de amostragem, intervalo de aproximadamente 0.0–1.0.
`top_p`	number	Não	Parâmetro de amostragem top-p.
`latency`	string	Não	`normal` ou `balanced`; se omitido, esta API preencherá automaticamente `normal` (enviar diretamente uma string vazia será rejeitado pelo upstream).
`normalize`	boolean	Não	Se deve normalizar o texto.
`callback_url`	string	Não	Endereço de callback assíncrono; consulte «Callback assíncrono» abaixo para detalhes. Esta é uma extensão em relação à API oficial.

A clonagem única aceita apenas URLs de áudio HTTPS, não aceita MessagePack, Base64, URI de dados ou URLs com credenciais. Recomenda-se que o áudio de referência tenha entre 10 e 270 segundos; o Studio usa uma faixa mais conservadora de 10 a 60 segundos.

Exemplo 1: solicitação mínima (`text` + `format=mp3`)

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Hello world.",
    "format": "mp3"
  }'

Retorno (testado):

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/e2ffcc06-18da-4a8c-b9aa-9337d0f9ec1d-230825dfc559.mp3"
}

audio_url aponta para a CDN desta plataforma e pode ser baixado diretamente com GET ou reproduzido em <audio>. A resposta final bem-sucedida também retornará cost no nível superior, em que amount são os Credits efetivamente deduzidos nesta solicitação; se houver desconto na conta, list_amount representa os créditos antes do desconto. O link permanece disponível por muito tempo, mas ainda é recomendável manter uma cópia em seu próprio armazenamento.

Exemplo 2: usar o timbre clonado `reference_id`

A seguir, é usado um timbre público em espanhol na plataforma Fish (o _id pode ser obtido por meio de pesquisa no Fish Model Query):

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Hermanos míos, hoy es un buen día.",
    "reference_id": "8d2c17a9b26d4d83888ea67a1ee565b2",
    "format": "mp3"
  }'

Retorno (testado):

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/b6f161f2-a100-4818-add2-47694f234659-6532864739de.mp3"
}

Exemplo 3: clonagem instantânea de voz única (`references`)

Coloque o áudio de referência em um endereço HTTPS público e forneça o texto exato realmente falado nele. Esta voz será usada apenas para esta síntese e não criará um modelo de longo prazo:

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "新的旅程从这一刻开始，让我们一起向前。",
    "format": "mp3",
    "references": [{
      "audio": "https://cdn.acedata.cloud/assets/examples/fish/6220d605-39d0-4d43-9e58-0f12949dc9b9-570cfdf96ad9.mp3",
      "text": "春天的清晨，阳光穿过树叶，落在安静的小路上。"
    }]
  }'

Resposta de sucesso real:

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/995dfe37-b187-474d-8323-b08d6678ed8f-6359be9f8873.mp3",
  "cost": {"amount": 0.007609319999999999, "currency": "credit"}
}

Método	Ciclo de vida	Cenário aplicável
`references`	Apenas esta solicitação de TTS	Uso temporário ou voz diferente a cada vez
`reference_id`	Pode ser reutilizado	Vozes públicas ou vozes de longo prazo criadas por meio de `/fish/model`

Exemplo 3: ajustar velocidade / volume (`prosody`)

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Faster speech with prosody overrides.",
    "prosody": { "speed": 1.2, "volume": 0 },
    "format": "mp3"
  }'

Retorno (testado):

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3"
}

speed maior que 1 acelera, menor que 1 desacelera; a unidade de volume é dB, 0 indica sem alteração, números positivos aumentam e números negativos reduzem.

Exemplo 5: alternar modelo + controlar taxa de bits

Alterne para o modelo estável por meio do cabeçalho HTTP model: s1 e adicione mp3_bitrate: 128 no corpo da solicitação para controlar a taxa de bits do MP3:

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s1' \
  -d '{
    "text": "high bitrate mp3",
    "format": "mp3",
    "mp3_bitrate": 128
  }'

Retorno (testado):

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/7e7abf3d-3d72-4c9f-8eb6-8af932d7c96e-6f11bf2f30e9.mp3"
}

Exemplo 6: forma de onda bruta PCM

Para cenários que exigem concatenação em tempo real no navegador ou processamento posterior no cliente (mixagem, alteração de velocidade), é recomendado usar pcm:

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "hi",
    "format": "pcm",
    "sample_rate": 16000
  }'

Retorno (testado):

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/64adc04b-c196-4a0f-9070-222ba101ce6c-fc50de38c165.wav"
}

A extensão do link segue o format da solicitação: mp3 resulta em .mp3, enquanto wav e pcm resultam em .wav (contêiner WAV, PCM de 16 bits).

Retorno de chamada assíncrono (`callback_url`)

A síntese de texto longo de uma só vez pode levar de mais de dez segundos a dezenas de segundos; se a conexão for interrompida, é necessário tentar novamente. Após passar callback_url no corpo da solicitação, a interface retornará imediatamente {task_id, started_at}. Quando o processamento upstream for realmente concluído, o resultado completo será retornado por POST JSON para essa URL, com o mesmo task_id e o cost de nível superior da cobrança final desta vez no corpo da solicitação. A confirmação inicial da tarefa ainda não concluiu a síntese, portanto não inclui cost.

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "今天天气真好，我们一起出去散散步吧。",
    "format": "mp3",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  }'

Retorno imediato (testado):

{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "started_at": 1778462584.742
}

Posteriormente, callback_url receberá algo como:

{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/bd66b8c5-7543-4557-b684-baa72407e336-52f2e79732f2.mp3"
}

Também é possível usar a Fish Tasks API para buscar ativamente o resultado por task_id; o response.cost no registro de estado final é consistente com o cost no retorno de chamada. Consulte essa documentação para mais detalhes.

Tratamento de erros

400 token_mismatched: parâmetros da solicitação ausentes ou inválidos (o mais comum é text estar vazio ou format receber um valor diferente de mp3/wav/pcm).
401 invalid_token: o token de autenticação não existe ou é inválido.
429 too_many_requests: o limite de taxa da conta foi acionado.
500 api_error: erro interno do servidor.

Exemplo de resposta de erro:

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Os erros de validação de parâmetros explicarão o campo inválido no campo message, por exemplo:

{
  "status": 400,
  "message": "[{\"type\":\"literal_error\",\"loc\":[\"format\"],\"msg\":\"Input should be 'pcm' or 'mp3'\",\"input\":\"wav\"}]"
}

Conclusão

O custo mínimo para integrar o Fish TTS é: no código existente que chama api.fish.audio/v1/tts, substituir a autenticação pelo token desta plataforma e incluir explicitamente format: "mp3" no corpo da solicitação. Para cenários de texto longo, recomenda-se usar o retorno de chamada assíncrono callback_url; para descobrir o reference_id de vozes clonadas, use em conjunto Fish Model Query e Fish Model Get.

Primeiros passos

Chat AI

Imagem AI

Vídeo AI

Áudio AI

Web e Dados

CAPTCHA

Identidade

Coding

Mais guias

Instruções de integração da API Fish TTS

Processo de solicitação

Cabeçalhos da solicitação

Campos do corpo da solicitação

Exemplo 1: solicitação mínima (`text` + `format=mp3`)

Exemplo 2: usar o timbre clonado `reference_id`

Exemplo 3: clonagem instantânea de voz única (`references`)

Exemplo 3: ajustar velocidade / volume (`prosody`)

Exemplo 5: alternar modelo + controlar taxa de bits

Exemplo 6: forma de onda bruta PCM

Retorno de chamada assíncrono (`callback_url`)

Tratamento de erros

Conclusão

​Processo de solicitação

​Cabeçalhos da solicitação

​Campos do corpo da solicitação

​Exemplo 1: solicitação mínima (text + format=mp3)

​Exemplo 2: usar o timbre clonado reference_id

​Exemplo 3: clonagem instantânea de voz única (references)

​Exemplo 3: ajustar velocidade / volume (prosody)

​Exemplo 5: alternar modelo + controlar taxa de bits

​Exemplo 6: forma de onda bruta PCM

​Retorno de chamada assíncrono (callback_url)

​Tratamento de erros

​Conclusão

Processo de solicitação

Cabeçalhos da solicitação

Campos do corpo da solicitação

Exemplo 1: solicitação mínima (`text` + `format=mp3`)

Exemplo 2: usar o timbre clonado `reference_id`

Exemplo 3: clonagem instantânea de voz única (`references`)

Exemplo 3: ajustar velocidade / volume (`prosody`)

Exemplo 5: alternar modelo + controlar taxa de bits

Exemplo 6: forma de onda bruta PCM

Retorno de chamada assíncrono (`callback_url`)

Tratamento de erros

Conclusão