Статус и результаты
Все операции генерации работают асинхронно. После запуска вы получаете action_id и опрашиваете статус до завершения.
Жизненный цикл
pending → processing → completed
→ failed| Статус | Описание |
|---|---|
pending | В очереди, ожидает начала обработки |
processing | Генерация выполняется |
completed | Готово, результат доступен для скачивания |
failed | Ошибка, подробности в error_message |
Получить статус
GET /status/:action_id
Python
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_id | integer | ID действия |
status | string | pending, processing, completed, failed |
type | string | generate, edit, video |
result_url | string | null | Подписанная ссылка на результат (30 дней) |
result_url_expires_at | string | null | Срок действия ссылки (ISO 8601) |
error_message | string | null | Сообщение об ошибке |
created_at | string | Время создания (ISO 8601) |
completed_at | string | 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
Python
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 и
последующий статус. Зарезервированные искры освобождаются после подтверждённой
отмены.
Python
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иfailedendpoint вернётcancelled: false. Дляprocessingвозможен ответ"Cancel requested.": запрос принят, но worker ещё должен подтвердить терминальную отмену.
Список результатов
GET /results
Список ваших генераций с фильтрацией и пагинацией.
Python
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'])}")Параметры запроса:
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
type | string | — | Фильтр по типу: generate, edit, video |
status | string | — | Фильтр по статусу: pending, processing, completed, failed |
created_after | string | — | Только после этой даты (YYYY-MM-DD) |
created_before | string | — | Только до этой даты (YYYY-MM-DD) |
project_id | integer | — | Только результаты этого проекта |
client_group_id | string | — | Фильтр по корреляционному тегу, отправленному в /generate/* |
page | integer | 1 | Номер страницы (1–1000) |
page_size | integer | 20 | Размер страницы (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_id | integer | ID действия |
project_id | integer | null | Проект, в котором лежит результат |
card_id | integer | null | Карточка результата (см. Проекты и карточки) |
client_group_id | string | null | Корреляционный тег, отправленный в /generate/* |
type | string | generate, edit, video |
status | string | pending, processing, completed, failed |
result_url | string | null | Подписанная ссылка на результат (действительна 30 дней) |
result_url_expires_at | string | null | Срок действия ссылки (ISO 8601) |
storage_status | string | available — результат доступен; archived — перемещён в холодное хранилище, result_url будет null |
error_message | string | null | Сообщение об ошибке (для failed) |
created_at | string | Время создания (ISO 8601) |
completed_at | string | null | Время завершения (ISO 8601) |
Скачивание результата
GET /results/:action_id/download
Скачать результат завершённого действия. Возвращает 302 Redirect на подписанную ссылку.
Python
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
Вы можете получить результат двумя способами:
result_urlиз ответа/status/:action_id— прямая подписанная ссылка, действительна 30 дней/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; - важные результаты скачивайте в собственное хранилище после завершения.