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

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

Щоб використовувати API, спочатку потрібно перейти на сторінку API для створення AI фотографій документів та подати заявку на відповідну послугу. Після переходу на сторінку натисніть кнопку «Acquire», як показано на малюнку: Якщо ви ще не увійшли в систему або не зареєстровані, вас автоматично перенаправлять на сторінку входу, щоб запросити реєстрацію та вхід. Після входу або реєстрації ви будете автоматично повернені на поточну сторінку. При першій подачі заявки вам буде надано безкоштовний ліміт, який дозволяє безкоштовно використовувати цей API.

​
Основне використання

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

Потім нам потрібно ввести обраний шаблон. У цьому документі представлено вісім популярних шаблонів, конкретні шаблони можна знайти нижче: 
{
   "male_portrait":  Чоловіча фотографія
   "male_portrait2":  Чоловіча фотографія (інша версія)
   "kindergarten":  Фотографія для дитячого садка
   "logo_tshirt": Фотографія з логотипом компанії на футболці
   "wedding":  Фотографія для реєстрації шлюбу
   "business_photo":  Бізнес-фотографія
   "bob_suit": Чорний костюм з бобом
   "female_portrait":  Жіноча фотографія
}
Після цього ми також можемо вказати параметр швидкості генерації mode, який зазвичай ділиться на два типи: повільний relax та швидкий fast, конкретний зміст наведено нижче:

Ми можемо бачити, що тут ми налаштували заголовки запиту, включаючи:
  • accept: вказує, в якому форматі ви хочете отримати відповідь, тут вказано application/json, тобто формат JSON.
  • authorization: ключ для виклику API, після подачі заявки ви можете вибрати його зі списку.
Крім того, налаштовано тіло запиту, яке включає:
  • mode: канал для генерації фотографії документів, основні типи - швидкий fast та повільний relax, при використанні relax настійно рекомендується використовувати нижче наведений параметр callback_url.
  • template: стиль шаблону фотографії документів.
  • image_urls: посилання на фотографії документів, які потрібно завантажити.
  • callback_url: URL для отримання результатів.
Після вибору ви можете помітити, що праворуч також згенеровано відповідний код, як показано на малюнку:

Натисніть кнопку «Try», щоб провести тестування, як показано на малюнку, і ви отримаєте наступний результат: 
{
  "success": true,
  "task_id": "ae1e4948-dba1-4a6f-87af-67961b647428",
  "data": [
    {
      "id": "202411031951124776",
      "image_url": "https://platform.cdn.acedata.cloud/headshots/ae1e4948-dba1-4a6f-87af-67961b647428.png",
      "template": "Чоловіча фотографія"
    },
    {
      "id": "202411031951128490",
      "image_url": "https://platform.cdn.acedata.cloud/headshots/ae1e4948-dba1-4a6f-87af-67961b647428.png",
      "template": "Чоловіча фотографія"
    }
  ]
}
У повернутому результаті є кілька полів, описаних нижче:
  • success: статус завдання на генерацію фотографії документів.
  • task_id: ID завдання на генерацію фотографії документів.
  • data: список результатів завдання на генерацію фотографії документів.
    • id: ID фотографії завдання на генерацію фотографії документів.
    • image_url: посилання на зображення завдання на генерацію фотографії документів.
    • template: назва шаблону фотографії документів завдання.
Ми можемо бачити, що отримали задовільну інформацію про фотографію документів на основі шаблону та портретного зображення, нам потрібно лише отримати фотографію документів за адресою посилання з data. Крім того, якщо ви хочете згенерувати відповідний код інтеграції, ви можете просто скопіювати його, наприклад, код CURL виглядає так: 
curl -X POST 'https://api.acedata.cloud/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 відразу поверне результат, що містить інформацію про поле task_id, яке представляє ID поточного завдання. Коли завдання завершено, результат генерації фотографії документів буде надіслано на вказаний клієнтом callback_url у форматі POST JSON, в якому також буде включено поле task_id, таким чином результати завдання можна буде пов’язати за ID. Давайте розглянемо приклад, щоб зрозуміти, як це працює. По-перше, Webhook зворотний виклик - це служба, яка може приймати HTTP запити, розробники повинні замінити на URL свого власного HTTP сервера. Для зручності демонстрації використовується публічний веб-сайт з прикладом Webhook https://webhook.site/, відкривши цей сайт, ви отримаєте URL Webhook, як показано на малюнку: Скопіюйте цей URL, і ви зможете використовувати його як Webhook, приклад тут: https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a. Далі ми можемо налаштувати поле callback_url на вказаний Webhook URL, а також ввести посилання на зображення портрету та шаблон. У цьому документі рекомендується використовувати асинхронний зворотний виклик, коли параметр mode є relax, конкретний зміст наведено на малюнку:

Натиснувши «Запустити», ви отримаєте результат, як показано нижче: 
{
  "task_id": "763b1450-8804-434f-acc7-d713be73a28f"
}
Через деякий час ви зможете спостерігати результати генерації на https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a, як показано на малюнку: Зміст нижче: 
{
    "success": true,
    "task_id": "763b1450-8804-434f-acc7-d713be73a28f",
    "data": [
        {
            "id": "202411032010131366",
            "image_url": "https://platform.cdn.acedata.cloud/headshots/763b1450-8804-434f-acc7-d713be73a28f.png",
            "template": "чоловіче зображення"
        },
        {
            "id": "202411032010132420",
            "image_url": "https://platform.cdn.acedata.cloud/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: Внутрішня помилка сервера, щось пішло не так на сервері.

​
Приклад відповіді на помилку

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "не вдалося отримати"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
Висновок

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