Passer au contenu principal

Documentation Index

Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt

Use this file to discover all available pages before exploring further.

Cet article présente les instructions d’intégration de l’API Fish Model, une interface entièrement compatible avec l’OpenAPI officielle Fish Audio, comprenant :
  • POST /fish/model : création d’un nouveau modèle vocal cloné (Voice Model) à partir d’un échantillon audio.
  • GET /fish/model : requête paginée de la liste des voix visibles pour le compte actuel ou sur toute la plateforme.

​
Processus de demande

Pour utiliser l’API, il faut d’abord demander le service correspondant sur la page Fish Model API. Une fois sur la page, cliquez sur le bouton « Acquire ». Si vous n’êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion pour vous inscrire et vous connecter. Après connexion, vous serez automatiquement ramené à la page actuelle. Une allocation gratuite est offerte lors de la première demande, permettant une utilisation gratuite de l’API.

​
Différences avec l’API officielle

  • Méthode d’authentification : utilisation de Authorization: Bearer {token}, où {token} est la clé obtenue sur cette plateforme.
  • Téléversement des échantillons lors de la création du modèle : cette interface supporte actuellement uniquement la soumission en JSON via le champ voices contenant les URL des échantillons audio. L’API officielle Fish supporte le multipart/msgpack pour un upload direct des données binaires, non encore implémenté ici. La méthode par URL couvre environ 80 % des cas d’usage courants.
  • Structure de la réponse : les réponses de POST /fish/model et GET /fish/model sont transmises telles quelles depuis Fish, sans enveloppe supplémentaire spécifique à la plateforme. En cas d’erreur, la structure standard de la plateforme {success:false, error:{code,message}, trace_id} est utilisée.

​
Création d’une voix (POST /fish/model)

La requête minimale nécessite les champs title et voices. voices est une liste d’URL d’échantillons audio, recommandés d’une durée supérieure à 30 secondes et d’un taux d’échantillonnage de 16 kHz ou plus. 
curl -X POST 'https://api.xhuoapi.ai/v1/fish/model' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "title": "我的克隆音色",
    "description": "用一段播客录音克隆的音色",
    "voices": [
      "https://example.com/sample-voice.mp3"
    ],
    "cover_image": "https://example.com/cover.png",
    "visibility": "private"
  }'
La réponse réussie retourne directement l’objet ModelEntity de la plateforme Fish : 
{
  "_id": "d7900c21663f485ab63ebdb7e5905036",
  "type": "tts",
  "title": "我的克隆音色",
  "description": "用一段播客录音克隆的音色",
  "cover_image": "https://example.com/cover.png",
  "train_mode": "fast",
  "state": "trained",
  "tags": [],
  "samples": [],
  "created_at": "2025-05-09T12:34:56.789Z",
  "updated_at": "2025-05-09T12:34:56.789Z",
  "languages": ["zh", "en"],
  "visibility": "private",
  "lock_visibility": false,
  "like_count": 0,
  "mark_count": 0,
  "shared_count": 0,
  "task_count": 0,
  "author": {
    "_id": "user_id",
    "nickname": "user_nickname",
    "avatar": "user_avatar"
  }
}
L’_id retourné peut être utilisé comme valeur du champ reference_id dans les requêtes POST /fish/tts pour la synthèse vocale avec ce modèle cloné.

​
Consultation de la liste des voix (GET /fish/model)

curl -G 'https://api.xhuoapi.ai/v1/fish/model' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'page_size=10' \
  --data-urlencode 'page_number=1' \
  --data-urlencode 'self=true'
Paramètres de requête disponibles (identiques à l’API officielle Fish) :
  • page_size : nombre d’éléments par page, par défaut 10.
  • page_number : numéro de page, à partir de 1.
  • title : recherche floue par titre.
  • tag : filtrage par étiquette.
  • self : si true, retourne uniquement les voix créées par le compte actuel.
  • author_id : filtrage par créateur.
  • language : filtrage par langue de la voix.
  • title_language : filtrage par langue du titre.
La réponse réussie transmet également la structure paginée de la plateforme Fish : 
{
  "items": [
    {
      "_id": "d7900c21663f485ab63ebdb7e5905036",
      "title": "我的克隆音色",
      "description": "用一段播客录音克隆的音色",
      "cover_image": "https://example.com/cover.png",
      "type": "tts",
      "state": "trained",
      "tags": [],
      "languages": ["zh", "en"],
      "visibility": "private",
      "created_at": "2025-05-09T12:34:56.789Z",
      "updated_at": "2025-05-09T12:34:56.789Z"
    }
  ],
  "total": 1
}

​
Tarification

Cette interface facture uniquement la création de voix (POST /fish/model avec le champ voices dans le corps de la requête). La consultation de la liste des voix (GET /fish/model) est gratuite.

​
Gestion des erreurs

  • 400 token_mismatched : requête incorrecte, paramètres manquants ou invalides.
  • 400 api_not_implemented : requête incorrecte, paramètres manquants ou invalides.
  • 401 invalid_token : non autorisé, jeton d’authentification invalide ou manquant.
  • 429 too_many_requests : trop de requêtes, limite de fréquence dépassé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

L’API Fish Model est entièrement compatible avec l’interface ModelEntity de l’OpenAPI officielle Fish Audio, permettant une migration sans modification du code existant de gestion des modèles vocaux clonés. L’_id des voix créées peut être directement utilisé dans le champ reference_id de l’API Fish TTS pour la synthèse vocale.