Saltar al contenido 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.

Este documento presenta las instrucciones para la integración de la API Fish Model, la cual es completamente compatible con la OpenAPI oficial de Fish Audio, incluyendo:
  • POST /fish/model: Crear un nuevo modelo de voz clonado basado en muestras de audio.
  • GET /fish/model: Consultar paginadamente la lista de modelos de voz visibles para la cuenta actual o en toda la plataforma.

​
Proceso de solicitud

Para usar la API, primero debe solicitar el servicio correspondiente en la página de Fish Model API. Al ingresar, haga clic en el botón «Acquire». Si aún no ha iniciado sesión o registrado, será redirigido automáticamente a la página de inicio de sesión para registrarse o iniciar sesión. Después de hacerlo, volverá automáticamente a la página actual. Al solicitar por primera vez, se otorgará un crédito gratuito para usar la API sin costo.

​
Diferencias con la API oficial

  • Método de autenticación: Se usa Authorization: Bearer {token}, donde {token} es la clave obtenida en esta plataforma.
  • Carga de muestras al crear el modelo: Actualmente, esta API solo admite enviar las muestras en formato JSON mediante el campo voices con URLs de las muestras de audio. La API oficial de Fish admite multipart/msgpack para subir binarios directamente, pero esta plataforma aún no lo implementa. El método por URL cubre aproximadamente el 80% de los casos comunes.
  • Estructura de respuesta: Tanto POST /fish/model como GET /fish/model transmiten directamente la respuesta original de Fish sin envolverla en un envelope adicional. En caso de error, se usa la estructura estándar de la plataforma {success:false, error:{code,message}, trace_id}.

​
Crear modelo de voz (POST /fish/model)

La solicitud mínima para crear un modelo requiere los campos title y voices. voices es una lista de URLs de muestras de audio; se recomienda que cada archivo tenga más de 30 segundos y una frecuencia de muestreo de 16 kHz o superior. 
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": "Mi voz clonada",
    "description": "Modelo clonado a partir de una grabación de podcast",
    "voices": [
      "https://example.com/sample-voice.mp3"
    ],
    "cover_image": "https://example.com/cover.png",
    "visibility": "private"
  }'
La respuesta exitosa devuelve directamente el objeto ModelEntity de la plataforma Fish: 
{
  "_id": "d7900c21663f485ab63ebdb7e5905036",
  "type": "tts",
  "title": "Mi voz clonada",
  "description": "Modelo clonado a partir de una grabación de podcast",
  "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"
  }
}
El _id retornado puede usarse como valor para el campo reference_id en la llamada POST /fish/tts para realizar síntesis de voz con este modelo clonado.

​
Consultar lista de modelos de voz (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'
Parámetros de consulta disponibles (idénticos a la API oficial de Fish):
  • page_size: Número de elementos por página, por defecto 10.
  • page_number: Número de página, comenzando en 1.
  • title: Búsqueda difusa por título.
  • tag: Filtrado por etiqueta.
  • self: Si se pasa true, solo devuelve los modelos creados por la cuenta actual.
  • author_id: Filtrado por creador.
  • language: Filtrado por idioma del modelo de voz.
  • title_language: Filtrado por idioma del título.
La respuesta exitosa también transmite directamente la estructura paginada de la plataforma Fish: 
{
  "items": [
    {
      "_id": "d7900c21663f485ab63ebdb7e5905036",
      "title": "Mi voz clonada",
      "description": "Modelo clonado a partir de una grabación de podcast",
      "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
}

​
Información de facturación

Esta API solo cobra por la creación de modelos de voz (POST /fish/model con el campo voices en el cuerpo). La consulta de la lista de modelos (GET /fish/model) es gratuita.

​
Manejo de errores

  • 400 token_mismatched: Solicitud incorrecta, posiblemente por parámetros faltantes o inválidos.
  • 400 api_not_implemented: Solicitud incorrecta, posiblemente por parámetros faltantes o inválidos.
  • 401 invalid_token: No autorizado, token de autorización inválido o ausente.
  • 429 too_many_requests: Demasiadas solicitudes, se ha excedido el límite de tasa.
  • 500 api_error: Error interno del servidor.

​
Ejemplo de respuesta de error

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

​
Conclusión

La API Fish Model es completamente compatible con la interfaz ModelEntity de la OpenAPI oficial de Fish Audio, permitiendo migrar el código existente de gestión de modelos clonados sin cambios. El _id del modelo creado puede usarse directamente en el campo reference_id de la API Fish TTS para síntesis de voz.