> ## 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 для завантаження AI фото на документи: інтеграція та використання

> AI ID Photo Production 集成指南 - XHuoAPI

Основна функція API для завантаження AI фото на документи полягає в тому, щоб за допомогою введеного ID завдання, згенерованого API для створення AI фото на документи, перевірити стан виконання цього завдання.

Цей документ детально описує інтеграцію API для завантаження AI фото на документи, щоб допомогти вам легко інтегрувати та повністю використовувати потужні можливості цього API. За допомогою API для завантаження AI фото на документи ви можете легко реалізувати перевірку стану виконання завдань API для створення AI фото на документи.

## Процес подачі заявки

Щоб використовувати API для завантаження AI фото на документи, спочатку потрібно перейти на сторінку подачі заявки [API для створення AI фото на документи](https://api.xhuoapi.ai/documents/bf7214a3-8447-4157-8a75-f5bb39d5ed1b) та подати заявку на відповідну послугу, а потім скопіювати ID завдання API для створення AI фото на документи, як показано на малюнку:

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

Нарешті, перейдіть на сторінку Tasks API [API для завантаження AI фото на документи](https://api.xhuoapi.ai/documents/3a23ee34-8689-406b-9042-7954224348ad) та подайте заявку на відповідну послугу, після входу на сторінку натисніть кнопку «Acquire», як показано на малюнку:

![Сторінка подачі заявки](https://cdn.xhuoapi.ai/rci31i.png)

Якщо ви ще не увійшли в систему або не зареєструвалися, вас автоматично перенаправлять на [сторінку входу](https://api.xhuoapi.ai), щоб запросити вас зареєструватися та увійти. Після входу або реєстрації ви автоматично повернетеся на поточну сторінку.

При першій подачі заявки вам буде надано безкоштовний ліміт, який дозволяє безкоштовно використовувати цей API.

## Приклад запиту

API для завантаження AI фото на документи можна використовувати для перевірки результатів API для створення AI фото на документи. Щоб дізнатися, як використовувати API для створення AI фото на документи, будь ласка, зверніться до документа [API для створення AI фото на документи](https://api.xhuoapi.ai/documents/d6ea75a4-836e-490a-aee5-7ca911a808fd).

Розглянемо приклад з ID завдання, повернутим сервісом API для створення AI фото на документи. Припустимо, у нас є ID завдання: `16f96e95-d95c-46ef-b183-139b9bd1aebd`, далі демонструємо, як передати ID завдання.

### Приклад завдання

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

### Налаштування заголовків запиту та тіла запиту

**Request Headers** включає:

* `accept`: вказує на прийняття відповіді у форматі JSON, тут вказується `application/json`.
* `authorization`: ключ для виклику API, після подачі заявки можна вибрати безпосередньо з випадаючого списку.

**Request Body** включає:

* `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.

**Request Body** включає:

* `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": "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": "男形象照"
          }
        ]
      }
    },
    {
      "_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": "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": "50b2b4a8-6c1c-4b95-ac0b-46e5b97c7b18",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "task_id": "5213468b-6b96-4ad4-9c6a-657bd438d299",
        "status": "unknown",
        "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": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## Висновок

За допомогою цього документа ви дізналися, як використовувати API завдань AI для отримання інформації про окремі або пакетні завдання з фотографіями. Сподіваємося, що цей документ допоможе вам краще інтегрувати та використовувати цей API. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої технічної підтримки.