> ## 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 연동 설명

> Fish music generation 集成指南 - XHuoAPI

본 문서에서는 Fish Model Query API(`GET /fish/model`)의 연동 방법을 소개합니다. 해당 인터페이스는 [Fish Audio 공식 OpenAPI](https://docs.fish.audio/resources/api-reference/model)와 완전히 호환되며, 현재 계정 또는 전체 플랫폼에서 볼 수 있는 클론 음색 목록을 **페이징 조회**하는 데 사용됩니다.

> 음색 생성은 [Fish Model Create API](https://api.xhuoapi.ai/documents/62fdf4f1-6a05-4d92-bb15-1bf78b27a14a)를 참고하시고, `_id`로 단일 음색 상세 조회는 [Fish Model Get API](https://api.xhuoapi.ai/documents/dabdffe7-254b-5a3f-9eca-425d614d82b9)를 참고하세요.

## 신청 절차

API를 사용하려면 먼저 [Fish Model API](https://api.xhuoapi.ai/services/caf99abc-ddcf-4714-b2a5-862d9b469509) 해당 페이지에서 서비스를 신청해야 합니다. 페이지에 접속한 후 「Acquire」 버튼을 클릭하세요.

로그인 또는 회원가입이 되어 있지 않으면 자동으로 로그인 페이지로 이동하여 회원가입 및 로그인을 안내합니다. 로그인 및 회원가입 후 자동으로 현재 페이지로 돌아옵니다.

최초 신청 시 무료 할당량이 제공되어 해당 API를 무료로 사용할 수 있습니다.

## 공식 API와의 차이점

* **인증 방식**: `Authorization: Bearer {token}`을 사용하며, `{token}`은 본 플랫폼에서 발급받은 키입니다.
* **응답 구조**: Fish 상위 API의 페이징 응답을 그대로 전달하며, 플랫폼 별도의 envelope 포장 없이 반환합니다. 오류 발생 시 `{success:false, error:{code,message}, trace_id}` 형태의 플랫폼 표준 구조를 사용합니다.

## 요청 예시

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

## 조회 파라미터

Fish 공식 API와 동일합니다:

* `page_size`: 페이지당 항목 수, 기본값 10.
* `page_number`: 페이지 번호, 1부터 시작.
* `title`: 제목으로 모호 검색.
* `tag`: 태그로 필터링.
* `self`: `true` 전달 시 현재 계정이 생성한 음색만 반환.
* `author_id`: 생성자 기준 필터링.
* `language`: 음색 언어 필터링.
* `title_language`: 제목 언어 필터링.

## 응답 예시

성공 응답은 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
}
```

반환된 `_id`는 이후 [Fish TTS API](https://api.xhuoapi.ai/documents/77adcb84-d59f-5ef9-b8a0-8b35eb42a71d)의 `reference_id` 필드 값으로 사용되어 해당 클론 음색으로 음성 합성에 활용됩니다.

## 과금 안내

본 인터페이스는 과금되지 않습니다 — 음색 목록 페이징 조회는 무료이며, `POST /fish/model`에서 요청 본문에 `voices` 필드를 포함하여 새 음색을 생성할 때만 과금됩니다.

## 오류 처리

* `400 token_mismatched`: 요청 파라미터 누락 또는 유효하지 않음.
* `400 api_not_implemented`: 현재 지원하지 않는 요청 방식 또는 파라미터.
* `401 invalid_token`: 인증 정보 누락 또는 무효.
* `429 too_many_requests`: 현재 계정의 속도 제한 초과.
* `500 api_error`: 서버 내부 오류.

### 오류 응답 예시

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

## 결론

Fish Model Query API는 Fish Audio 공식 API와 완전히 호환되는 음색 검색 기능을 제공하며, 본 플랫폼에서 자신만의 클론 음색 라이브러리를 관리하는 데 사용할 수 있습니다. [Fish Model Get API](https://api.xhuoapi.ai/documents/dabdffe7-254b-5a3f-9eca-425d614d82b9)와 함께 사용하면 ID로 단일 음색의 상세 정보를 얻을 수 있습니다.