> ## 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 Documentation

> Fish voice generation API guide - Ace Data Cloud

Cette interface est basée sur [Fish Audio Official TTS API](https://docs.fish.audio/text-to-speech/text-to-speech), avec des différences uniquement dans le mode d'authentification (utilisation du token de cette plateforme) et le rappel asynchrone (extension `callback_url`), la structure du corps de la requête étant identique à celle de l'upstream. L'adresse est `POST https://api.acedata.cloud/fish/tts`.

## Processus de demande

Pour utiliser l'API Fish TTS, commencez par obtenir votre API Token sur [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) pour le garder en réserve.

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

Si vous n'êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion pour vous inviter à vous inscrire et à vous connecter, après quoi vous serez automatiquement renvoyé à la page actuelle.

**Un seul API Token suffit pour appeler tous les services de la plateforme, il n'est pas nécessaire de demander un pour chaque service.** La première demande vous donnera un quota gratuit pour une expérience sans frais ; en cas de quota insuffisant, vous pouvez recharger le solde général dans la [console](https://platform.acedata.cloud/console/coin).

> 📘 Documentation complète : [Fish TTS API →](https://platform.acedata.cloud/services/fish)

## En-têtes de requête

| En-tête         | Obligatoire | Description                                                                                                                                                                                                                                   |
| --------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `authorization` | Oui         | `Bearer {token}`, où `{token}` est la clé demandée sur cette plateforme.                                                                                                                                                                      |
| `content-type`  | Oui         | `application/json`.                                                                                                                                                                                                                           |
| `accept`        | Non         | `application/json`.                                                                                                                                                                                                                           |
| `model`         | Non         | Modèle TTS, options `s1`, `s2-pro` ou `s2.1-pro`, par défaut `s2-pro`. `s2.1-pro` est la dernière génération, `s2-pro` est plus expressif ; `s1` est plus stable, les longs textes ne s'écartent pas facilement. Les trois sont au même prix. |

## Champs du corps de la requête

| Champ          | Type                | Obligatoire | Description                                                                                                                                                                                                     |
| -------------- | ------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text`         | string              | Oui         | Texte à synthétiser, chaîne non vide.                                                                                                                                                                           |
| `format`       | string              | Non         | Format audio de sortie, options `mp3` (par défaut), `wav`, `pcm`. `wav` et `pcm` retournent tous deux un conteneur WAV. `opus` n'est pas supporté, une entrée renverra directement `400`.                       |
| `reference_id` | string \| string\[] | Non         | ID de la voix clonée (peut être créé par [Fish Model API](https://platform.acedata.cloud/documents/fish-model) ou récupéré dans [Fish Model Query](https://platform.acedata.cloud/documents/fish-model-query)). |
| `references`   | object\[]           | Non         | Échantillons de référence en ligne, structure identique à l'upstream, chaque élément contenant `audio` et `text`. Un des deux avec `reference_id`.                                                              |
| `sample_rate`  | integer             | Non         | Taux d'échantillonnage, couramment `16000`, `22050`, `44100`. `format=mp3` par défaut à 44100.                                                                                                                  |
| `mp3_bitrate`  | integer             | Non         | Débit binaire MP3, options `64`, `128`, `192`. Ne fonctionne que si `format=mp3`.                                                                                                                               |
| `prosody`      | object              | Non         | Couverture prosodique, supporte `speed` (vitesse de parole, 1.0 étant la vitesse normale) et `volume` (gain de volume en dB). Par exemple `{"speed":1.2,"volume":0}`.                                           |
| `chunk_length` | integer             | Non         | Longueur de fragment de l'upstream, par défaut déterminée par l'upstream.                                                                                                                                       |
| `temperature`  | number              | Non         | Température d'échantillonnage, plage d'environ 0.0–1.0.                                                                                                                                                         |
| `top_p`        | number              | Non         | Paramètre d'échantillonnage top-p.                                                                                                                                                                              |
| `latency`      | string              | Non         | `normal` ou `balanced`, par défaut automatiquement complété par cette interface à `normal` (une chaîne vide sera refusée par l'upstream).                                                                       |
| `normalize`    | boolean             | Non         | Indique si le texte doit être normalisé.                                                                                                                                                                        |
| `callback_url` | string              | Non         | Adresse de rappel asynchrone, voir ci-dessous « Rappel asynchrone ». **Ceci est une extension par rapport à l'interface officielle**.                                                                           |

> La nomenclature des champs est identique à celle de l'upstream. À l'exception de `callback_url`, les autres champs ont la même signification et les mêmes valeurs que celles indiquées dans [Fish Official TTS Documentation](https://docs.fish.audio/text-to-speech/text-to-speech).

## Exemple 1 : Requête minimale (`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"
  }'
```

Retour (testé) :

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

`audio_url` pointe vers le CDN de cette plateforme, pouvant être téléchargé directement par GET ou joué dans `<audio>`. Le lien est valable à long terme, mais il est toujours conseillé de conserver une copie dans votre propre stockage.

## Exemple 2 : Utilisation de la voix clonée `reference_id`

Voici un exemple avec une voix espagnole publique sur la plateforme Fish (`_id` pouvant être récupéré via [Fish Model Query](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"
  }'
```

Retour (testé) :

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

## Exemple 3 : Ajustement de la vitesse / 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"
  }'
