Guide d'intégration de l'API Fish Model Query

Cette interface est basée sur l’API officielle Fish Audio Model et est utilisée pour récupérer de manière paginée la bibliothèque publique de voix Fish ou les voix clonées sous le compte actuel. L’adresse est GET https://api.acedata.cloud/fish/model.

Pour créer une voix, veuillez consulter Fish Model Create API ; pour interroger les détails d’une seule voix par _id, veuillez consulter Fish Model Get API.

Processus de demande

Pour utiliser l’API Fish Model, allez d’abord dans la console Ace Data Cloud pour obtenir votre API Token et le conserver pour une utilisation ultérieure.

Si vous n’êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion qui vous invitera à vous inscrire et à vous connecter ; une fois terminé, vous reviendrez automatiquement à la page actuelle. Un seul API Token permet d’appeler tous les services de la plateforme, sans devoir en demander un séparément pour chaque service. La première demande offre un quota gratuit, permettant une expérience gratuite ; lorsque le quota est insuffisant, vous pouvez recharger le solde universel dans la console.

📘 Documentation complète : Fish Model API →

Paramètres de requête

Paramètre	Type	Par défaut	Description
`page_size`	integer	10	Nombre d’éléments par page.
`page_number`	integer	1	Numéro de page commençant à 1.
`title`	string	—	Recherche floue par titre.
`tag`	string	—	Filtrage par une seule étiquette.
`self`	boolean	—	Lorsque `true`, retourne uniquement les voix créées et enregistrées via cette plateforme par le compte appelant actuel.
`author_id`	string	—	Filtrage par ID de l’auteur de la voix.
`language`	string	—	Filtrage par langue de la voix, par exemple `en`, `zh`, `es`.
`title_language`	string	—	Filtrage par langue du titre dans la bibliothèque publique de voix.
`sort_by`	string	—	Champ de tri ; lorsque `self=true`, prend en charge `created_at`, `task_count`.

Les noms des paramètres sont entièrement identiques à ceux de l’amont GET https://api.fish.audio/model, voir la documentation officielle Fish.

Exemple 1 : pagination par défaut (selon `page_size`)

curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'page_size=2'

Retour (testé en conditions réelles, le total de la bibliothèque publique est d’environ 1,8 million d’éléments ; certains champs longs sont omis dans l’exemple ci-dessous pour la lisibilité) :

{
  "total": 1829200,
  "items": [
    {
      "_id": "8d2c17a9b26d4d83888ea67a1ee565b2",
      "type": "tts",
      "title": "Valentino Narración Biblica Fer",
      "description": "A mature and authoritative male voice with a calm, spiritual tone...",
      "cover_image": "coverimage/8d2c17a9b26d4d83888ea67a1ee565b2",
      "train_mode": "fast",
      "state": "trained",
      "tags": ["male", "old", "narration", "calm", "Spanish"],
      "samples": [
        {
          "title": "Default Sample",
          "text": "Hermanos míos, recordemos las palabras del Señor...",
          "task_id": "59ce7df6935c42249759327ddf70f37b",
          "audio": "https://platform.r2.fish.audio/task/59ce7df6935c42249759327ddf70f37b.mp3"
        }
      ],
      "languages": ["es"],
      "visibility": "public",
      "like_count": 4344,
      "task_count": 708461,
      "author": {
        "_id": "1b82fb6a329c4462b67aa9ee0a42046f",
        "nickname": "Fernando Caicedo"
      }
    },
    {
      "_id": "90e65eaaf50e4470b8e6d43ee6afd7d5",
      "type": "tts",
      "title": "Super Smash Bros. 4/Ultimate Announcer",
      "tags": ["male", "old", "announcer", "gaming", "cinematic"],
      "languages": ["en"],
      "visibility": "public"
    }
  ],
  "has_more": null
}

Exemple 2 : recherche floue par titre (`title`)

curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'title=narration' \
  --data-urlencode 'page_size=2'

Retour (testé en conditions réelles) :

{
  "total": 161,
  "items": [
    {
      "_id": "fb8fe4a94658429d9be70efd4eec35a2",
      "type": "tts",
      "title": "Miles Morales ( Narration Paw )",
      "tags": ["male", "middle-aged", "entertainment", "storytelling", "Children's Content"],
      "languages": ["en"],
      "visibility": "public",
      "task_count": 770
    },
    {
      "_id": "76b55591c758444cb95253708696dfad",
      "type": "tts",
      "title": "Joe NARRATION",
      "tags": ["male", "middle-aged", "narration", "deep", "raspy"],
      "languages": ["en"],
      "visibility": "public"
    }
  ],
  "has_more": null
}

Notez que title est une « correspondance floue globale », qui correspondra simultanément à toutes les voix de la bibliothèque publique Fish (et pas uniquement aux vôtres).

Exemple 3 : lister uniquement les voix créées par soi-même (`self=true`)

curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'self=true' \
  --data-urlencode 'page_size=5'

Exemple de retour :

