Przejdź do głównej treści
Ten dokument przedstawi sposób integracji Fish Voices Generation API, które pozwala na tworzenie własnych tonów poprzez wprowadzenie linku do audio.

​
Proces aplikacji

Aby korzystać z API, należy najpierw przejść do strony Fish Voices Generation API i złożyć wniosek o odpowiednią usługę, po wejściu na stronę, kliknij przycisk „Acquire”, jak pokazano na obrazku: Jeśli nie jesteś zalogowany lub zarejestrowany, automatycznie zostaniesz przekierowany na stronę logowania, aby zarejestrować się i zalogować, po zalogowaniu lub rejestracji automatycznie wrócisz na bieżącą stronę. Podczas pierwszej aplikacji otrzymasz darmowy limit, który pozwala na bezpłatne korzystanie z tego API.

​
Podstawowe użycie

Najpierw zapoznaj się z podstawowym sposobem użycia, polegającym na wprowadzeniu linku audio voice_url, aby uzyskać przetworzony wynik, szczegóły są następujące:

Można zauważyć, że ustawiliśmy nagłówki żądania, w tym:
  • accept: format odpowiedzi, który chcesz otrzymać, tutaj wpisz application/json, czyli format JSON.
  • authorization: klucz do wywołania API, po złożeniu wniosku można go bezpośrednio wybrać z rozwijanej listy.
Dodatkowo ustawiono ciało żądania, w tym:
  • voice_url: link do przesłanego audio.
  • title: tytuł tego tonu.
  • image_urls: okładka tego tonu.
  • description: opis tego tonu.
  • callback_url: URL, na który mają być zwracane wyniki.
Po dokonaniu wyboru, można zauważyć, że po prawej stronie wygenerowano odpowiedni kod, jak pokazano na obrazku:

Kliknij przycisk „Try”, aby przeprowadzić test, jak pokazano na powyższym obrazku, otrzymujemy następujący wynik: 
{
  "success": true,
  "task_id": "b01db503-dd9e-4f92-861a-344f14756217",
  "trace_id": "8731a2f1-7736-4a47-98e7-da942f9346a7",
  "data": {
    "_id": "d5d21261512b4852b9ccd709facf93f3",
    "type": "tts",
    "title": "test",
    "description": "test",
    "cover_image": "coverimage/d5d21261512b4852b9ccd709facf93f3",
    "train_mode": "fast",
    "state": "trained",
    "tags": [],
    "samples": [
      {
        "title": "Default Sample",
        "text": "Przez długoterminowe obserwacje odkryto, że ryby w ekosystemie raf koralowych mają złożone wzorce zachowań grupowych. Wykorzystują zmiany kolorów i specyficzne postawy pływania do przekazywania informacji, ten precyzyjny system komunikacji niewerbalnej ukazuje adaptacyjną mądrość organizmów morskich.",
        "task_id": "4ae961828fc94c07b2103dc039a8466b",
        "audio": "task/4ae961828fc94c07b2103dc039a8466b.mp3"
      }
    ],
    "created_at": "2025-09-21T07:29:41.058506Z",
    "updated_at": "2025-09-21T07:29:41.057917Z",
    "languages": [
      "zh"
    ],
    "visibility": "public",
    "lock_visibility": false,
    "default_text": "Przez długoterminowe obserwacje odkryto, że ryby w ekosystemie raf koralowych mają złożone wzorce zachowań grupowych. Wykorzystują zmiany kolorów i specyficzne postawy pływania do przekazywania informacji, ten precyzyjny system komunikacji niewerbalnej ukazuje adaptacyjną mądrość organizmów morskich.",
    "like_count": 0,
    "mark_count": 0,
    "shared_count": 0,
    "task_count": 0,
    "unliked": false,
    "liked": false,
    "marked": false,
    "author": {
      "_id": "7ecad23df62a4174acd6a2a6cb5201ee",
      "nickname": "Matthew Garcia",
      "avatar": "avatars/7ecad23df62a4174acd6a2a6cb5201ee.jpg"
    }
  }
}
Wynik zwrotny zawiera wiele pól, które są opisane poniżej:
  • success, status zadania tworzenia tonu.
    • data, wynik zadania muzycznego
      • _id, ID zadania generowania tonu, które będzie używane do klonowania dźwięku.
      • title, tytuł tonu.
      • image_url, informacja o okładce tonu.
      • description, opis tonu.
      • train_mode, tryb użyty do generowania tonu.
      • tags, styl tonu.
      • default_text, tekst dźwiękowy zadania generowania tonu.
Można zauważyć, że otrzymaliśmy satysfakcjonujące informacje o tonie, wystarczy, że na podstawie data w id przeprowadzimy zadanie klonowania dźwięku. Dodatkowo, jeśli chcesz wygenerować odpowiedni kod integracyjny, możesz go bezpośrednio skopiować, na przykład kod CURL wygląda następująco: 
curl -X POST 'https://api.acedata.cloud/fish/voices' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "voice_url": "https://platform.r2.fish.audio/task/604133d7b3c7430385382470f67770e8.mp3",
  "title": "test",
  "description": "test"
}'

​
Asynchroniczne wywołanie zwrotne

