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

# 人顔美顔 API 接続説明

> Face Transformation 集成指南 - XHuoAPI

本文では、人顔美顔 API 接続説明を紹介します。これは、ユーザーが人顔画像をアップロードすることで（最大で1枚の画像中の5つの人顔情報を処理可能）、五官を正確に特定し、美肌、明るい肌、ニキビ除去などの美顔機能を実現します。

## 申請プロセス

API を使用するには、まず [人顔美顔 API](https://api.xhuoapi.ai/documents/29641bfa-8e71-4d63-8b35-7c9e647c18ba) の該当ページでサービスを申請する必要があります。ページに入ったら、「Acquire」ボタンをクリックします。以下の図のように：

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

まだログインまたは登録していない場合、自動的にログインページにリダイレクトされ、登録とログインを促されます。ログインまたは登録後、現在のページに自動的に戻ります。

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

## 基本使用

まず、基本的な使用方法を理解します。画像リンクと美顔情報を入力することで、処理後の結果画像を得ることができます。まず、`image_url` フィールドを簡単に渡す必要があります。人顔画像は以下の図のように：

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

次に、人顔美顔情報パラメータをアップロードする必要があります。具体的なリクエストボディ情報は以下の通りです。次に、画面上で対応する内容を記入できます。以下の図のように：

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

ここで、Request Headers を設定しました。含まれるのは：

* `accept`：どのような形式の応答結果を受け取りたいか。ここでは `application/json`、すなわち JSON 形式を記入します。
* `authorization`：API を呼び出すためのキー。申請後、直接ドロップダウンから選択できます。

さらに、Request Body を設定しました。含まれるのは：

* `image_url`：処理する人顔画像のリンク。
* `smoothing`：磨皮の程度、値の範囲は \[0,100]。0 は磨皮なし、100 は最高程度。デフォルト値は 10。
* `whitening`：美白の程度、値の範囲は \[0,100]。0 は美白なし、100 は最高程度。デフォルト値は 30。
* `face_lifting`：顔を細くする程度、値の範囲は \[0,100]。0 は細くしない、100 は最高程度。デフォルト値は 70。
* `eye_enlarging`：目を大きくする程度、値の範囲は \[0,100]。0 は大きくしない、100 は最高程度。デフォルト値は 70。

選択後、右側にも対応するコードが生成されていることがわかります。以下の図のように：

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

「Try」ボタンをクリックするとテストができます。上の図のように、以下の結果を得ました：

```json theme={null}
{
  "image_url": "https://faceeffect-1254418846.cos.ap-guangzhou.myqcloud.com/fmu/BeautifyPic/1256437459/1a68c13b-b03c-4c7b-92a1-e4a9b5f1d7ec"
}
```

ここで返された結果には `image_url` フィールドがあり、入力された美顔変化後の人顔画像です。変化後の人顔情報は以下の通りです：

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

画像中の人顔は、入力された美顔情報に基づいて変化したことがわかります。

また、対応する接続コードを生成したい場合は、生成されたものを直接コピーできます。例えば、CURL のコードは以下の通りです：

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/face/beautify' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "image_url": "https://cdn.xhuoapi.ai/lrbtcn.jpg",
  "smoothing": 50,
  "whitening": 50,
  "face_lifting": 50,
  "eye_enlarging": 50
}'
```

Python の接続コードは以下の通りです：

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/face/beautify"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "image_url": "https://cdn.xhuoapi.ai/lrbtcn.jpg",
    "smoothing": 50,
    "whitening": 50,
    "face_lifting": 50,
    "eye_enlarging": 50
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

## エラー処理

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

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

### エラー応答の例

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

## 結論

この文書を通じて、ユーザーがアップロードした1枚の人顔画像（最大で1枚の画像中の5つの人顔情報を処理可能）を使用して、人顔美顔 API をどのように使用するかを理解しました。美肌、明るい肌、ニキビ除去などの美顔機能を実現します。この文書が、API の接続と使用をより良くする手助けとなることを願っています。何か問題があれば、いつでも技術サポートチームにお問い合わせください。