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

# Fish Model Query API Integration Guide

> Fish music generation 集成指南 - XHuoAPI

This document introduces the Fish Model Query API (`GET /fish/model`) integration instructions. This interface is fully compatible with the [Fish Audio Official OpenAPI](https://docs.fish.audio/resources/api-reference/model), and is used for **paginated querying** of clone voice models visible to the current account or across the entire platform.

> For creating voices, please refer to [Fish Model Create API](https://api.xhuoapi.ai/documents/62fdf4f1-6a05-4d92-bb15-1bf78b27a14a). To query details of a single voice model by `_id`, see [Fish Model Get API](https://api.xhuoapi.ai/documents/dabdffe7-254b-5a3f-9eca-425d614d82b9).

## Application Process

To use the API, you need to first apply for the corresponding service on the [Fish Model API](https://api.xhuoapi.ai/services/caf99abc-ddcf-4714-b2a5-862d9b469509) page. After entering the page, click the "Acquire" button.

If you are not logged in or registered, you will be automatically redirected to the login page to register and log in. After login or registration, you will be redirected back to the current page.

During your first application, a free quota will be granted, allowing you to use this API free of charge.

## Differences from the Official API

* **Authentication Method**: Uses `Authorization: Bearer {token}`, where `{token}` is the key applied for on this platform.
* **Response Structure**: Directly passes through Fish upstream's paginated response without platform envelope wrapping; in case of errors, uses the platform's standard structure `{success:false, error:{code,message}, trace_id}`.

## Request Example

```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'
```

## Query Parameters

Consistent with Fish official:

* `page_size`: Number of items per page, default 10.
* `page_number`: Page number, starting from 1.
* `title`: Fuzzy search by title.
* `tag`: Filter by tags.
* `self`: When set to `true`, only returns voices created by the current account.
* `author_id`: Filter by creator.
* `language`: Filter by voice language.
* `title_language`: Filter by title language.

## Response Example

Successful responses directly pass through Fish platform's paginated structure:

```json theme={null}
{
  "items": [
    {
      "_id": "d7900c21663f485ab63ebdb7e5905036",
      "title": "My Clone Voice",
      "description": "A voice cloned from a podcast recording",
      "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
}
```

The returned `_id` can be used as the `reference_id` in the [Fish TTS API](https://api.xhuoapi.ai/documents/77adcb84-d59f-5ef9-b8a0-8b35eb42a71d) for speech synthesis with this clone voice.

## Billing Information

This API is free of charge — paginated querying of voice models is free. Only when creating a new voice with `POST /fish/model` and including the `voices` field in the request body is billing applicable.

## Error Handling

* `400 token_mismatched`: Missing or invalid request parameters.
* `400 api_not_implemented`: Unsupported request method or parameters.
* `401 invalid_token`: Missing or invalid authentication information.
* `429 too_many_requests`: Exceeded the rate limit for the current account.
* `500 api_error`: Internal server error.

### Error Response Example

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

## Conclusion

The Fish Model Query API provides voice model retrieval capabilities fully compatible with Fish Audio's official API, enabling you to maintain your own clone voice library on this platform. Coupled with [Fish Model Get API](https://api.xhuoapi.ai/documents/dabdffe7-254b-5a3f-9eca-425d614d82b9), you can retrieve complete details of individual voice models by ID.