> ## 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.

# Face Swap API の接続と使用

> Face Transformation 集成指南 - XHuoAPI

Face Swap API の主な機能は、ソース画像とターゲット画像を入力することで、ターゲット画像の顔をソース画像の顔に置き換えることです。

この文書では、Face Swap API の接続方法を詳しく説明し、簡単に統合し、この API の強力な機能を最大限に活用できるようにします。Face Swap API を使用することで、ターゲット画像の顔をソース画像の顔に簡単に置き換えることができます。

## 申請プロセス

Face Swap API を使用するには、まず申請ページ [Face Swap API](https://api.xhuoapi.ai/documents/d10df07a-66a6-4c37-b114-3a003fc9bd55) にアクセスして、該当するサービスを申請する必要があります。ページに入ったら、「Acquire」ボタンをクリックします。以下の図のように：

![申請ページ](https://cdn.xhuoapi.ai/rci31i.png)

まだログインまたは登録していない場合は、自動的に[ログインページ](https://api.xhuoapi.ai)にリダイレクトされ、登録とログインを促されます。ログインまたは登録後、現在のページに自動的に戻ります。

初回申請時には無料のクレジットが付与され、この API を無料で使用できます。

## リクエスト例

2つの画像を例に、API の使用方法を示します。ソース画像は以下のようになります：

<p>
  <img src="https://cdn.xhuoapi.ai/n1lmd8.png" width="500" className="m-auto" />
</p>

ターゲット画像は：

<p>
  <img src="https://cdn.xhuoapi.ai/3np95r.png" width="500" className="m-auto" />
</p>

次に、ターゲット画像の顔をソース画像の顔に置き換える方法を示します。

### リクエストヘッダーとリクエストボディの設定

**Request Headers** には以下が含まれます：

* `accept`：JSON形式のレスポンスを受け取ることを指定します。ここには `application/json` と記入します。
* `authorization`：APIを呼び出すためのキーで、申請後に直接選択できます。

**Request Body** には以下が含まれます：

* `source_image_url`：アップロードしたソース画像のリンク。
* `target_image_url`：アップロードしたターゲット画像のリンク。
* `timeout`：オプション、処理のタイムアウト時間（秒）、タイムアウト時には直接返されます。

設定は以下の図のようになります：

<p>
  <img src="https://cdn.xhuoapi.ai/g7tnn1.png" width="500" className="m-auto" />
</p>

### コード例

ページの右側には、すでにさまざまな言語のコードが自動生成されています。以下の図のように：

<p>
  <img src="https://cdn.xhuoapi.ai/t8gsls.png" width="500" className="m-auto" />
</p>

一部のコード例は以下の通りです：

#### 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)
```

### レスポンス例

リクエストが成功すると、API は顔交換後の画像結果情報を返します。例えば：

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

結果には `image_url` フィールドがあり、そこにはターゲット画像の顔を元の画像の顔に置き換えた後の画像リンクが含まれています。他の情報は以下の図のようになります：

* `image_url`、生成された画像のリンク。
* `image_width`、生成された画像の幅。
* `image_height`、生成された画像の高さ。
* `image_size`、生成された画像のサイズ。
* `task_id`、今回の生成タスクの ID。

生成された画像の結果は：

<p>
  <img src="https://cdn.xhuoapi.ai/soa3lk.png" width="500" className="m-auto" />
</p>

この画像には、ターゲット画像の顔がソース画像の顔に成功裏に置き換えられたことが明らかに示されています。

## 非同期コールバック

Face Swap の生成には比較的長い時間がかかり、約 1-2 分必要です。API が長時間応答しない場合、HTTP リクエストは接続を維持し続け、追加のシステムリソースを消費するため、この API では非同期コールバックのサポートも提供しています。

全体の流れは次の通りです：クライアントがリクエストを発行する際に、追加で `callback_url` フィールドを指定します。クライアントが API リクエストを発行した後、API はすぐに結果を返し、`task_id` フィールド情報を含み、現在のタスク ID を示します。タスクが完了すると、生成された Face Swap の結果が POST JSON 形式でクライアントが指定した `callback_url` に送信され、その中にも `task_id` フィールドが含まれ、タスク結果を ID で関連付けることができます。

以下の例を通じて、具体的にどのように操作するかを理解しましょう。

まず、Webhook コールバックは HTTP リクエストを受け取ることができるサービスで、開発者は自分が構築した HTTP サーバーの URL に置き換える必要があります。ここでは、便利なデモのために公開された Webhook サンプルサイト [https://webhook.site/](https://webhook.site/) を使用します。このサイトを開くと、Webhook URL が得られます。以下の図のように：

![](https://cdn.xhuoapi.ai/r8wyb7.png)

この URL をコピーすれば、Webhook として使用できます。このサンプルは [https://webhook.site/3b76eba5-4573-432a-b607-3000b87afc06](https://webhook.site/3b76eba5-4573-432a-b607-3000b87afc06) です。

次に、フィールド `callback_url` を上記の Webhook URL に設定し、対応するパラメータを入力します。以下の図のように：

<p>
  <img src="https://cdn.xhuoapi.ai/xx08i2.png" width="500" className="m-auto" />
</p>

実行をクリックすると、すぐに結果が得られます。以下のように：

```json theme={null}
{
  "task_id": "9cba9d36-3b14-43c9-85b6-86f6dfc3b096"
}
```

少し待つと、[https://webhook.site/3b76eba5-4573-432a-b607-3000b87afc06](https://webhook.site/3b76eba5-4573-432a-b607-3000b87afc06) で生成された Face Swap の結果を確認できます。以下の図のように：

![](https://cdn.xhuoapi.ai/col42s.png)

内容は以下の通りです：

```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
}
```

結果には `task_id` フィールドがあり、他のフィールドは上記と似ており、このフィールドを通じてタスクの関連付けが可能です。

## エラーハンドリング

API を呼び出す際にエラーが発生した場合、API は対応するエラーコードと情報を返します。例えば：

* `400 token_mismatched`：不正なリクエスト、パラメータが欠落しているか無効である可能性があります。
* `400 api_not_implemented`：不正なリクエスト、パラメータが欠落しているか無効である可能性があります。
* `401 invalid_token`：認証されていません、無効または欠落している認証トークンです。
* `429 too_many_requests`：リクエストが多すぎます、レート制限を超えました。
* `500 api_error`：内部サーバーエラー、サーバーで何かがうまくいきませんでした。

### エラー応答の例

```
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "取得に失敗しました"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## 結論

この文書を通じて、Face Swap APIを使用してターゲット画像の顔をソース画像の顔に置き換える方法を理解しました。この文書がAPIの接続と使用に役立つことを願っています。ご不明な点がございましたら、いつでも技術サポートチームにお問い合わせください。