Статус и результаты
Все операции генерации работают асинхронно. После запуска вы получаете 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. Зарезервированные искры будут возвращены.
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'"
}Отмена возможна только для действий в статусе
pending. Для действий в статусеprocessing,completedилиfailedcancel вернётcancelled: false.
Список результатов
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) |
page | integer | 1 | Номер страницы (1–1000) |
page_size | integer | 20 | Размер страницы (1–100) |
Ответ:
{
"items": [
{
"action_id": 12345,
"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 действия |
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 not ready yet. Current status: processing"
}result_url vs download
Вы можете получить результат двумя способами:
result_urlиз ответа/status/:action_id— прямая подписанная ссылка, действительна 30 дней/results/:action_id/download— endpoint с redirect, генерирует новую подписанную ссылку
Используйте result_url для кеширования и прямого доступа, /download — когда нужна свежая ссылка.
Хранение результатов
Результаты генерации хранятся 30 дней с момента создания. После этого файлы удаляются и становятся недоступны для скачивания.
result_url— подписанная ссылка, действительна 30 дней с момента генерации/results/:action_id/download— генерирует новую подписанную ссылку (пока файл доступен)- После 30 дней результат удаляется безвозвратно
Рекомендуем скачивать и сохранять результаты локально сразу после генерации.