> ## 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.

# Instrucciones para la integración de la API Fish Model Query

> Fish music generation 集成指南 - XHuoAPI

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](https://docs.fish.audio/resources/api-reference/model), 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](https://api.xhuoapi.ai/documents/62fdf4f1-6a05-4d92-bb15-1bf78b27a14a). Para consultar detalles de un solo tono por `_id`, consulte la [Fish Model Get API](https://api.xhuoapi.ai/documents/dabdffe7-254b-5a3f-9eca-425d614d82b9).

## Proceso de solicitud

Para usar la API, primero debe solicitar el servicio correspondiente en la página de [Fish Model API](https://api.xhuoapi.ai/services/caf99abc-ddcf-4714-b2a5-862d9b469509). 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

```shell theme={null}
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:

```json theme={null}
{
  "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](https://api.xhuoapi.ai/documents/77adcb84-d59f-5ef9-b8a0-8b35eb42a71d) 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

```json theme={null}
{
  "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](https://api.xhuoapi.ai/documents/dabdffe7-254b-5a3f-9eca-425d614d82b9), permite obtener detalles completos de un solo tono por ID.