Instructions d’intégration de l’API Fish TTS

Cette interface fournit la synthèse vocale à partir de texte, l’appel de voix enregistrées et le clonage vocal instantané à usage unique, à l’adresse POST https://api.acedata.cloud/fish/tts.

Processus de demande

Pour utiliser l’API Fish TTS, obtenez d’abord votre API Token dans la console Ace Data Cloud et conservez-le pour une utilisation ultérieure.

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, puis vous reviendrez automatiquement à la page actuelle une fois terminé. Un seul API Token permet d’appeler tous les services de la plateforme, sans avoir besoin d’en demander un séparément pour chaque service. Lors de votre première demande, un quota gratuit vous sera offert pour une expérience gratuite ; lorsque le quota est insuffisant, vous pouvez recharger votre solde universel dans la console.

📘 Documentation complète : Fish TTS API →

En-têtes de requête

Header	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, au choix parmi `s1`, `s2-pro` ou `s2.1-pro`, avec `s2-pro` par défaut. `s2.1-pro` est la dernière génération, `s2-pro` est très expressif ; `s1` est plus stable et moins susceptible de dévier sur les textes longs. Les trois ont le même prix.

Champs du corps de la requête

Champ	Type	Obligatoire	Description
`text`	string	Oui	Le texte à synthétiser, chaîne non vide.
`format`	string	Non	Format audio de sortie, au choix parmi `mp3` (par défaut), `wav`, `pcm`. Les retours de `wav` et `pcm` utilisent tous deux un conteneur WAV. `opus` n’est pas pris en charge et son envoi renvoie directement `400`.
`reference_id`	string \| string[]	Non	ID du modèle d’une voix enregistrée ou publique, pouvant être créé via Fish Model API, ou recherché dans Fish Model Query. Ne peut pas être utilisé en même temps que `references`.
`references`	object[]	Non	Clonage vocal instantané à usage unique, ne prend en charge qu’un seul échantillon `{audio, text}` : `audio` est une URL MP3/WAV HTTPS publique, et `text` est la transcription exacte de l’audio. Ne peut pas être utilisé en même temps que `reference_id`.
`sample_rate`	integer	Non	Taux d’échantillonnage, couramment `16000`, `22050`, `44100`. La valeur par défaut pour `format=mp3` est 44100.
`mp3_bitrate`	integer	Non	Débit MP3, au choix parmi `64`, `128`, `192`. S’applique uniquement à `format=mp3`.
`prosody`	object	Non	Remplacement de prosodie, prend en charge `speed` (vitesse de parole, 1.0 est la vitesse d’origine) et `volume` (gain de volume en dB). Par exemple `{"speed":1.2,"volume":0}`.
`chunk_length`	integer	Non	Longueur des segments en amont, déterminée par l’amont par défaut.
`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`, en l’absence de valeur cette interface complète automatiquement avec `normal` (transmettre directement une chaîne vide sera refusé par l’amont).
`normalize`	boolean	Non	Indique s’il faut normaliser le texte.
`callback_url`	string	Non	Adresse de rappel asynchrone, voir « Rappel asynchrone » ci-dessous pour les détails. Il s’agit d’une extension par rapport à l’interface officielle.

Le clonage à usage unique n’accepte que des URL audio HTTPS, et n’accepte pas MessagePack, Base64, les URI data ni les URL avec identifiants. Il est recommandé que l’audio de référence dure entre 10 et 270 secondes ; Studio utilise une plage plus prudente 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://cdn.acedata.cloud/assets/examples/fish/e2ffcc06-18da-4a8c-b9aa-9337d0f9ec1d-230825dfc559.mp3"
}

audio_url pointe vers le CDN de cette plateforme, et peut être téléchargé directement avec GET ou lu dans <audio>. La réponse finale en cas de succès renvoie également un cost de niveau supérieur, où amount correspond aux Credits effectivement déduits cette fois-ci ; en cas de remise sur le compte, list_amount indique le quota avant remise. Le lien est disponible à long terme, mais il reste recommandé d’en conserver une copie dans votre propre stockage.

Exemple 2 : utiliser la voix clonée `reference_id`

L’exemple ci-dessous utilise une voix espagnole publique sur la plateforme Fish (_id peut être obtenu via une recherche dans 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://cdn.acedata.cloud/assets/examples/fish/b6f161f2-a100-4818-add2-47694f234659-6532864739de.mp3"
}

Exemple 3 : clonage vocal instantané à usage unique (`references`)

Placez l’audio de référence à une adresse HTTPS publique et fournissez le texte exact réellement prononcé. Cette voix est utilisée uniquement pour cette synthèse et ne crée 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://cdn.acedata.cloud/assets/examples/fish/6220d605-39d0-4d43-9e58-0f12949dc9b9-570cfdf96ad9.mp3",
      "text": "春天的清晨，阳光穿过树叶，落在安静的小路上。"
    }]
  }'

