> ## 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 Get API 연동 안내

> Fish music generation 集成指南 - XHuoAPI

본 문서에서는 Fish Model Get API(`GET /fish/model/{id}`)의 연동 방법을 설명합니다. 이 API는 [Fish Audio 공식 OpenAPI](https://docs.fish.audio/resources/api-reference/model)와 완전 호환되며, **음색 ID로 단일 클론 음색의 전체 상세 정보를 조회**하는 데 사용됩니다.

> 음색 생성은 [Fish Model Create API](https://api.xhuoapi.ai/documents/62fdf4f1-6a05-4d92-bb15-1bf78b27a14a)를 참고하시고, 페이징 리스트 조회는 [Fish Model Query API](https://api.xhuoapi.ai/documents/5a9b3e03-2896-5606-a6b9-d9f4469f0e9d)를 참고하세요.

## 신청 절차

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

아직 로그인 또는 회원가입이 안 되어 있다면 자동으로 로그인 페이지로 이동하며, 회원가입 후 로그인하면 현재 페이지로 자동 복귀됩니다.

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

## 공식 API와의 차이점

* **인증 방식**: `Authorization: Bearer {token}` 헤더를 사용하며, `{token}`은 본 플랫폼에서 신청한 키입니다.
* **응답 구조**: Fish 상위의 ModelEntity 객체를 그대로 전달하며, 플랫폼의 envelope 포장 없이 반환합니다. 오류 발생 시에는 `{success:false, error:{code,message}, trace_id}`의 플랫폼 표준 구조를 따릅니다.
* **경로 파라미터**: `{id}`는 음색의 `_id`이며, [Fish Model Create API](https://api.xhuoapi.ai/documents/62fdf4f1-6a05-4d92-bb15-1bf78b27a14a) 호출 시 반환되거나, [Fish Model Query API](https://api.xhuoapi.ai/documents/5a9b3e03-2896-5606-a6b9-d9f4469f0e9d) 페이징 조회 시 얻을 수 있습니다.

## 요청 예제

```shell theme={null}
curl 'https://api.xhuoapi.ai/v1/fish/model/d7900c21663f485ab63ebdb7e5905036' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}'
```

URL 경로의 `{id}`만 구체적인 음색 ID로 교체하면 되며, 별도의 쿼리 파라미터 또는 요청 본문은 필요하지 않습니다.

## 응답 예제

성공 시 Fish 플랫폼의 ModelEntity 객체를 바로 전달합니다:

```json theme={null}
{
  "_id": "d7900c21663f485ab63ebdb7e5905036",
  "type": "tts",
  "title": "내 클론 음색",
  "description": "팟캐스트 녹음으로 클론한 음색",
  "cover_image": "https://example.com/cover.png",
  "train_mode": "fast",
  "state": "trained",
  "tags": [],
  "samples": [
    {
      "audio": "https://example.com/sample-voice.mp3",
      "text": ""
    }
  ],
  "created_at": "2025-05-09T12:34:56.789Z",
  "updated_at": "2025-05-09T12:34:56.789Z",
  "languages": ["zh", "en"],
  "visibility": "private",
  "lock_visibility": false,
  "default_text": "",
  "default_mode": "fast",
  "like_count": 0,
  "mark_count": 0,
  "shared_count": 0,
  "task_count": 0,
  "unliked": false,
  "liked": false,
  "marked": false,
  "author": {
    "_id": "00000000000000000000000000000000",
    "nickname": "",
    "avatar": ""
  }
}
```

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

## 과금 안내

이 API는 무료입니다 — ID로 음색 상세 정보를 조회하는 것은 무료이며, `POST /fish/model` 요청 시 `voices` 필드를 포함하여 새 음색을 생성하는 경우에만 과금됩니다.

## 오류 처리

* `400 token_mismatched`: 요청 파라미터 누락 또는 부적합
* `400 api_not_implemented`: 요청 방식 또는 파라미터 미지원
* `401 invalid_token`: 인증 정보 누락 또는 유효하지 않음
* `404 not_found`: 지정된 `_id`에 해당하는 음색이 존재하지 않거나 현재 계정에서 볼 수 없음
* `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 Get API는 Fish Audio 공식과 완벽히 호환되는 단일 음색 상세 조회 기능을 제공합니다. 음색 ID를 획득한 후, 본 API를 통해 ModelEntity 객체(샘플, 상태, 가시성, 통계 필드 등)를 가져오고, [Fish TTS API](https://api.xhuoapi.ai/documents/77adcb84-d59f-5ef9-b8a0-8b35eb42a71d)를 활용하여 엔드 투 엔드 클론 + 합성 과정을 수행할 수 있습니다.