Fish TTS API Documentation

Cette interface est basée sur Fish Audio Official TTS API, 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 pour le garder en réserve.

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.

📘 Documentation complète : Fish TTS API →

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 ou récupéré dans 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.

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

Retour (testé) :

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

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

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

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

Retour (testé) :

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

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

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

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

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

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

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

Plus tard, callback_url recevra un message de la forme :

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

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

{
  "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 et Fish Model Get.

Démarrage

Chat IA

Image IA

Vidéo IA

Audio IA

Web & Données

CAPTCHA

Identité

Proxy

Avancé

Fish TTS API Documentation

Processus de demande

En-têtes de requête

Champs du corps de la requête

Exemple 1 : Requête minimale (`text` + `format=mp3`)

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

Exemple 3 : Ajustement de la vitesse / volume (`prosody`)

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

Exemple 5 : Onde PCM brute

Rappel asynchrone (`callback_url`)

Gestion des erreurs

Conclusion

​Processus de demande

​En-têtes de requête

​Champs du corps de la requête

​Exemple 1 : Requête minimale (text + format=mp3)

​Exemple 2 : Utilisation de la voix clonée reference_id

​Exemple 3 : Ajustement de la vitesse / volume (prosody)

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

​Exemple 5 : Onde PCM brute

​Rappel asynchrone (callback_url)

​Gestion des erreurs

​Conclusion

Processus de demande

En-têtes de requête

Champs du corps de la requête

Exemple 1 : Requête minimale (`text` + `format=mp3`)

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

Exemple 3 : Ajustement de la vitesse / volume (`prosody`)

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

Exemple 5 : Onde PCM brute

Rappel asynchrone (`callback_url`)

Gestion des erreurs

Conclusion