> ## 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 の主な機能は、AI 証明写真制作 API から生成されたタスク ID を入力することで、そのタスクの実行状況を照会することです。

この文書では、AI 証明写真タスク API の接続説明を詳しく紹介し、簡単に統合し、この API の強力な機能を十分に活用できるようにします。AI 証明写真タスク API を使用することで、AI 証明写真制作 API のタスク実行状況を簡単に照会できます。

## 申請プロセス

AI 証明写真タスク API を使用するには、まず申請ページ [AI 証明写真制作 API](https://api.xhuoapi.ai/documents/bf7214a3-8447-4157-8a75-f5bb39d5ed1b) にアクセスして、該当するサービスを申請し、その後、AI 証明写真制作 API のタスク ID をコピーします。以下の図のように：

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

最後に、Tasks API ページ [AI 証明写真タスク API](https://api.xhuoapi.ai/documents/3a23ee34-8689-406b-9042-7954224348ad) にアクセスして、該当するサービスを申請します。ページに入ったら、「Acquire」ボタンをクリックします。以下の図のように：

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

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

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

## リクエスト例

AI 証明写真タスク API は、AI 証明写真制作 API の結果を照会するために使用できます。AI 証明写真制作 API の使用方法については、文書 [AI 証明写真制作 API](https://api.xhuoapi.ai/documents/d6ea75a4-836e-490a-aee5-7ca911a808fd) を参照してください。

AI 証明写真制作 API サービスから返されたタスク ID を例に、どのようにこの API を使用するかを示します。タスク ID が `16f96e95-d95c-46ef-b183-139b9bd1aebd` だと仮定し、次にタスク ID を渡す方法を示します。

### タスク例の画像

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

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

**リクエストヘッダー** には以下が含まれます：

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

**リクエストボディ** には以下が含まれます：

* `id`：アップロードされたタスク ID。
* `action`：タスクの操作方法。

以下の図のように設定します：

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

### コード例

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

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

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

#### CURL

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/headshots/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "16f96e95-d95c-46ef-b183-139b9bd1aebd",
  "action": "retrieve"
}'
```

#### Python

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/headshots/tasks"

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

payload = {
    "id": "16f96e95-d95c-46ef-b183-139b9bd1aebd",
    "action": "retrieve"
}

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

### レスポンス例

リクエストが成功すると、API はこの証明写真タスクの詳細情報を返します。例えば：

```json theme={null}
{
  "_id": "67276ab6550a4144a53b6036",
  "id": "16f96e95-d95c-46ef-b183-139b9bd1aebd",
  "api_id": "53bcc3f7-12ec-4f04-8ca4-20f150dcde2a",
  "application_id": "1af53f80-c166-4f54-a8ea-0ffc24d8e2cd",
  "created_at": 1730636470.402,
  "credential_id": "3c253880-21ef-478a-9389-c09fa837ac7c",
  "request": {
    "mode": "relax",
    "template": "male_portrait",
    "image_urls": [
      "https://cdn.zhishuyun.com/2024-11-03-d23744954ca4819503469f04f2268aa0.jpg"
    ],
    "callback_url": "https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a"
  },
  "trace_id": "6eded0e2-274d-4cde-a567-d6b0decb9a97",
  "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
  "response": {
    "success": true,
    "task_id": "16f96e95-d95c-46ef-b183-139b9bd1aebd",
    "data": [
      {
        "id": "202411032022077381",
        "image_url": "https://platform.cdn.xhuoapi.ai/headshots/16f96e95-d95c-46ef-b183-139b9bd1aebd.png",
        "template": "男形象照"
      },
      {
        "id": "202411032022079194",
        "image_url": "https://platform.cdn.xhuoapi.ai/headshots/16f96e95-d95c-46ef-b183-139b9bd1aebd.png",
        "template": "男形象照"
      }
    ]
  }
}
```

返された結果には複数のフィールドがあり、request フィールドはタスクを開始したときのリクエストボディであり、response フィールドはタスク完了後に返されるレスポンスボディです。フィールドの説明は以下の通りです。

* `id`：この証明写真タスクを生成するための ID で、今回の証明写真生成タスクを一意に識別します。
* `request`：証明写真タスクのリクエスト情報を照会します。
* `response`：証明写真タスクの返却情報を照会します。

## バッチ照会操作

これは複数のタスク ID に対して証明写真タスクの詳細を照会するもので、上記とは異なり、action を retrieve\_batch に設定する必要があります。

**リクエストボディ** には以下が含まれます：

* `ids`：アップロードされたタスク ID の配列。
* `action`：タスクの操作方法。

以下の図のように設定します：

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

### コード例

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

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

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

### レスポンス例

リクエストが成功すると、API は今回のすべてのバッチ証明写真タスクの具体的な詳細情報を返します。例えば：

```json theme={null}
{
  "items": [
    {
      "_id": "67276ab6550a4144a53b6036",
      "id": "16f96e95-d95c-46ef-b183-139b9bd1aebd",
      "api_id": "53bcc3f7-12ec-4f04-8ca4-20f150dcde2a",
      "application_id": "1af53f80-c166-4f54-a8ea-0ffc24d8e2cd",
      "created_at": 1730636470.402,
      "credential_id": "3c253880-21ef-478a-9389-c09fa837ac7c",
      "request": {
        "mode": "relax",
        "template": "男性ポートレート",
        "image_urls": [
          "https://cdn.zhishuyun.com/2024-11-03-d23744954ca4819503469f04f2268aa0.jpg"
        ],
        "callback_url": "https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a"
      },
      "trace_id": "6eded0e2-274d-4cde-a567-d6b0decb9a97",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "16f96e95-d95c-46ef-b183-139b9bd1aebd",
        "data": [
          {
            "id": "202411032022077381",
            "image_url": "https://platform.cdn.xhuoapi.ai/headshots/16f96e95-d95c-46ef-b183-139b9bd1aebd.png",
            "template": "男性ポートレート"
          },
          {
            "id": "202411032022079194",
            "image_url": "https://platform.cdn.xhuoapi.ai/headshots/16f96e95-d95c-46ef-b183-139b9bd1aebd.png",
            "template": "男性ポートレート"
          }
        ]
      }
    },
    {
      "_id": "67276c52550a4144a53b995b",
      "id": "5213468b-6b96-4ad4-9c6a-657bd438d299",
      "api_id": "53bcc3f7-12ec-4f04-8ca4-20f150dcde2a",
      "application_id": "1af53f80-c166-4f54-a8ea-0ffc24d8e2cd",
      "created_at": 1730636882.359,
      "credential_id": "3c253880-21ef-478a-9389-c09fa837ac7c",
      "request": {
        "mode": "relax",
        "template": "男性ポートレート",
        "image_urls": [
          "https://cdn.zhishuyun.com/2024-11-03-d23744954ca4819503469f04f2268aa0.jpg"
        ],
        "callback_url": "https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a"
      },
      "trace_id": "50b2b4a8-6c1c-4b95-ac0b-46e5b97c7b18",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "task_id": "5213468b-6b96-4ad4-9c6a-657bd438d299",
        "status": "不明",
        "data": []
      }
    }
  ],
  "count": 2
}
```

#### CURL

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/headshots/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["16f96e95-d95c-46ef-b183-139b9bd1aebd","5213468b-6b96-4ad4-9c6a-657bd438d299"],
  "action": "retrieve_batch"
}'
```

#### Python

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/headshots/tasks"

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

payload = {
    "ids": ["16f96e95-d95c-46ef-b183-139b9bd1aebd","5213468b-6b96-4ad4-9c6a-657bd438d299"],
    "action": "retrieve_batch"
}

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": "取得に失敗しました"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## 結論

この文書を通じて、AI証明写真タスクAPIを使用して、単一またはバッチの証明写真タスクのすべての具体的な詳細情報を照会する方法を理解しました。この文書がAPIの接続と使用に役立つことを願っています。ご不明な点がございましたら、いつでも技術サポートチームにお問い合わせください。