Fish TTS API Documentation

Cette interface fournit la conversion de texte en parole, l’appel de voix enregistrées et le clonage instantané de voix, à l’adresse POST https://api.acedata.cloud/fish/tts.

Processus de demande

Pour utiliser l’API Fish TTS, commencez par obtenir votre API Token sur le tableau de bord Ace Data Cloud 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, sans avoir à en demander un pour chaque service. La première demande vous donnera un quota gratuit pour une expérience sans frais ; si le quota est insuffisant, vous pouvez recharger le solde général dans le tableau de bord.

📘 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 entraînera un retour direct de `400`.
`reference_id`	string \| string[]	Non	ID du modèle de voix enregistré ou public, pouvant être créé par l’API Fish Model, ou récupéré dans Fish Model Query. Ne peut pas être utilisé avec `references`.
`references`	object[]	Non	Clonage instantané de voix, ne supporte qu’un seul échantillon `{audio, text}` : `audio` est une URL MP3/WAV HTTPS publique, `text` est le script exact de l’audio. Ne peut pas être utilisé 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 s’applique qu’à `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 en amont, par défaut déterminée par l’amont.
`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’amont).
`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.

Le clonage instantané n’accepte que les URL audio HTTPS, n’accepte pas MessagePack, Base64, data URI ou URL avec des identifiants. L’audio de référence est recommandé pour 10 à 270 secondes ; Studio utilise une plage plus conservatrice de 10 à 60 secondes.

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>. La réponse réussie finale renverra également le cost de niveau supérieur, où amount est le montant de crédits réellement déduits ; en cas de remise sur le compte, list_amount indique le montant avant remise. Le lien est utilisable à long terme, mais il est 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 : Clonage instantané de voix (`references`)

Placez l’audio de référence à une adresse HTTPS publique et fournissez le texte exact prononcé. Cette voix est uniquement utilisée pour cette synthèse et ne créera pas de modèle à long terme :

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": "春天的清晨，阳光穿过树叶，落在安静的小路上。"
    }]
  }'

Réponse réussie testée :

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

方式	生命周期	适用场景
`references`	仅本次 TTS 请求	Utilisation temporaire ou chaque fois une voix différente
`reference_id`	可重复使用	Voix publiques ou voix à long terme créées via `/fish/model`

Exemple 3 : Régler la vitesse / le volume (`prosody`)

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Discours plus rapide avec des overrides de prosodie.",
    "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é, nombre positif pour un gain, nombre négatif pour une atténuation.

Exemple 5 : Changer de modèle + Contrôler le débit binaire

Pour passer au modèle stable via l’en-tête HTTP model: s1, 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 binaire",
    "format": "mp3",
    "mp3_bitrate": 128
  }'

Retour (testé) :

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

Exemple 6 : Onde PCM brute

Pour des scénarios nécessitant un assemblage en temps réel dans le navigateur ou un traitement ultérieur (mixage, changement de vitesse) côté client, 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’interface 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 et le cost final de cette demande. La tâche initiale confirmée n’ayant pas encore terminé la synthèse, elle ne contient donc pas de cost.

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 ; le response.cost de l’état final est identique au cost dans le rappel, 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 : Déclenchement de la limite de débit du 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 seront expliquées dans le champ message, 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, remplacez l’authentification par le token de cette plateforme et incluez explicitement dans le corps de la requête format: "mp3". Pour les scénarios de texte long, il est conseillé d’utiliser le rappel asynchrone callback_url ; pour découvrir le reference_id des voix clonées, 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é

Coding

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 : Clonage instantané de voix (`references`)

Exemple 3 : Régler la vitesse / le volume (`prosody`)

Exemple 5 : Changer de modèle + Contrôler le débit binaire

Exemple 6 : 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 : Clonage instantané de voix (references)

​Exemple 3 : Régler la vitesse / le volume (prosody)

​Exemple 5 : Changer de modèle + Contrôler le débit binaire

​Exemple 6 : 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 : Clonage instantané de voix (`references`)

Exemple 3 : Régler la vitesse / le volume (`prosody`)

Exemple 5 : Changer de modèle + Contrôler le débit binaire

Exemple 6 : Onde PCM brute

Rappel asynchrone (`callback_url`)

Gestion des erreurs

Conclusion