Fish Model API 연동 안내

본 문서에서는 Fish Model API 연동 방법을 소개합니다. 해당 인터페이스는 Fish Audio 공식 OpenAPI와 완전히 호환되며, 다음을 포함합니다:

POST /fish/model：오디오 샘플을 기반으로 새로운 클론 음색(Voice Model) 생성
GET /fish/model：현재 계정 또는 전체 플랫폼에서 볼 수 있는 음색 목록을 페이징 조회

신청 절차

API를 사용하려면 먼저 Fish Model API 해당 페이지에서 서비스를 신청해야 하며, 페이지에 접속 후 「Acquire」 버튼을 클릭합니다. 로그인 또는 회원가입이 되어 있지 않은 경우 자동으로 로그인 페이지로 이동하여 회원가입 및 로그인을 안내하며, 로그인 후 자동으로 현재 페이지로 돌아옵니다. 최초 신청 시 무료 할당량이 제공되어 해당 API를 무료로 사용할 수 있습니다.

공식 API와의 차이점

인증 방식：Authorization: Bearer {token} 사용, 여기서 {token}은 본 플랫폼에서 발급받은 키입니다.
모델 생성 시 샘플 업로드：본 인터페이스는 현재 JSON 형식으로만 제출을 지원하며, voices 필드를 통해 오디오 샘플 URL을 전달합니다. Fish 공식은 multipart/msgpack을 통한 바이너리 직접 업로드를 지원하지만, 본 플랫폼은 아직 구현하지 않았으며 URL 방식이 약 80%의 일반적인 상황을 커버합니다.
응답 구조：POST /fish/model 및 GET /fish/model 모두 Fish 상위 플랫폼의 응답을 그대로 전달하며, 별도의 플랫폼 envelope 포장 없이 오류 시 {success:false, error:{code,message}, trace_id} 형태의 플랫폼 표준 구조를 사용합니다.

음색 생성 (POST /fish/model)

최소 생성 요청에는 title과 voices 두 필드가 필요합니다. voices는 오디오 샘플 URL 리스트이며, 각 파일은 30초 이상, 샘플링 레이트 16k 이상을 권장합니다.

curl -X POST 'https://api.xhuoapi.ai/v1/fish/model' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "title": "나의 클론 음색",
    "description": "팟캐스트 녹음을 사용해 클론한 음색",
    "voices": [
      "https://example.com/sample-voice.mp3"
    ],
    "cover_image": "https://example.com/cover.png",
    "visibility": "private"
  }'

성공 응답은 Fish 플랫폼의 ModelEntity 객체를 직접 반환합니다:

{
  "_id": "d7900c21663f485ab63ebdb7e5905036",
  "type": "tts",
  "title": "나의 클론 음색",
  "description": "팟캐스트 녹음을 사용해 클론한 음색",
  "cover_image": "https://example.com/cover.png",
  "train_mode": "fast",
  "state": "trained",
  "tags": [],
  "samples": [],
  "created_at": "2025-05-09T12:34:56.789Z",
  "updated_at": "2025-05-09T12:34:56.789Z",
  "languages": ["zh", "en"],
  "visibility": "private",
  "lock_visibility": false,
  "like_count": 0,
  "mark_count": 0,
  "shared_count": 0,
  "task_count": 0,
  "author": {
    "_id": "user_id",
    "nickname": "user_nickname",
    "avatar": "user_avatar"
  }
}

반환된 _id는 이후 POST /fish/tts 요청의 reference_id 필드 값으로 사용하여 해당 클론 음색으로 음성 합성에 활용할 수 있습니다.

음색 목록 조회 (GET /fish/model)

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 공식과 동일):

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

성공 응답 역시 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
}

과금 안내

본 인터페이스는 「음색 생성」 시에만 과금됩니다 (POST /fish/model 요청 본문에 voices 필드 포함 시). 「음색 목록 조회」 (GET /fish/model)는 과금되지 않습니다.

오류 처리

400 token_mismatched：잘못된 요청, 누락되었거나 유효하지 않은 파라미터 가능성 있음
400 api_not_implemented：잘못된 요청, 누락되었거나 유효하지 않은 파라미터 가능성 있음
401 invalid_token：권한 없음, 유효하지 않거나 누락된 인증 토큰
429 too_many_requests：요청 과다, 속도 제한 초과
500 api_error：서버 내부 오류 발생

오류 응답 예시

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

결론

Fish Model API는 Fish Audio 공식 OpenAPI의 ModelEntity 인터페이스와 완전 호환되어, 기존 클론 음색 관리 코드를 코드 변경 없이 그대로 마이그레이션할 수 있습니다. 생성된 음색 _id는 Fish TTS API의 reference_id 필드에 직접 전달하여 음성 합성에 활용할 수 있습니다.

Documentation Index

​신청 절차

​공식 API와의 차이점

​음색 생성 (POST /fish/model)

​음색 목록 조회 (GET /fish/model)

​과금 안내

​오류 처리

​오류 응답 예시

​결론