Fish TTS API Integração

Este interface fornece conversão de texto em fala, chamada de sons salvos e clonagem instantânea de som, com o endereço POST https://api.acedata.cloud/fish/tts.

Processo de Solicitação

Para usar a API Fish TTS, primeiro acesse o Painel de Controle da Ace Data Cloud para obter seu Token de API, que deve ser guardado.

Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e logar; após a conclusão, você será redirecionado de volta para a página atual. Um Token de API é suficiente para acessar todos os serviços da plataforma, não sendo necessário solicitar um para cada serviço. A primeira solicitação oferece um crédito gratuito para experiência; quando o crédito estiver baixo, você pode recarregar o saldo geral no painel de controle.

📘 Documentação Completa: Fish TTS API →

Cabeçalho da Solicitação

Cabeçalho	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, pode ser `s1`, `s2-pro` ou `s2.1-pro`, padrão `s2-pro`. `s2.1-pro` é a última geração, `s2-pro` é mais expressivo; `s1` é mais estável, textos longos não se desviam facilmente. Todos têm o mesmo preço.

Campos do Corpo da Solicitação

Campo	Tipo	Obrigatório	Descrição
`text`	string	Sim	Texto a ser sintetizado, deve ser uma string não vazia.
`format`	string	Não	Formato de áudio de saída, pode ser `mp3` (padrão), `wav`, `pcm`. `wav` e `pcm` retornam ambos no contêiner WAV. `opus` não é suportado, a entrada resultará em `400`.
`reference_id`	string \| string[]	Não	ID do modelo de som salvo ou público, pode ser criado pela API Fish Model ou recuperado na Consulta de Modelos Fish. Não pode ser usado com `references`.
`references`	object[]	Não	Clonagem instantânea de som, suporta apenas um `{audio, text}`: `audio` é uma URL pública HTTPS MP3/WAV, `text` é a transcrição exata do áudio. Não pode ser usado com `reference_id`.
`sample_rate`	integer	Não	Taxa de amostragem, comumente `16000`, `22050`, `44100`. `format=mp3` padrão é 44100.
`mp3_bitrate`	integer	Não	Taxa de bits MP3, pode ser `64`, `128`, `192`. Apenas `format=mp3` é aplicável.
`prosody`	object	Não	Cobertura de prosódia, suporta `speed` (velocidade, 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, padrão é decidido pelo upstream.
`temperature`	number	Não	Temperatura de amostragem, faixa de aproximadamente 0.0–1.0.
`top_p`	number	Não	Parâmetro de amostragem top-p.
`latency`	string	Não	`normal` ou `balanced`, padrão é automaticamente preenchido como `normal` (transmitir uma string vazia será rejeitado pelo upstream).
`normalize`	boolean	Não	Se o texto deve ser normalizado.
`callback_url`	string	Não	Endereço de callback assíncrono, veja abaixo “Callback Assíncrono”. Esta é uma extensão em relação à interface oficial.

A clonagem instantânea aceita apenas URLs de áudio HTTPS, não aceita MessagePack, Base64, data URI ou URLs com credenciais. O áudio de referência é recomendado entre 10–270 segundos; o Studio usa uma faixa mais conservadora de 10–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://platform2.cdn.acedata.cloud/fish/e2ffcc06-18da-4a8c-b9aa-9337d0f9ec1d.mp3"
}

audio_url aponta para o CDN da plataforma, podendo ser baixado diretamente via GET ou reproduzido em <audio>. A resposta final bem-sucedida também retornará o cost de nível superior, onde amount é o crédito efetivamente deduzido; se houver desconto na conta, list_amount indica o crédito antes do desconto. O link é de uso prolongado, mas ainda é recomendado manter uma cópia em seu próprio armazenamento.

Exemplo 2: Usando a Voz Clonada `reference_id`

Abaixo, um tom de voz em espanhol público na plataforma Fish (_id pode ser recuperado através da Consulta de Modelos Fish):

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://platform2.cdn.acedata.cloud/fish/b6f161f2-a100-4818-add2-47694f234659.mp3"
}

Exemplo 3: Clonagem Instantânea de Som (`references`)

Coloque o áudio de referência em um endereço HTTPS público e forneça a transcrição exata do que foi realmente dito. Este som é usado 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://platform2.cdn.acedata.cloud/fish/6220d605-39d0-4d43-9e58-0f12949dc9b9.mp3",
      "text": "春天的清晨，阳光穿过树叶，落在安静的小路上。"
    }]
  }'

Resposta de sucesso testada:

{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/995dfe37-b187-474d-8323-b08d6678ed8f.mp3",
  "cost": {"amount": 0.007609319999999999, "currency": "crédito"}
}

