Instrukcja integracji API zapytań modelu Fish

Ten interfejs opiera się na oficjalnym API modeli Fish Audio i służy do stronicowanego wyszukiwania publicznej biblioteki głosów Fish lub sklonowanych głosów należących do bieżącego konta. Adres to GET https://api.acedata.cloud/fish/model.

Aby utworzyć głos, zapoznaj się z Fish Model Create API; aby wyszukać szczegóły pojedynczego głosu według _id, zapoznaj się z Fish Model Get API.

Proces aplikowania

Aby korzystać z Fish Model API, najpierw przejdź do konsoli Ace Data Cloud, aby uzyskać swój API Token i zachować go na później.

Jeśli nie jesteś jeszcze zalogowany ani zarejestrowany, zostaniesz automatycznie przekierowany na stronę logowania, która zaprosi Cię do rejestracji i logowania; po ukończeniu automatycznie wrócisz na bieżącą stronę. Jeden API Token może wywoływać wszystkie usługi platformy, nie ma potrzeby osobnego aplikowania dla każdej usługi. Przy pierwszym uzyskaniu przyznawany jest darmowy limit, umożliwiający bezpłatne testowanie; gdy limit jest niewystarczający, możesz doładować wspólne saldo w konsoli.

📘 Pełna dokumentacja: Fish Model API →

Parametry zapytania

Parametr	Typ	Domyślnie	Opis
`page_size`	integer	10	Liczba rekordów na stronę.
`page_number`	integer	1	Numer strony zaczynający się od 1.
`title`	string	—	Wyszukiwanie rozmyte według tytułu.
`tag`	string	—	Filtrowanie według pojedynczego tagu.
`self`	boolean	—	Gdy `true`, zwraca tylko głosy utworzone i zapisane przez bieżące konto wywołujące za pośrednictwem tej platformy.
`author_id`	string	—	Filtrowanie według ID autora głosu.
`language`	string	—	Filtrowanie według języka głosu, np. `en`, `zh`, `es`.
`title_language`	string	—	Filtrowanie według języka tytułu w publicznej bibliotece głosów.
`sort_by`	string	—	Pole sortowania; gdy `self=true`, obsługiwane są `created_at`, `task_count`.

Nazewnictwo parametrów jest całkowicie zgodne z nadrzędnym GET https://api.fish.audio/model; szczegóły znajdziesz w oficjalnej dokumentacji Fish.

Przykład 1: domyślne stronicowanie (według `page_size`)

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

Odpowiedź (testowana w praktyce, łączna liczba w publicznej bibliotece wynosi około 1,8 miliona; dla czytelności w poniższym przykładzie pominięto niektóre długie pola):

