Fish 모델 쿼리 API 연동 설명

본 인터페이스는 Fish Audio 공식 모델 API를 기반으로 하여 Fish 공용 음색 라이브러리 또는 현재 계정의 클론 음색을 페이지별로 검색하는 데 사용됩니다. 주소는 GET https://api.acedata.cloud/fish/model입니다.

음색 생성은 Fish 모델 생성 API를 참조하십시오. _id로 단일 음색 세부정보를 조회하려면 Fish 모델 조회 API를 참조하십시오.

신청 절차

Fish 모델 API를 사용하려면 먼저 Ace Data Cloud 콘솔에서 API 토큰을 받아야 하며, 이를 보관하십시오.

로그인 또는 등록이 되어 있지 않은 경우 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인을 초대합니다. 완료 후 현재 페이지로 자동으로 돌아옵니다. 하나의 API 토큰으로 플랫폼의 모든 서비스를 호출할 수 있으며, 각 서비스에 대해 별도로 신청할 필요가 없습니다. 최초 신청 시 무료 할당량이 제공되어 무료로 체험할 수 있습니다. 할당량이 부족할 경우 콘솔에서 일반 잔액을 충전할 수 있습니다.

📘 전체 문서: Fish 모델 API →

쿼리 매개변수

매개변수	유형	기본값	설명
`page_size`	integer	10	페이지당 항목 수.
`page_number`	integer	1	1부터 시작하는 페이지 번호.
`title`	string	—	제목으로 모호하게 검색.
`tag`	string	—	단일 태그로 필터링.
`self`	boolean	—	`true`일 때 현재 계정에서 생성한 음색만 반환, 추가 조건 필요 없음.
`author_id`	string	—	상위 사용자 `_id`로 필터링.
`language`	string	—	음색 언어로 필터링, 예: `en`, `zh`, `es`.
`title_language`	string	—	제목 언어로 필터링.
`sort_by`	string	—	정렬 필드, 상위와 일치, 예: `created_at`, `task_count`.

매개변수 명칭은 상위 GET https://api.fish.audio/model와 완전히 일치하며, 자세한 내용은 Fish 공식 문서를 참조하십시오.

예시 1: 기본 페이지네이션 ( `page_size` 기준)

curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'page_size=2'

반환 (실제 측정, 공용 라이브러리 총량 약 180만 건; 가독성을 위해 아래 예시는 일부 긴 필드를 생략함):

{
  "total": 1829200,
  "items": [
    {
      "_id": "8d2c17a9b26d4d83888ea67a1ee565b2",
      "type": "tts",
      "title": "Valentino Narración Biblica Fer",
      "description": "차분하고 영적인 톤을 가진 성숙하고 권위 있는 남성 목소리...",
      "cover_image": "coverimage/8d2c17a9b26d4d83888ea67a1ee565b2",
      "train_mode": "fast",
      "state": "trained",
      "tags": ["male", "old", "narration", "calm", "Spanish"],
      "samples": [
        {
          "title": "기본 샘플",
          "text": "Hermanos míos, recordemos las palabras del Señor...",
          "task_id": "59ce7df6935c42249759327ddf70f37b",
          "audio": "https://platform.r2.fish.audio/task/59ce7df6935c42249759327ddf70f37b.mp3"
        }
      ],
      "languages": ["es"],
      "visibility": "public",
      "like_count": 4344,
      "task_count": 708461,
      "author": {
        "_id": "1b82fb6a329c4462b67aa9ee0a42046f",
        "nickname": "Fernando Caicedo"
      }
    },
    {
      "_id": "90e65eaaf50e4470b8e6d43ee6afd7d5",
      "type": "tts",
      "title": "Super Smash Bros. 4/Ultimate Announcer",
      "tags": ["male", "old", "announcer", "gaming", "cinematic"],
      "languages": ["en"],
      "visibility": "public"
    }
  ],
  "has_more": null
}

예시 2: 제목으로 모호하게 검색 ( `title` )

curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'title=narration' \
  --data-urlencode 'page_size=2'

반환 (실제 측정):

{
  "total": 161,
  "items": [
    {
      "_id": "fb8fe4a94658429d9be70efd4eec35a2",
      "type": "tts",
      "title": "Miles Morales ( Narration Paw )",
      "tags": ["male", "middle-aged", "entertainment", "storytelling", "Children's Content"],
      "languages": ["en"],
      "visibility": "public",
      "task_count": 770
    },
    {
      "_id": "76b55591c758444cb95253708696dfad",
      "type": "tts",
      "title": "Joe NARRATION",
      "tags": ["male", "middle-aged", "narration", "deep", "raspy"],
      "languages": ["en"],
      "visibility": "public"
    }
  ],
  "has_more": null
}

주의 title은 「전역 모호 일치」로, Fish 공용 라이브러리의 모든 음색(자신의 것뿐만 아니라)을 포함합니다.

예시 3: 자신이 생성한 음색만 나열 ( `self=true` )

curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'self=true' \
  --data-urlencode 'page_size=5'

반환 (실제 측정, 현재 계정에는 1개의 음색만 존재):

{
  "total": 1,
  "items": [
    {
      "_id": "e5c6db52c3ed417f9cb2e5a33fb04667",
      "type": "tts",
      "title": "copilot-smoke-test",
      "description": "api.acedata.cloud에서의 스모크 테스트",
      "state": "trained",
      "languages": ["zh"],
      "visibility": "public",
      "samples": [
        {
          "title": "기본 샘플",
          "text": "师父，[语气坚定]我真的受够了这山上的清冷日子！...",
          "task_id": "6a1bf398dfae49dca0e23159214342a0",
          "audio": "https://platform.r2.fish.audio/task/6a1bf398dfae49dca0e23159214342a0.mp3"
        }
      ],
      "created_at": "2026-05-10T03:52:55.601000Z",
      "author": {
        "_id": "780f2b2f862d41a08c0507bbbda77eb6",
        "nickname": "Penny Conrad"
      }
    }
  ],
  "has_more": null
}

self=true는 필터링에서 author_id == 현재 계정의 상위 ID로 제한하는 것과 같으며, 일반적으로 사용되는 「내 음색 목록」 진입점입니다.

예시 4: 언어 + 태그로 필터링

curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'language=zh' \
  --data-urlencode 'tag=narration' \
  --data-urlencode 'page_size=5'

상류는 태그 사전에 없는 tag에 대해서도 결과를 반환하지만, 매칭이 상대적으로 느슨합니다; 만약 적중 수가 0이라면 title 모호 매칭으로 변경하는 것이 좋습니다.

응답 필드

items[]의 각 항목은 완전한 ModelEntity 객체이며, 자주 사용되는 필드는 다음과 같습니다:

필드	유형	설명
`_id`	string	음색 ID, `/fish/tts`에서 `reference_id`의 값으로 사용됩니다.
`type`	string	모델 유형, 일반적으로 `tts`입니다.
`title`	string	음색 이름입니다.
`description`	string	음색 설명입니다.
`state`	string	훈련 상태: `trained`는 사용 가능함을 나타냅니다.
`tags`	string[]	공용 라이브러리 태그입니다.
`languages`	string[]	음색이 잘하는 언어입니다.
`visibility`	string	`public` 또는 `private`입니다.
`samples`	object[]	미리 설정된 샘플(포함 `audio` 직링크)입니다.
`like_count`	integer	공용 라이브러리 좋아요 수입니다.
`task_count`	integer	역사적 합성 횟수입니다.
`author`	object	상류 저자 정보: `_id` / `nickname` / `avatar`입니다.
`total`（최상위）	integer	조건을 만족하는 총 항목 수입니다.
`has_more`	boolean?	상류 페이지 지시, `null`일 수 있습니다. 총 페이지 수는 `total / page_size`로 계산하는 것이 좋습니다.

요금 설명

이 인터페이스는 요금이 부과되지 않습니다——음색 목록의 페이지 쿼리는 무료 작업입니다. 음색 생성(Fish Model Create)도 무료이며, 비용은 Fish TTS로 음성을 합성할 때 사용량에 따라 발생합니다.

오류 처리

400 token_mismatched：요청 매개변수가 누락되었거나 유효하지 않습니다.
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 공용 라이브러리에서 음색을 선택하여 /fish/tts의 reference_id에 제공하려면, 먼저 이 인터페이스를 사용하여 title / tag / language로 검색하여 목표 _id를 찾고, 그 다음 Fish Model Get으로 샘플을 들어보세요. 자신이 생성한 음색을 나열하려면 self=true를 전달하면 됩니다.

시작하기

AI 채팅

AI 이미지

AI 비디오

AI 오디오

웹 & 데이터

CAPTCHA

신원

프록시

고급

Coding

Fish 모델 쿼리 API 연동 설명

신청 절차

쿼리 매개변수

예시 1: 기본 페이지네이션 ( `page_size` 기준)

예시 2: 제목으로 모호하게 검색 ( `title` )

예시 3: 자신이 생성한 음색만 나열 ( `self=true` )

예시 4: 언어 + 태그로 필터링

응답 필드

요금 설명

오류 처리

결론

​신청 절차

​쿼리 매개변수

​예시 1: 기본 페이지네이션 ( page_size 기준)

​예시 2: 제목으로 모호하게 검색 ( title )

​예시 3: 자신이 생성한 음색만 나열 ( self=true )

​예시 4: 언어 + 태그로 필터링

​응답 필드

​요금 설명

​오류 처리

​결론

신청 절차

쿼리 매개변수

예시 1: 기본 페이지네이션 ( `page_size` 기준)

예시 2: 제목으로 모호하게 검색 ( `title` )

예시 3: 자신이 생성한 음색만 나열 ( `self=true` )

예시 4: 언어 + 태그로 필터링

응답 필드

요금 설명

오류 처리

결론