方式	生命周期	适用场景
`references`	仅本次 TTS 请求	Uso temporário ou cada vez com som diferente
`reference_id`	Pode ser reutilizado	Som público ou som de longo prazo criado através 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": "Fala mais rápida com sobreposições de prosódia.",
    "prosody": { "speed": 1.2, "volume": 0 },
    "format": "mp3"
  }'

Retorno (teste real):

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

speed maior que 1 acelera, menor que 1 desacelera; volume em dB, 0 significa inalterado, números positivos aumentam, negativos diminuem.

Exemplo 5: Alternar modelo + controlar taxa de bits

Para alternar para o modelo estável, use o 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": "mp3 de alta taxa de bits",
    "format": "mp3",
    "mp3_bitrate": 128
  }'

Retorno (teste real):

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

Exemplo 6: Forma de onda PCM bruta

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

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

Retorno (teste real):

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

A extensão do link segue o format na solicitação: mp3 resulta em .mp3, wav e pcm resultam em .wav (container WAV, PCM de 16 bits).

Callback assíncrono (`callback_url`)

A síntese de texto longo pode levar de dez a dezenas de segundos, se a conexão for interrompida, é necessário tentar novamente. Ao passar callback_url no corpo da solicitação, a interface retornará imediatamente {task_id, started_at}, e quando a tarefa for realmente concluída, o resultado completo será enviado de volta para essa URL em formato JSON POST, incluindo o mesmo task_id e o cost final da cobrança. A tarefa inicial confirmada 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": "Hoje o tempo está ótimo, vamos dar uma volta juntos.",
    "format": "mp3",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  }'

Retorno imediato (teste real):

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

Mais tarde, callback_url receberá algo como:

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

Você também pode usar a API de Tarefas Fish para puxar resultados ativamente pelo task_id; o response.cost do estado final registrado será o mesmo que o cost no callback, veja esse documento para mais detalhes.

Tratamento de erros

400 token_mismatched: Parâmetros de solicitação ausentes ou inválidos (o mais comum é text vazio ou format com um valor diferente de mp3/wav/pcm).
401 invalid_token: Token de autenticação inexistente ou inválido.
429 too_many_requests: Limite de taxa da conta atingido.
500 api_error: Erro interno do servidor.

Exemplo de resposta de erro:

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

Erros de validação de parâmetros serão descritos no campo message, indicando os campos inválidos, por exemplo:

{
  "status": 400,
  "message": "[{\"type\":\"literal_error\",\"loc\":[\"format\"],\"msg\":\"A entrada deve ser 'pcm' ou 'mp3'\",\"input\":\"wav\"}]"
}

Conclusão

O custo mínimo para integrar o Fish TTS é: substituir a autenticação pelo token da plataforma no código que já chama api.fish.audio/v1/tts, e incluir explicitamente no corpo da solicitação format: "mp3". Para cenários de texto longo, recomenda-se usar callback_url para callback assíncrono; para descobrir o reference_id de vozes clonadas, utilize a Consulta de Modelos Fish e Obter Modelo Fish.

Primeiros passos

Chat AI

Imagem AI

Vídeo AI

Áudio AI

Web e Dados

CAPTCHA

Identidade

Proxy

Avançado

Coding

Processo de Solicitação

Cabeçalho da Solicitação

Campos do Corpo da Solicitação

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

Exemplo 2: Usando a Voz Clonada `reference_id`

Exemplo 3: Clonagem Instantânea de Som (`references`)

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

Exemplo 5: Alternar modelo + controlar taxa de bits

Exemplo 6: Forma de onda PCM bruta

Callback assíncrono (`callback_url`)

Tratamento de erros

Conclusão

​Processo de Solicitação

​Cabeçalho da Solicitação

​Campos do Corpo da Solicitação

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

​Exemplo 2: Usando a Voz Clonada reference_id

​Exemplo 3: Clonagem Instantânea de Som (references)

​Exemplo 3: Ajustar velocidade / volume (prosody)

​Exemplo 5: Alternar modelo + controlar taxa de bits

​Exemplo 6: Forma de onda PCM bruta

​Callback assíncrono (callback_url)

​Tratamento de erros

​Conclusão

Processo de Solicitação

Cabeçalho da Solicitação

Campos do Corpo da Solicitação

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

Exemplo 2: Usando a Voz Clonada `reference_id`

Exemplo 3: Clonagem Instantânea de Som (`references`)

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

Exemplo 5: Alternar modelo + controlar taxa de bits

Exemplo 6: Forma de onda PCM bruta

Callback assíncrono (`callback_url`)

Tratamento de erros

Conclusão