> ## 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.
# Integracja i użycie API Face Swap
> Face Transformation 集成指南 - XHuoAPI
Główna funkcja API Face Swap polega na zamianie twarzy w obrazie źródłowym na twarz w obrazie docelowym poprzez wprowadzenie jednego obrazu źródłowego i jednego obrazu docelowego.
Dokument ten szczegółowo opisuje instrukcje integracji API Face Swap, aby pomóc Ci łatwo zintegrować i w pełni wykorzystać potężne możliwości tego API. Dzięki API Face Swap możesz łatwo zamienić twarz z obrazu docelowego na twarz z obrazu źródłowego.
## Proces aplikacji
Aby korzystać z API Face Swap, należy najpierw przejść do strony aplikacji [Face Swap API](https://api.xhuoapi.ai/documents/d10df07a-66a6-4c37-b114-3a003fc9bd55), klikając przycisk „Acquire”, jak pokazano na poniższym obrazku:
Jeśli nie jesteś zalogowany lub zarejestrowany, automatycznie zostaniesz przekierowany na [stronę logowania](https://api.xhuoapi.ai), aby zarejestrować się i zalogować. Po zalogowaniu lub rejestracji zostaniesz automatycznie przekierowany z powrotem na bieżącą stronę.
Podczas pierwszej aplikacji otrzymasz darmowy limit, który pozwala na bezpłatne korzystanie z tego API.
## Przykład żądania
Użyjemy dwóch obrazów jako przykładu, aby pokazać, jak korzystać z tego API. Załóżmy, że obraz źródłowy wygląda jak poniżej:
Obraz docelowy to:
Następnie pokażemy, jak zamienić twarz z obrazu docelowego na twarz z obrazu źródłowego.
### Ustawienia nagłówków żądania i ciała żądania
**Nagłówki żądania** obejmują:
* `accept`: określa, że oczekiwany jest wynik odpowiedzi w formacie JSON, tutaj wpisz `application/json`.
* `authorization`: klucz do wywołania API, po aplikacji można go bezpośrednio wybrać z rozwijanej listy.
**Ciało żądania** obejmuje:
* `source_image_url`: link do przesłanego obrazu źródłowego.
* `target_image_url`: link do przesłanego obrazu docelowego.
* `timeout`: opcjonalne, czas oczekiwania na przetwarzanie (w sekundach), po upływie czasu zwróci bezpośrednio.
Ustawienia są pokazane na poniższym obrazku:
### Przykład kodu
Można zauważyć, że po prawej stronie strony automatycznie wygenerowano kod w różnych językach, jak pokazano na poniższym obrazku:
Niektóre przykłady kodu są następujące:
#### CURL
```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/face/swap' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"source_image_url": "https://cdn.xhuoapi.ai/n1lmd8.png",
"target_image_url": "https://cdn.xhuoapi.ai/3np95r.png"
}'
```
#### Python
```python theme={null}
import requests
url = "https://api.xhuoapi.ai/v1/face/swap"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"source_image_url": "https://cdn.xhuoapi.ai/n1lmd8.png",
"target_image_url": "https://cdn.xhuoapi.ai/3np95r.png"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
### Przykład odpowiedzi
Po pomyślnym żądaniu API zwróci informacje o wyniku zamiany twarzy. Na przykład:
```json theme={null}
{
"image_url": "https://platform.cdn.xhuoapi.ai/face/4b13bdeb-1b19-4ea5-bddf-c2da14ba72e3.png",
"image_width": 2008,
"image_height": 1942,
"image_size": 4006213,
"task_id": "4b13bdeb-1b19-4ea5-bddf-c2da14ba72e3"
}
```
Można zauważyć, że w wyniku znajduje się pole `image_url`, które zawiera link do obrazu po zamianie twarzy, a inne informacje są pokazane na poniższym obrazku:
* `image_url`, link do wygenerowanego obrazu.
* `image_width`, szerokość wygenerowanego obrazu.
* `image_height`, długość wygenerowanego obrazu.
* `image_size`, rozmiar wygenerowanego obrazu.
* `task_id`, ID zadania generacji.
Wynik wygenerowanego obrazu to:
Można wyraźnie zobaczyć, że obraz pomyślnie zamienił twarz z obrazu docelowego na twarz z obrazu źródłowego.
## Asynchroniczny callback
Ponieważ czas generacji Face Swap 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 callbacków.
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 generacji Face Swap zostanie wysłany do określonego przez klienta `callback_url` w formie POST JSON, w tym również 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, callback Webhook to usługa, która może odbierać żądania HTTP, deweloperzy powinni zastąpić ją URL swojego serwera HTTP. W tym celu, dla wygody demonstracji, użyjemy publicznej strony przykładowej Webhook [https://webhook.site/](https://webhook.site/), otwierając tę stronę, można uzyskać URL Webhook, jak pokazano na poniższym obrazku:
Skopiuj ten URL, aby użyć go jako Webhook, przykładowy URL to [https://webhook.site/3b76eba5-4573-432a-b607-3000b87afc06](https://webhook.site/3b76eba5-4573-432a-b607-3000b87afc06).
Następnie możemy ustawić pole `callback_url` na powyższy URL Webhook, a także wypełnić odpowiednie parametry, jak pokazano na poniższym obrazku:
Klikając uruchom, można zauważyć, że natychmiast otrzymujemy wynik, jak poniżej:
```json theme={null}
{
"task_id": "9cba9d36-3b14-43c9-85b6-86f6dfc3b096"
}
```
Po chwili możemy obserwować wynik generacji Face Swap na [https://webhook.site/3b76eba5-4573-432a-b607-3000b87afc06](https://webhook.site/3b76eba5-4573-432a-b607-3000b87afc06), jak pokazano na poniższym obrazku:
Treść jest następująca:
```json theme={null}
{
"success": true,
"task_id": "9cba9d36-3b14-43c9-85b6-86f6dfc3b096",
"image_url": "https://platform.cdn.xhuoapi.ai/face/9cba9d36-3b14-43c9-85b6-86f6dfc3b096.png",
"image_width": 2008,
"image_height": 1942,
"image_size": 4006481
}
```
Można zauważyć, że w wyniku znajduje się pole `task_id`, a inne pola są podobne do tych opisanych wcześniej, dzięki czemu można powiązać zadanie.
## 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ły wniosek, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów.
* `400 api_not_implemented`：Zły wniosek, 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ń, przekroczyłeś 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 zrozumiałeś, jak używać API Face Swap do zamiany twarzy z docelowego obrazu na twarz z obrazu źródłowego. 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.