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

# AI証明写真制作 API 接続説明

> AI ID Photo Production 集成指南 - XHuoAPI

本文では、AI証明写真制作 API 接続説明を紹介します。これは、人像写真のURLと好みのテンプレートを入力することで、さまざまなスタイルの証明写真を制作できるものです。

## 申請プロセス

APIを使用するには、まず [AI証明写真制作 API](https://api.xhuoapi.ai/documents/bf7214a3-8447-4157-8a75-f5bb39d5ed1b) の該当ページでサービスを申請する必要があります。ページに入ったら、「Acquire」ボタンをクリックします。以下の図のように：

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

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

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

## 基本使用

まず、基本的な使用方法を理解します。処理したい人像画像と好みのAI証明写真テンプレートを入力することで、処理後の結果を得ることができます。最初に、`image_urls` フィールドを簡単に渡す必要があります。これは、処理したい人像画像のリンクの配列です。以下の図のように：

<p>
  <img src="https://cdn.zhishuyun.com/2024-11-03-d23744954ca4819503469f04f2268aa0.jpg" width="500" className="m-auto" />
</p>

次に、自分の好きなテンプレートを入力する必要があります。本文では、人気のある8種類のテンプレートを提供しています。具体的なテンプレートは以下の通りです：

```json theme={null}
{
   "male_portrait":  男性の証明写真
   "male_portrait2":  男性の証明写真（別バージョン）
   "kindergarten":  幼稚園入園写真
   "logo_tshirt": 企業ロゴTシャツ写真
   "wedding":  結婚登録写真
   "business_photo":  ビジネス風写真
   "bob_suit":  黒スーツのボブヘア
   "female_portrait":  女性の証明写真
}
```

その後、生成の速度パラメータ `mode` を指定することもできます。一般的には、遅い `relax` と速い `fast` の2種類に分かれています。具体的な内容は以下の通りです：

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

ここでは、リクエストヘッダーを設定しています。これには以下が含まれます：

* `accept`：受け取りたいレスポンスの形式。ここでは `application/json`、つまりJSON形式を記入します。
* `authorization`：APIを呼び出すためのキー。申請後、直接ドロップダウンから選択できます。

また、リクエストボディを設定しています。これには以下が含まれます：

* `mode`：証明写真生成のチャンネル。主にfast（速い）とrelax（遅い）の2種類があります。relaxを使用する場合は、以下のパラメータ `callback_url` の使用を強く推奨します。
* `template`：証明写真テンプレートのスタイル。
* `image_urls`：アップロードする証明写真の人像リンク。
* `callback_url`：結果を返すためのURL。

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

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

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

```json theme={null}
{
  "success": true,
  "task_id": "ae1e4948-dba1-4a6f-87af-67961b647428",
  "data": [
    {
      "id": "202411031951124776",
      "image_url": "https://platform.cdn.xhuoapi.ai/headshots/ae1e4948-dba1-4a6f-87af-67961b647428.png",
      "template": "男性の証明写真"
    },
    {
      "id": "202411031951128490",
      "image_url": "https://platform.cdn.xhuoapi.ai/headshots/ae1e4948-dba1-4a6f-87af-67961b647428.png",
      "template": "男性の証明写真"
    }
  ]
}
```

返された結果には複数のフィールドがあり、以下のように説明されます：

* `success`：この時点での証明写真生成タスクの状態。
* `task_id`：この時点での証明写真生成タスクID。
* `data`：この時点での証明写真生成タスクの結果リスト。
  * `id`：この時点での証明写真生成タスクの写真ID。
  * `image_url`：この時点での証明写真生成タスクの画像リンク。
  * `template`：この時点での証明写真生成タスクの証明写真テンプレート名。

テンプレートと人像画像に基づいて満足のいく証明写真情報を得ることができました。結果の `data` の画像リンクアドレスに従って証明写真を取得するだけです。

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

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/headshots/generate' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "mode": "fast",
  "template": "male_portrait",
  "image_urls": ["https://cdn.zhishuyun.com/2024-11-03-d23744954ca4819503469f04f2268aa0.jpg"]
}'
```

## 非同期コールバック

AI証明写真生成の時間は比較的長く、約1-2分かかります。APIが長時間応答しない場合、HTTPリクエストは接続を維持し続け、追加のシステムリソースを消費する可能性があります。そのため、本APIは非同期コールバックのサポートも提供しています。

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

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

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

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

このURLをコピーすればWebhookとして使用できます。このサンプルは `https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a` です。

次に、フィールド `callback_url` を上記のWebhook URLに設定し、人像画像リンクとテンプレートを入力します。本文では、パラメータ `mode` が `relax` の場合に非同期コールバックを使用することを推奨します。具体的な内容は以下の図のように：

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

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

```
{
  "task_id": "763b1450-8804-434f-acc7-d713be73a28f"
}
```

少し待つと、`https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a` で生成された結果を確認できます。以下の図のように：
![](https://cdn.xhuoapi.ai/ym6fw1.png)

内容如下：

```json theme={null}
{
    "success": true,
    "task_id": "763b1450-8804-434f-acc7-d713be73a28f",
    "data": [
        {
            "id": "202411032010131366",
            "image_url": "https://platform.cdn.xhuoapi.ai/headshots/763b1450-8804-434f-acc7-d713be73a28f.png",
            "template": "男形象照"
        },
        {
            "id": "202411032010132420",
            "image_url": "https://platform.cdn.xhuoapi.ai/headshots/763b1450-8804-434f-acc7-d713be73a28f.png",
            "template": "男形象照"
        }
    ]
}
```

結果には `task_id` フィールドが含まれており、他のフィールドは前述の内容と類似しており、このフィールドを通じてタスクの関連付けが可能です。

## エラーハンドリング

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

## 結論

この文書を通じて、AI証明写真制作APIの使用方法を理解しました。人像写真のURLと好みのテンプレートを入力することで、さまざまなスタイルの証明写真を制作できます。この文書がAPIの接続と使用に役立つことを願っています。ご不明な点がございましたら、いつでも技術サポートチームにお問い合わせください。