> ## 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 Audios Generation API dokumentacja integracji
> Fish music generation 集成指南 - XHuoAPI
W tym artykule przedstawimy dokumentację integracji Fish Audios Generation API, która pozwala na klonowanie własnego głosu za pomocą wprowadzenia słów kluczowych.
## Proces aplikacji
Aby skorzystać z API, należy najpierw przejść do strony [Fish Audios Generation API](https://api.xhuoapi.ai/documents/e681b715-54fd-4464-a59a-d7f14500e095) 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, czyli wprowadzeniem słów kluczowych `prompt`, działania `action`, identyfikatora głosu `voice_id` oraz modelu `model`, aby uzyskać przetworzony wynik. Najpierw musisz przekazać pole `action`, którego wartość to `generate`, a następnie musimy wprowadzić model `model`, obecnie głównie model `fish-tts`, szczegóły są następujące:
Możemy zobaczyć, że ustawiliśmy nagłówki żądania, w tym:
* `accept`: jakiego formatu odpowiedzi oczekujesz, 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:
* `model`: model klonowania głosu, głównie model `fish-tts`.
* `action`: działanie w ramach zadania klonowania głosu.
* `prompt`: słowa kluczowe do sklonowania.
* `voice_id`: klonowanie na podstawie identyfikatora głosu.
* `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:
```json theme={null}
{
"success": true,
"task_id": "5872ab00-3cf4-4040-a798-8510aaa16756",
"trace_id": "5eda3694-448a-4b72-af33-2acb3851ffe1",
"data": [
{
"audio_url": "https://platform.r2.fish.audio/task/8a72ff9840234006a9f74cb2fa04f978.mp3"
}
]
}
```
Wynik zwrotny zawiera wiele pól, które są opisane poniżej:
* `success`, status zadania klonowania głosu.
* `data`, wynik zadania klonowania głosu
* `audio_url`, link do audio wynikającego z zadania klonowania głosu.
Możemy zobaczyć, że otrzymaliśmy satysfakcjonujące informacje o głosie, wystarczy, że na podstawie adresu linku muzycznego w `data` uzyskamy sklonowany głos.
Dodatkowo, jeśli chcesz wygenerować odpowiedni kod do integracji, możesz go bezpośrednio skopiować, na przykład kod CURL wygląda następująco:
```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/fish/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"action": "speech",
"prompt": "a white siamese cat",
"model": "fish-tts",
"voice_id": "d7900c21663f485ab63ebdb7e5905036"
}'
```
## Asynchroniczne wywołanie zwrotne
Ponieważ czas generacji Fish Audios 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 wygląda następująco: klient inicjuje żądanie, dodatkowo określając pole `callback_url`, po zainicjowaniu żądania API natychmiast zwraca wynik, zawierający pole `task_id`, które reprezentuje bieżące ID zadania. Po zakończeniu zadania, wynik generacji zostanie wysłany do określonego przez klienta `callback_url` w formie POST JSON, który również zawiera pole `task_id`, dzięki czemu wyniki zadania można powiązać za pomocą ID.
Poniżej przedstawiamy przykład, aby zrozumieć, jak to działa.
Najpierw, wywołanie zwrotne Webhook to usługa, która może odbierać żądania HTTP, deweloper powinien zastąpić to URL swojego serwera HTTP. Dla wygody demonstracji użyjemy publicznej strony przykładowej Webhook [https://webhook.site/](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 są pokazane na obrazku:
Klikając „Uruchom”, można zauważyć, że natychmiast otrzymujemy wynik, jak poniżej:
```
{
"task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5"
}
```
Po chwili możemy na `https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34` zobaczyć wynik zadania generacji, jak pokazano na obrazku:
Treść jest następująca:
```json theme={null}
{
"success": true,
"task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
"trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
"data": [
{
"audio_url": "https://platform.r2.fish.audio/task/b627c2f7d38a4083a837570ba6d0962f.mp3"
}
]
}
```
Możemy zobaczyć, że wynik zawiera pole `task_id`, a pozostałe pola są podobne do tych opisanych wcześniej, dzięki czemu można powiązać zadanie za pomocą tego pola.
## Obsługa błędów
Podczas wywoływania API, jeśli wystąpią błędy, 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.
* `500 api_error`: Błąd wewnętrzny serwera, coś poszło nie tak na serwerze.
### Przykład odpowiedzi błędu
```json theme={null}
{
"success": false,
"error": {
"code": "api_error",
"message": "fetch failed"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```
## Wnioski
Dzięki temu dokumentowi zrozumiałeś, jak używać API generacji dźwięku Fish Audios do klonowania głosu za pomocą wprowadzonych słów kluczowych. Mamy nadzieję, że ten dokument pomoże Ci lepiej zintegrować i korzystać z tego API. W razie jakichkolwiek pytań, skontaktuj się z naszym zespołem wsparcia technicznego.