Проекты и карточки

Раньше каждый вызов /generate/* создавал в кабинете отдельный проект — при пакетной работе UI быстро превращался в свалку. Теперь API понимает Проекты и Карточки как полноценные ресурсы.

Иерархия:

• Проект — папка-контейнер. К нему привязаны карточки и общие референсы товара.
• Карточка — одна логическая «единица результата» (один товарный кадр). В неё могут входить несколько версий: первая генерация и последующие правки.
• Action (версия) — конкретная асинхронная операция (generate или edit). У одной карточки может быть много версий, поле active_action_id указывает на активную.

На уровне ответов /generate/* теперь всегда возвращают project_id, card_id и action_id. Простому клиенту достаточно action_id (как и раньше) — продвинутый видит всю структуру.

Способы группировки

1. Авто-инбокс (по умолчанию для новых ключей)

Ничего не меняйте в запросе — все вызовы без project_id падают в один проект API Inbox — <название ключа>. Внутри он работает как обычный проект кабинета: можно открыть, посмотреть карточки, скачать, удалить.

# Просто шлём как обычно — Card попадает в API Inbox автоматически
curl -X POST https://api.aidentika.com/api/v1/public/generate/photo \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{"images": [{"url": "https://example.com/p.jpg"}]}'

2. Явный project_id

Когда нужно собирать пачку генераций под общим именем — создайте проект и передавайте его id во все генерации.

# 1. Создать проект
curl -X POST https://api.aidentika.com/api/v1/public/projects \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Клетка для животных — кампания май"}'
# => {"id": 4321, ...}
 
# 2. Слать генерации с project_id
curl -X POST https://api.aidentika.com/api/v1/public/generate/photo \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "images": [{"url": "https://example.com/p.jpg"}],
    "project_id": 4321
  }'

3. Перенос уже созданных карточек

Если генерации уже разлетелись по разным проектам — карточку можно перенести через PATCH /cards/:id.

4. Корреляция через client_group_id

Опциональное поле в /generate/*. На сервере ничего не группирует, но возвращается в webhook payload и фильтрах /results. Удобно когда вашему коду нужно агрегировать запросы пакета на стороне клиента.

{
  "images": [...],
  "project_id": 4321,
  "client_group_id": "batch-2026-05-19-cosmetics"
}

Настройка ключа

default_grouping контролирует поведение /generate/* без явного project_id. У новых ключей по умолчанию api_key_inbox. Старые ключи остались на legacy_per_request чтобы не сломать существующие интеграции — переключить можно из кабинета или через API.

Если вы не сталкивались с проблемой замусоренного списка проектов — оставьте legacy_per_request. Если сталкивались — переключитесь на api_key_inbox и при желании создавайте именованные проекты для серьёзных пакетов.

POST /projects

Создать пустой Project. Возвращает id, который можно передавать в /generate/*.

Запрос:

{
  "name": "Клетка для животных",
  "product_name": "Клетка с поддоном",
  "category_id": "home",
  "concept_id": "home_catalog",
  "comment": "Серия для маркетплейса"
}

Все поля опциональны.

Ответ (201 Created):

{
  "id": 4321,
  "name": "Клетка для животных",
  "product_name": "Клетка с поддоном",
  "category_id": "home",
  "concept_id": "home_catalog",
  "comment": "Серия для маркетплейса",
  "source": "api",
  "created_at": "2026-05-19T10:00:00Z",
  "updated_at": "2026-05-19T10:00:00Z"
}

GET /projects

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

Query-параметры:

Ответ:

{
  "items": [{ "id": 4321, "name": "...", ... }],
  "total": 12,
  "limit": 20,
  "offset": 0
}

GET /projects/:id

Содержимое проекта — карточки и все версии (Actions).

Ответ:

{
  "id": 4321,
  "name": "Клетка для животных",
  "source": "api",
  "created_at": "...",
  "updated_at": "...",
  "cards": [
    {
      "id": 999,
      "status": "completed",
      "content_type": "photo",
      "aspect_ratio": "3:4",
      "active_action_id": 5001,
      "created_at": "...",
      "updated_at": "..."
    }
  ],
  "actions": [
    {
      "id": 5001,
      "card_id": 999,
      "type": "generate",
      "status": "completed",
      "depth": 0,
      "asset_path": "...",
      "created_at": "...",
      "completed_at": "..."
    }
  ]
}

PATCH /projects/:id

Обновить метаданные проекта. Можно прислать только те поля, которые меняете.

Запрос:

{ "name": "Новое имя проекта" }

Поддерживаемые поля: name, product_name, category_id, concept_id, comment.

GET /cards/:id

Карточка с историей всех версий.

Ответ:

{
  "id": 999,
  "project_id": 4321,
  "status": "completed",
  "content_type": "photo",
  "aspect_ratio": "3:4",
  "active_action_id": 5002,
  "created_at": "...",
  "updated_at": "...",
  "actions": [
    {"id": 5001, "type": "generate", "status": "completed", "depth": 0, "asset_path": "..."},
    {"id": 5002, "type": "edit", "status": "completed", "depth": 1, "parent_action_id": 5001, "asset_path": "..."}
  ]
}

PATCH /cards/:id

Перенести карточку в другой проект — например когда генерации уже созданы, а собрать их хочется в одну папку. Назначение должно принадлежать тому же пользователю.

Запрос:

{ "project_id": 4321 }

Ответ: актуальная карточка (как GET /cards/:id) с новым project_id.