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 Query (GET /fish/model), que es completamente compatible con la OpenAPI oficial de Fish Audio, y se utiliza para la consulta paginada de la lista de tonos clonados visibles para la cuenta actual o en toda la plataforma.
Para crear tonos, consulte la Fish Model Create API. Para consultar detalles de un solo tono por _id, consulte la Fish Model Get API.

​
Proceso de solicitud

Para usar la API, primero debe solicitar el servicio correspondiente en la página de Fish Model API. Una vez en la página, haga clic en el botón “Acquire”. Si no ha iniciado sesión o registrado, será redirigido automáticamente a la página de inicio de sesión para registrarse e iniciar sesión. Después de iniciar sesión o registrarse, volverá automáticamente a la página actual. Al solicitar por primera vez, se otorga un crédito gratuito para usar esta 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.
  • Estructura de respuesta: se transmite directamente la respuesta paginada de Fish sin envolverla en un envelope de la plataforma; en caso de error se usa la estructura estándar de la plataforma {success:false, error:{code,message}, trace_id}.

​
Ejemplo de solicitud

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

Iguales a los de Fish oficial:
  • page_size: número de ítems por página, por defecto 10.
  • page_number: número de página, comenzando en 1.
  • title: búsqueda difusa por título.
  • tag: filtro por etiqueta.
  • self: si se pasa true, solo devuelve tonos creados por la cuenta actual.
  • author_id: filtro por creador.
  • language: filtro por idioma del tono.
  • title_language: filtro por idioma del título.

​
Ejemplo de respuesta

La respuesta exitosa transmite directamente la estructura paginada de la plataforma 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
}
El _id devuelto puede usarse como valor del campo reference_id en la Fish TTS API para sintetizar voz con ese tono clonado.

​
Información de facturación

Esta API no tiene costo: la consulta paginada de la lista de tonos es gratuita. Solo se cobra al crear un nuevo tono con POST /fish/model enviando el campo voices en el cuerpo de la solicitud.

​
Manejo de errores

  • 400 token_mismatched: falta o invalidez en los parámetros de la solicitud.
  • 400 api_not_implemented: método o parámetros no soportados actualmente.
  • 401 invalid_token: falta o invalidez de la autenticación.
  • 429 too_many_requests: se excedió el límite de tasa para la cuenta actual.
  • 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 Fish Model Query API ofrece una capacidad de búsqueda de tonos completamente compatible con la oficial de Fish Audio, permitiendo mantener una biblioteca propia de tonos clonados en esta plataforma. Combinada con la Fish Model Get API, permite obtener detalles completos de un solo tono por ID.