Skip to Content
API и интеграцииСтатус и результаты

Статус и результаты

Все операции генерации работают асинхронно. После запуска вы получаете action_id и опрашиваете статус до завершения.

Жизненный цикл

pending → processing → completed → failed
СтатусОписание
pendingВ очереди, ожидает начала обработки
processingГенерация выполняется
completedГотово, результат доступен для скачивания
failedОшибка, подробности в error_message

Получить статус

GET /status/:action_id

resp = requests.get(f"{BASE}/status/12345", headers=headers) data = resp.json() print(f"Статус: {data['status']}")

Ответ (в процессе):

{ "action_id": 12345, "status": "processing", "type": "generate", "result_url": null, "error_message": null, "created_at": "2026-02-23T10:00:00Z" }

Ответ (завершено):

{ "action_id": 12345, "status": "completed", "type": "generate", "result_url": "https://api.aidentika.com/api/v1/assets/...", "result_url_expires_at": "2026-03-25T10:00:00Z", "created_at": "2026-02-23T10:00:00Z", "completed_at": "2026-02-23T10:00:45Z" }

Ответ (ошибка):

{ "action_id": 12345, "status": "failed", "type": "generate", "result_url": null, "error_message": "Генерация не удалась. Попробуйте ещё раз.", "created_at": "2026-02-23T10:00:00Z", "completed_at": "2026-02-23T10:00:30Z" }

Поля ответа

ПолеТипОписание
action_idintegerID действия
statusstringpending, processing, completed, failed
typestringgenerate, edit, video
result_urlstring | nullПодписанная ссылка на результат (30 дней)
result_url_expires_atstring | nullСрок действия ссылки (ISO 8601)
error_messagestring | nullСообщение об ошибке
created_atstringВремя создания (ISO 8601)
completed_atstring | nullВремя завершения (ISO 8601)

Поле storage_status доступно только в GET /results (см. ниже).

Ошибки:

  • 403 — действие принадлежит другому пользователю
  • 404 — действие не найдено

Рекомендуемый паттерн polling

Ожидаемое время генерации

ОперацияТипичное времяМаксимум
Фото / Карточка20–60 сек2 мин
Редактирование20–40 сек2 мин
Видео (5 сек)1–3 мин5 мин
Видео (10 сек)2–5 мин7 мин

Генерация изображений занимает минимум 20 секунд, видео — минимум 40 секунд. Рекомендуем начинать polling после этого времени.

Рекомендуемые интервалы polling

  • Фото / Карточка / Редактирование: первый запрос через 20 сек, далее каждые 10 сек
  • Видео: первый запрос через 40 сек, далее каждые 15 сек
  • Для видео рекомендуется использовать webhooks вместо polling
import time import requests def wait_for_result(action_id, headers, is_video=False, timeout=300): """Ждать завершения генерации.""" base_url = "https://api.aidentika.com/api/v1/public" interval = 15 if is_video else 10 initial_wait = 40 if is_video else 20 # Не опрашивать раньше, чем результат может быть готов time.sleep(initial_wait) elapsed = initial_wait while elapsed < timeout: resp = requests.get(f"{base_url}/status/{action_id}", headers=headers) data = resp.json() if data["status"] == "completed": return data if data["status"] == "failed": raise Exception(f"Генерация не удалась: {data.get('error_message')}") time.sleep(interval) elapsed += interval raise TimeoutError(f"Генерация не завершилась за {timeout} секунд")

Отмена генерации

POST /cancel/:action_id

Запросить отмену генерации в статусе pending или processing. Для уже запущенной работы отмена выполняется best-effort; проверяйте поле cancelled и последующий статус. Зарезервированные искры освобождаются после подтверждённой отмены.

resp = requests.post(f"{BASE}/cancel/12345", headers=headers) print(resp.json())

Ответ (успешно):

{ "action_id": 12345, "cancelled": true, "message": "Action cancelled. Tokens will be released." }

Ответ (нельзя отменить):

{ "action_id": 12345, "cancelled": false, "message": "Cannot cancel: action is already 'completed'" }

Для completed и failed endpoint вернёт cancelled: false. Для processing возможен ответ "Cancel requested.": запрос принят, но worker ещё должен подтвердить терминальную отмену.


Список результатов

GET /results

Список ваших генераций с фильтрацией и пагинацией.

resp = requests.get(f"{BASE}/results", headers=headers, params={ "status": "completed", "page": 1, "page_size": 20, }) data = resp.json() print(f"Всего: {data['total']}, на странице: {len(data['items'])}")

Параметры запроса:

ПараметрТипПо умолчаниюОписание
typestringФильтр по типу: generate, edit, video
statusstringФильтр по статусу: pending, processing, completed, failed
created_afterstringТолько после этой даты (YYYY-MM-DD)
created_beforestringТолько до этой даты (YYYY-MM-DD)
project_idintegerТолько результаты этого проекта
client_group_idstringФильтр по корреляционному тегу, отправленному в /generate/*
pageinteger1Номер страницы (1–1000)
page_sizeinteger20Размер страницы (1–100)

Ответ:

{ "items": [ { "action_id": 12345, "project_id": 678, "card_id": 999, "client_group_id": "batch-2026-05-19-cosmetics", "type": "generate", "status": "completed", "result_url": "https://api.aidentika.com/api/v1/assets/...", "result_url_expires_at": "2026-03-25T10:00:00Z", "storage_status": "available", "error_message": null, "created_at": "2026-02-23T10:00:00Z", "completed_at": "2026-02-23T10:00:45Z" } ], "total": 42, "page": 1, "page_size": 20, "total_pages": 3 }

Поля элемента

ПолеТипОписание
action_idintegerID действия
project_idinteger | nullПроект, в котором лежит результат
card_idinteger | nullКарточка результата (см. Проекты и карточки)
client_group_idstring | nullКорреляционный тег, отправленный в /generate/*
typestringgenerate, edit, video
statusstringpending, processing, completed, failed
result_urlstring | nullПодписанная ссылка на результат (действительна 30 дней)
result_url_expires_atstring | nullСрок действия ссылки (ISO 8601)
storage_statusstringavailable — результат доступен; archived — перемещён в холодное хранилище, result_url будет null
error_messagestring | nullСообщение об ошибке (для failed)
created_atstringВремя создания (ISO 8601)
completed_atstring | nullВремя завершения (ISO 8601)

Скачивание результата

GET /results/:action_id/download

Скачать результат завершённого действия. Возвращает 302 Redirect на подписанную ссылку.

result = requests.get( f"{BASE}/results/12345/download", headers=headers, allow_redirects=True, ) with open("result.png", "wb") as f: f.write(result.content) print("Результат сохранён в result.png")

Если генерация ещё не завершена, вернётся JSON:

{ "status": "processing", "message": "Result is not ready yet" }

result_url vs download

Вы можете получить результат двумя способами:

  1. result_url из ответа /status/:action_id — прямая подписанная ссылка, действительна 30 дней
  2. /results/:action_id/download — endpoint с redirect, генерирует новую подписанную ссылку

Используйте result_url для кеширования и прямого доступа, /download — когда нужна свежая ссылка.


Срок ссылки и хранение результата

result_url — подписанная ссылка со сроком действия до 30 дней. Это не равно сроку хранения самого проекта: политика хранения зависит от состояния аккаунта и может меняться отдельно.

  • используйте result_url_expires_at, а не вычисляйте expiry на клиенте;
  • /status/:action_id и /results/:action_id/download выдают свежую ссылку, пока исходный asset ещё хранится;
  • если storage_status равен archived, result_url в списке будет null;
  • важные результаты скачивайте в собственное хранилище после завершения.