{
  "total": 1,
  "items": [
    {
      "_id": "e5c6db52c3ed417f9cb2e5a33fb04667",
      "type": "tts",
      "title": "copilot-smoke-test",
      "description": "smoke test from api.acedata.cloud",
      "state": "trained",
      "languages": ["zh"],
      "visibility": "public",
      "samples": [
        {
          "title": "Default Sample",
          "text": "师父，[语气坚定]我真的受够了这山上的清冷日子！...",
          "task_id": "6a1bf398dfae49dca0e23159214342a0",
          "audio": "https://platform.r2.fish.audio/task/6a1bf398dfae49dca0e23159214342a0.mp3"
        }
      ],
      "created_at": "2026-05-10T03:52:55.601000Z",
      "author": {
        "_id": "780f2b2f862d41a08c0507bbbda77eb6",
        "nickname": "Penny Conrad"
      }
    }
  ],
  "has_more": false
}

self=true répertorie les voix créées et enregistrées via cette plateforme selon le compte appelant réel ; les voix créées par le même compte avec différents API Token seront également répertoriées ensemble. Les résultats sont paginés par ordre décroissant de date de création, et author_id peut filtrer davantage l’ID de l’auteur de ces voix. Ce paramètre filtre uniquement la liste, les voix restent publiquement disponibles. self=true ne prend pas en charge title_language ; si vous devez rechercher par langue du titre, veuillez interroger la bibliothèque publique de voix.

Exemple 4 : filtrer par langue + étiquette

curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'language=zh' \
  --data-urlencode 'tag=narration' \
  --data-urlencode 'page_size=5'

L’amont renvoie également des résultats pour les tag absents du dictionnaire d’étiquettes, mais la correspondance est relativement large ; si le nombre de résultats est de 0, il est recommandé d’utiliser une correspondance floue avec title.

Champs de réponse

Chaque élément dans items[] est un objet ModelEntity complet, champs couramment utilisés :

Champ	Type	Description
`_id`	string	ID de la voix, utilisé comme valeur de `reference_id` dans `/fish/tts`.
`type`	string	Type de modèle, généralement `tts`.
`title`	string	Nom de la voix.
`description`	string	Description de la voix.
`state`	string	État de l’entraînement : `trained` indique qu’elle est disponible.
`tags`	string[]	Étiquettes de la bibliothèque publique.
`languages`	string[]	Langues dans lesquelles la voix excelle.
`visibility`	string	`public` ou `private`.
`samples`	object[]	Échantillons prédéfinis (incluant un lien direct `audio`).
`like_count`	integer	Nombre de mentions J’aime dans la bibliothèque publique.
`task_count`	integer	Nombre de synthèses historiques.
`author`	object	Informations sur l’auteur de la voix : `_id` / `nickname` / `avatar`.
`total`（niveau supérieur）	integer	Nombre total d’éléments répondant aux conditions.
`has_more`	boolean?	Valeur booléenne lorsque `self=true` ; les requêtes de la bibliothèque publique de voix peuvent être `null`.

Informations de facturation

Cette interface n’est pas facturée — la requête paginée de la liste des voix est une opération gratuite. La création de voix (Fish Model Create) est également gratuite, les frais sont générés uniquement selon l’utilisation lors de l’appel à Fish TTS pour synthétiser de la parole.

Gestion des erreurs

400 token_mismatched : paramètres de requête manquants ou non valides.
401 invalid_token : le token d’authentification n’existe pas ou n’est pas valide.
429 too_many_requests : limite de débit du compte 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"
}

Conclusion

Pour sélectionner une voix depuis la bibliothèque publique Fish afin de l’utiliser comme reference_id de /fish/tts, utilisez d’abord cette interface avec title / tag / language pour effectuer une recherche, localisez le _id cible, puis utilisez Fish Model Get pour obtenir des échantillons et les écouter. Pour répertorier les voix que vous avez créées, il suffit de transmettre self=true.

Démarrage

Chat IA

Image IA

Vidéo IA

Audio IA

Web & Données

CAPTCHA

Identité

Coding

Autres guides

Guide d'intégration de l'API Fish Model Query

Processus de demande

Paramètres de requête

Exemple 2 : recherche floue par titre (`title`)

Exemple 3 : lister uniquement les voix créées par soi-même (`self=true`)

Exemple 4 : filtrer par langue + étiquette

Champs de réponse

Informations de facturation

Gestion des erreurs

Conclusion

​Processus de demande

​Paramètres de requête

​Exemple 1 : pagination par défaut (selon page_size)

​Exemple 2 : recherche floue par titre (title)

​Exemple 3 : lister uniquement les voix créées par soi-même (self=true)

​Exemple 4 : filtrer par langue + étiquette

​Champs de réponse

​Informations de facturation

​Gestion des erreurs

​Conclusion

Processus de demande

Paramètres de requête

Exemple 1 : pagination par défaut (selon `page_size`)

Exemple 2 : recherche floue par titre (`title`)

Exemple 3 : lister uniquement les voix créées par soi-même (`self=true`)

Exemple 4 : filtrer par langue + étiquette

Champs de réponse

Informations de facturation

Gestion des erreurs

Conclusion