Réponse réussie testée :

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

Méthode	Cycle de vie	Cas d’utilisation
`references`	Uniquement pour cette requête TTS	Utilisation temporaire ou voix différente à chaque fois
`reference_id`	Réutilisable	Voix publiques ou voix à long terme créées via `/fish/model`

Exemple 3 : ajuster 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": "Faster speech with prosody overrides.",
    "prosody": { "speed": 1.2, "volume": 0 },
    "format": "mp3"
  }'

Retour (testé) :

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

Une valeur speed supérieure à 1 accélère, inférieure à 1 ralentit ; l’unité de volume est le dB, 0 indique aucune modification, une valeur positive augmente le gain, une valeur négative l’atténue.

Exemple 5 : changer de modèle + contrôler le débit binaire

Basculez vers le modèle stable via l’en-tête HTTP model: s1, et 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": "high bitrate mp3",
    "format": "mp3",
    "mp3_bitrate": 128
  }'

Retour (testé) :

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

Exemple 6 : forme d’onde brute PCM

Pour les scénarios nécessitant un assemblage en temps réel dans le navigateur, ou un traitement ultérieur côté client (mixage, variation 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": "hi",
    "format": "pcm",
    "sample_rate": 16000
  }'

Retour (testé) :

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

L’extension du lien suit le format de la requête : mp3 donne .mp3, tandis que wav et pcm donnent .wav (conteneur WAV, PCM 16 bits).

Rappel asynchrone (`callback_url`)

La synthèse d’un texte long en une fois peut prendre de dix à plusieurs dizaines de secondes ; si la connexion est interrompue, une nouvelle tentative est nécessaire. Après avoir transmis callback_url dans le corps de la requête, l’interface retourne immédiatement {task_id, started_at}. Une fois le traitement réellement terminé en amont, le résultat complet est rappelé à cette URL sous la forme d’un POST JSON, avec le même task_id ainsi que le cost de niveau supérieur correspondant à la facturation finale de cette requête. La confirmation initiale de la tâche n’inclut pas cost, car la synthèse n’est pas encore terminée.

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "今天天气真好，我们一起出去散散步吧。",
    "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 une structure telle que :

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

Vous pouvez également utiliser l’API Fish Tasks pour récupérer activement le résultat selon task_id ; le response.cost de l’enregistrement à l’état final est identique au cost du rappel, voir cette documentation pour plus de détails.

Gestion des erreurs

400 token_mismatched : paramètres de requête manquants ou non valides (le plus fréquent est un text vide, ou une valeur autre que mp3/wav/pcm passée à format).
401 invalid_token : le token d’authentification n’existe pas ou n’est pas valide.
429 too_many_requests : la limite de débit du compte a été déclenchée.
500 api_error : erreur interne du serveur.

Exemple de réponse d’erreur :

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

Les erreurs de validation des paramètres indiquent le champ non valide dans le champ message, par exemple :

{
  "status": 400,
  "message": "[{\"type\":\"literal_error\",\"loc\":[\"format\"],\"msg\":\"Input should be 'pcm' or 'mp3'\",\"input\":\"wav\"}]"
}

Conclusion

Le coût minimal pour intégrer Fish TTS est de remplacer l’authentification par le token de cette plateforme dans le code existant appelant api.fish.audio/v1/tts, et d’inclure explicitement format: "mp3" dans le corps de la requête. Pour les textes longs, il est recommandé d’utiliser le rappel asynchrone callback_url ; pour découvrir les reference_id de voix clonées, utilisez Fish Model Query et Fish Model Get.

Démarrage

Chat IA

Image IA

Vidéo IA

Audio IA

Web & Données

CAPTCHA

Identité

Coding

Autres guides

Instructions d’intégration de l’API Fish TTS

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 : utiliser la voix clonée `reference_id`

Exemple 3 : clonage vocal instantané à usage unique (`references`)

Exemple 3 : ajuster la vitesse / le volume (`prosody`)

Exemple 5 : changer de modèle + contrôler le débit binaire

Exemple 6 : forme d’onde brute PCM

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 : utiliser la voix clonée reference_id

​Exemple 3 : clonage vocal instantané à usage unique (references)

​Exemple 3 : ajuster la vitesse / le volume (prosody)

​Exemple 5 : changer de modèle + contrôler le débit binaire

​Exemple 6 : forme d’onde brute PCM

​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 : utiliser la voix clonée `reference_id`

Exemple 3 : clonage vocal instantané à usage unique (`references`)

Exemple 3 : ajuster la vitesse / le volume (`prosody`)

Exemple 5 : changer de modèle + contrôler le débit binaire

Exemple 6 : forme d’onde brute PCM

Rappel asynchrone (`callback_url`)

Gestion des erreurs

Conclusion