> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Fish TTS API Integração

> Fish voice generation API guide - Ace Data Cloud

Esta interface é baseada na [API TTS oficial da Fish Audio](https://docs.fish.audio/text-to-speech/text-to-speech), com diferenças apenas na forma de autenticação (usando o token desta plataforma) e no callback assíncrono (extensão `callback_url`), a estrutura do corpo da solicitação é a mesma que a do upstream. O endereço é `POST https://api.acedata.cloud/fish/tts`.

## Processo de Solicitação

Para usar a API Fish TTS, primeiro acesse o [console da Ace Data Cloud](https://platform.acedata.cloud/console/applications) para obter seu API Token, que deve ser guardado para uso futuro.

![](https://cdn.acedata.cloud/5hmkdg.jpg)

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 API Token é suficiente para acessar todos os serviços da plataforma, não é necessário solicitar um para cada serviço.** A primeira solicitação oferece um crédito gratuito para que você possa experimentar; quando o crédito estiver baixo, você pode recarregar o saldo geral no [console](https://platform.acedata.cloud/console/coin).

> 📘 Documentação completa: [Fish TTS API →](https://platform.acedata.cloud/services/fish)

## 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` tem maior expressividade; `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 de clone de voz (pode ser criado pela [API Fish Model](https://platform.acedata.cloud/documents/fish-model) ou recuperado na [Consulta de Modelos Fish](https://platform.acedata.cloud/documents/fish-model-query)). |
| `references`   | object\[]           | Não         | Amostras de referência inline, estrutura igual ao upstream, cada item contém `audio` e `text`. Um dos dois 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 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, 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` (enviar 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, veja abaixo "Callback Assíncrono". **Esta é uma extensão em relação à interface oficial**.                                                                                             |

> A nomenclatura dos campos é idêntica ao upstream. Exceto `callback_url`, os outros campos têm significados e valores conforme a [documentação oficial da TTS Fish](https://docs.fish.audio/text-to-speech/text-to-speech).

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

```shell theme={null}
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):

```json theme={null}
{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/e2ffcc06-18da-4a8c-b9aa-9337d0f9ec1d.mp3"
}
```

`audio_url` aponta para o CDN desta plataforma, podendo ser baixado diretamente via GET ou reproduzido em `<audio>`. O link é válido por um longo período, mas ainda é recomendado manter uma cópia em seu próprio armazenamento.

## Exemplo 2: Usando Clone de Voz `reference_id`

Abaixo, um clone de voz pública em espanhol na plataforma Fish (`_id` pode ser recuperado através da [Consulta de Modelos Fish](https://platform.acedata.cloud/documents/fish-model-query)):

```shell theme={null}
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):

```json theme={null}
{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/b6f161f2-a100-4818-add2-47694f234659.mp3"
}
```

## Exemplo 3: Ajustando Velocidade / Volume (`prosody`)

```shell theme={null}
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):

```json theme={null}
{
  "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 sem alteração, números positivos aumentam, negativos diminuem.

## Exemplo 4: Mudando Modelo + Controlando Taxa de Bits

Através do cabeçalho HTTP `model: s1` mude para o modelo estável, adicionando `mp3_bitrate: 128` no corpo da solicitação para controlar a taxa de bits MP3:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s1' \
  -d '{
    "text": "alta taxa de bits mp3",
    "format": "mp3",
    "mp3_bitrate": 128
  }'
```

Retorno (medido):

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

## Exemplo 5: Forma de onda PCM bruta

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

```shell theme={null}
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 (medido):

```json theme={null}
{
  "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 textos longos pode levar de dez a várias dezenas de segundos, e 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 como um POST JSON para essa URL, com o mesmo `task_id` no corpo da solicitação.

```shell theme={null}
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 sair para dar uma volta.",
    "format": "mp3",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  }'
```

Retorno imediato (medido):

```json theme={null}
{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "started_at": 1778462584.742
}
```

Mais tarde, `callback_url` receberá algo como:

```json theme={null}
{
  "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](https://platform.acedata.cloud/documents/fish-tasks) para puxar resultados ativamente por `task_id`, veja o 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:

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

Erros de validação de parâmetros incluirão a mensagem de erro original do pydantic no campo `message`, facilitando a localização do campo inválido, por exemplo:

```json theme={null}
{
  "status": 400,
  "message": "[{\"type\":\"literal_error\",\"loc\":[\"format\"],\"msg\":\"Input 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 `format: "mp3"` no corpo da solicitação. Para cenários de texto longo, recomenda-se usar o callback assíncrono `callback_url`; para descobrir o `reference_id` de clonagem de timbre, consulte a [Consulta de Modelos Fish](https://platform.acedata.cloud/documents/fish-model-query) e [Obter Modelo Fish](https://platform.acedata.cloud/documents/fish-model-get).