```

Retour (testé) :

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

`speed` supérieur à 1 accélère, inférieur à 1 ralentit ; `volume` en dB, 0 signifie inchangé, les nombres positifs augmentent, les négatifs diminuent.

## Exemple 4 : Changement de modèle + contrôle du débit binaire

En utilisant l'en-tête HTTP `model: s1` pour passer au modèle stable, ajoutez `mp3_bitrate: 128` dans le corps de la requête pour contrôler le débit binaire 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": "mp3 à haut débit",
    "format": "mp3",
    "mp3_bitrate": 128
  }'
```

Retour (testé) :

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

## Exemple 5 : Onde PCM brute

Pour les scénarios nécessitant un assemblage en temps réel dans le navigateur, ou un traitement ultérieur côté client (mixage, changement de vitesse), il est recommandé d'utiliser `pcm` :

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

Retour (testé) :

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

> L'extension du lien suit le `format` dans la requête : `mp3` donne `.mp3`, `wav` et `pcm` donnent `.wav` (conteneur WAV, PCM 16 bits).

## Rappel asynchrone (`callback_url`)

La synthèse d'un long texte peut prendre de quelques secondes à plusieurs dizaines de secondes, si la connexion est interrompue, il faut réessayer. En passant `callback_url` dans le corps de la requête, l'API renverra immédiatement `{task_id, started_at}`, et lorsque le traitement est réellement terminé, le résultat complet sera rappelé à cette URL sous forme de POST JSON, avec le même `task_id` dans le corps de la requête.

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Il fait vraiment beau aujourd'hui, sortons nous promener.",
    "format": "mp3",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  }'
```

Retour immédiat (testé) :

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

Plus tard, `callback_url` recevra un message de la forme :

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

Il est également possible d'utiliser [Fish Tasks API](https://platform.acedata.cloud/documents/fish-tasks) pour récupérer les résultats par `task_id`, voir ce document pour plus de détails.

## Gestion des erreurs

* `400 token_mismatched` : Paramètres de requête manquants ou non valides (le plus courant est que `text` est vide, ou que `format` a une valeur autre que `mp3`/`wav`/`pcm`).
* `401 invalid_token` : Le token d'authentification n'existe pas ou est invalide.
* `429 too_many_requests` : Limite de taux déclenchée pour le compte.
* `500 api_error` : Erreur interne du serveur.

Exemple de réponse d'erreur :

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "échec de la récupération"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

Les erreurs de validation des paramètres incluront le message d'erreur d'origine de pydantic dans le champ `message`, facilitant l'identification du champ non valide, par exemple :

```json theme={null}
{
  "status": 400,
  "message": "[{\"type\":\"literal_error\",\"loc\":[\"format\"],\"msg\":\"L'entrée doit être 'pcm' ou 'mp3'\",\"input\":\"wav\"}]"
}
```

## Conclusion

Le coût minimal pour intégrer Fish TTS est : dans le code déjà appelant `api.fish.audio/v1/tts`, remplacer l'authentification par le token de la plateforme, et dans le corps de la requête **inclure explicitement** `format: "mp3"`. Pour les scénarios de long texte, il est conseillé d'utiliser le rappel asynchrone `callback_url` ; pour la découverte de l'`id de référence` de la voix clonée, veuillez utiliser [Fish Model Query](https://platform.acedata.cloud/documents/fish-model-query) et [Fish Model Get](https://platform.acedata.cloud/documents/fish-model-get).