{
  "total": 1829200,
  "items": [
    {
      "_id": "8d2c17a9b26d4d83888ea67a1ee565b2",
      "type": "tts",
      "title": "Valentino Narración Biblica Fer",
      "description": "A mature and authoritative male voice with a calm, spiritual tone...",
      "cover_image": "coverimage/8d2c17a9b26d4d83888ea67a1ee565b2",
      "train_mode": "fast",
      "state": "trained",
      "tags": ["male", "old", "narration", "calm", "Spanish"],
      "samples": [
        {
          "title": "Default Sample",
          "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
}

Przykład 2: wyszukiwanie rozmyte według tytułu (`title`)

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

Odpowiedź (testowana w praktyce):

{
  "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
}

Zauważ, że title to „globalne dopasowanie rozmyte”, które jednocześnie trafia we wszystkie głosy z publicznej biblioteki Fish (nie tylko własne).

Przykład 3: wyświetlanie wyłącznie głosów utworzonych przez siebie (`self=true`)

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

Przykładowa odpowiedź:

{
  "total": 1,
  "items": [
    {
      "_id": "e5c6db52c3ed417f9cb2e5a33fb04667",
      "type": "tts",
      "title": "copilot-smoke-test",
      "description": "smoke test from api.acedata.cloud",
      "state": "trained",
      "languages": ["zh"],
      "visibility": "public",
      "samples": [
        {
          "title": "Default Sample",
          "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": false
}

self=true wyświetla głosy utworzone i zapisane przez tę platformę dla faktycznie wywołującego konta; głosy utworzone przez to samo konto przy użyciu różnych API Token również zostaną wyświetlone razem. Wyniki są stronicowane w odwrotnej kolejności czasu utworzenia, a author_id może dalej filtrować ID autora tych głosów. Ten parametr filtruje tylko listę, głosy nadal są publicznie dostępne. self=true nie obsługuje title_language; jeśli chcesz wyszukiwać według języka tytułu, przeszukaj publiczną bibliotekę głosów.

Przykład 4: filtrowanie według języka + tagów

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'

Usługa nadrzędna zwraca również wyniki dla tag, które nie znajdują się w słowniku tagów, ale dopasowanie jest względnie luźne; jeśli liczba trafień wynosi 0, zaleca się użycie rozmytego dopasowania title.

Pola odpowiedzi

Każdy element w items[] jest kompletnym obiektem ModelEntity, często używane pola:

Pole	Typ	Opis
`_id`	string	ID głosu, używane jako wartość `reference_id` w `/fish/tts`.
`type`	string	Typ modelu, zazwyczaj `tts`.
`title`	string	Nazwa głosu.
`description`	string	Opis głosu.
`state`	string	Stan trenowania: `trained` oznacza dostępność.
`tags`	string[]	Tagi publicznej biblioteki.
`languages`	string[]	Języki, w których głos jest dobry.
`visibility`	string	`public` lub `private`.
`samples`	object[]	Wstępnie ustawione próbki (w tym bezpośredni link `audio`).
`like_count`	integer	Liczba polubień w publicznej bibliotece.
`task_count`	integer	Liczba historycznych syntez.
`author`	object	Informacje o autorze głosu: `_id` / `nickname` / `avatar`.
`total`（najwyższy poziom）	integer	Łączna liczba pozycji spełniających warunki.
`has_more`	boolean?	Przy `self=true` jest wartością logiczną; zapytania do publicznej biblioteki głosów mogą mieć wartość `null`.

Informacje o rozliczeniach

Ten interfejs nie jest płatny — stronicowane pobieranie listy głosów jest operacją bezpłatną. Tworzenie głosów (Fish Model Create) również jest bezpłatne, opłaty są naliczane wyłącznie według użycia podczas wywoływania Fish TTS w celu syntezy mowy.

Obsługa błędów

400 token_mismatched: brakujące lub nieprawidłowe parametry żądania.
401 invalid_token: token uwierzytelniający nie istnieje lub jest nieprawidłowy.
429 too_many_requests: uruchomiono limit szybkości konta.
500 api_error: wewnętrzny błąd serwera.

Przykład odpowiedzi błędu:

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

Wnioski

Aby wybrać głos z publicznej biblioteki Fish i przekazać go do reference_id w /fish/tts, najpierw użyj tego interfejsu wraz z title / tag / language do wyszukiwania, zlokalizuj docelowe _id, a następnie użyj Fish Model Get, aby pobrać próbkę do odsłuchu. Aby wyświetlić głosy utworzone przez siebie, wystarczy przekazać self=true.

Getting Started

Czat AI

Obraz AI

Wideo AI

Audio AI

Sieć i dane

CAPTCHA

Tożsamość

Coding

Więcej przewodników

Instrukcja integracji API zapytań modelu Fish

Proces aplikowania

Parametry zapytania

Przykład 1: domyślne stronicowanie (według `page_size`)

Przykład 2: wyszukiwanie rozmyte według tytułu (`title`)

Przykład 3: wyświetlanie wyłącznie głosów utworzonych przez siebie (`self=true`)

Przykład 4: filtrowanie według języka + tagów

Pola odpowiedzi

Informacje o rozliczeniach

Obsługa błędów

Wnioski

​Proces aplikowania

​Parametry zapytania

​Przykład 1: domyślne stronicowanie (według page_size)

​Przykład 2: wyszukiwanie rozmyte według tytułu (title)

​Przykład 3: wyświetlanie wyłącznie głosów utworzonych przez siebie (self=true)

​Przykład 4: filtrowanie według języka + tagów

​Pola odpowiedzi

​Informacje o rozliczeniach

​Obsługa błędów

​Wnioski

Proces aplikowania

Parametry zapytania

Przykład 1: domyślne stronicowanie (według `page_size`)

Przykład 2: wyszukiwanie rozmyte według tytułu (`title`)

Przykład 3: wyświetlanie wyłącznie głosów utworzonych przez siebie (`self=true`)

Przykład 4: filtrowanie według języka + tagów

Pola odpowiedzi

Informacje o rozliczeniach

Obsługa błędów

Wnioski