Ponieważ czas generowania Fish Voices Generation API jest stosunkowo długi, wynosi około 1-2 minut, jeśli API nie odpowiada przez dłuższy czas, żądanie HTTP będzie utrzymywać połączenie, co prowadzi do dodatkowego zużycia zasobów systemowych, dlatego to API oferuje również wsparcie dla asynchronicznych wywołań zwrotnych. Cały proces polega na tym, że klient podczas wysyłania żądania dodatkowo określa pole callback_url, po wysłaniu żądania API natychmiast zwraca wynik, zawierający pole task_id, które reprezentuje aktualne ID zadania. Po zakończeniu zadania, wynik generowania zadania zostanie wysłany do określonego przez klienta callback_url w formie POST JSON, w tym również pole task_id, dzięki czemu wynik zadania można powiązać z ID. Poniżej przedstawiamy przykład, aby zrozumieć, jak dokładnie to działa. Najpierw, wywołanie zwrotne Webhook to usługa, która może odbierać żądania HTTP, deweloperzy powinni zastąpić URL swojego serwera HTTP. W tym celu, dla wygody demonstracji, użyjemy publicznej strony przykładowej Webhook https://webhook.site/, otwierając tę stronę, otrzymasz URL Webhook, jak pokazano na obrazku: Skopiuj ten URL, aby użyć go jako Webhook, przykładowy URL to https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34. Następnie możemy ustawić pole callback_url na powyższy URL Webhook, a także wprowadzić odpowiednie parametry, szczegóły jak na obrazku:

Klikając „Uruchom”, można zauważyć, że natychmiast otrzymujemy wynik, jak poniżej: 
{
  "task_id": "9f626a13-96ec-4dec-8846-dc5aab7362a8"
}
Proszę chwilę poczekać, możemy obserwować wyniki generowania zadań na https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34, jak pokazano na obrazku: Treść jest następująca: 
{
    "success": true,
    "task_id": "9f626a13-96ec-4dec-8846-dc5aab7362a8",
    "trace_id": "3fcdea82-7c1c-4a0a-b8d8-f7616f722d8f",
    "data": {
        "_id": "fa75e7c3f02f42e79a6aa622b6cf075e",
        "type": "tts",
        "title": "test",
        "description": "test",
        "cover_image": "coverimage/fa75e7c3f02f42e79a6aa622b6cf075e",
        "train_mode": "fast",
        "state": "trained",
        "tags": [],
        "samples": [
            {
                "title": "Default Sample",
                "text": "Delfiny nawigują w oceanie za pomocą systemu echolokacji, ta precyzyjna technologia fal dźwiękowych pozwala im wykrywać otoczenie, szukać pożywienia i unikać niebezpieczeństw. To nie tylko pokazuje zdolności adaptacyjne morskich stworzeń, ale także ujawnia cudowny projekt natury.",
                "task_id": "68cdda24d26e4794bae177e20da740db",
                "audio": "task/68cdda24d26e4794bae177e20da740db.mp3"
            }
        ],
        "created_at": "2025-09-21T07:36:20.200865Z",
        "updated_at": "2025-09-21T07:36:20.200353Z",
        "languages": [
            "zh"
        ],
        "visibility": "public",
        "lock_visibility": false,
        "default_text": "Delfiny nawigują w oceanie za pomocą systemu echolokacji, ta precyzyjna technologia fal dźwiękowych pozwala im wykrywać otoczenie, szukać pożywienia i unikać niebezpieczeństw. To nie tylko pokazuje zdolności adaptacyjne morskich stworzeń, ale także ujawnia cudowny projekt natury.",
        "like_count": 0,
        "mark_count": 0,
        "shared_count": 0,
        "task_count": 0,
        "unliked": false,
        "liked": false,
        "marked": false,
        "author": {
            "_id": "7ecad23df62a4174acd6a2a6cb5201ee",
            "nickname": "Matthew Garcia",
            "avatar": "avatars/7ecad23df62a4174acd6a2a6cb5201ee.jpg"
        }
    }
}
Można zauważyć, że w wynikach znajduje się pole task_id, a inne pola są podobne do powyższych, dzięki czemu można powiązać zadania.

​
Obsługa błędów

Podczas wywoływania API, jeśli wystąpi błąd, API zwróci odpowiedni kod błędu i informacje. Na przykład:
  • 400 token_mismatched: Złe żądanie, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów.
  • 400 api_not_implemented: Złe żądanie, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów.
  • 401 invalid_token: Nieautoryzowany, nieprawidłowy lub brakujący token autoryzacyjny.
  • 429 too_many_requests: Zbyt wiele żądań, przekroczono limit szybkości.
  • 500 api_error: Błąd wewnętrzny serwera, coś poszło nie tak na serwerze.

​
Przykład odpowiedzi błędu

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

​
Wnioski

Dzięki temu dokumentowi zrozumieliście, jak korzystać z API Generacji Głosów Ryb, które pozwala na tworzenie własnych tonów za pomocą połączenia audio tonów wejściowych. Mamy nadzieję, że ten dokument pomoże Wam lepiej zintegrować i korzystać z tego API. W razie jakichkolwiek pytań, prosimy o kontakt z naszym zespołem wsparcia technicznego.