Skip to Content
API и интеграцииFunnel API v1

Funnel API v1

Funnel-сессия создаёт одну товарную карточку пошагово. Распознанный товар, вопросы, идеи и настройки сохраняются в funnel_id, поэтому клиенту не нужно повторять весь контекст в каждом запросе.

Base URL: https://api.aidentika.com/api/v1/public

Все запросы используют Authorization: Bearer ak_.... Endpoint доступен, когда на окружении включён FUNNEL_ENABLED; иначе возвращается 503 с кодом funnel_disabled.

Поток

POST /funnels
  ├─ POST /funnels/{id}/idea      (необязательно, можно повторять)
  ├─ POST /funnels/{id}/setup     (необязательно)
  └─ POST /funnels/{id}/generate
       └─ GET /status/{action_id} или GET /funnels/{id}

Шаги idea и setup можно пропустить.

1. Начать сессию

POST /funnels

Загружает от 1 до 6 фото, распознаёт товар и сразу возвращает вопросы. Endpoint поддерживает заголовок Idempotency-Key и ограничен примерно 6 запросами в минуту.

{
  "images": [{"url": "https://example.com/product.jpg"}],
  "locale": "ru",
  "product_name": "Крем для рук",
  "category_id": "cosmetics",
  "description": "Натуральный состав, для сухой кожи"
}

Вместо URL можно передать base64:

{
  "images": [
    {"data": "BASE64_БЕЗ_DATA_PREFIX", "media_type": "image/jpeg"}
  ]
}
ПолеОбязательноеОписание
imagesда1–6 изображений (url либо data + media_type)
localeнетru, en или es
product_nameнетАвторитетное название товара
category_idнетapparel, wearables, food, cosmetics, gadgets, home, other
descriptionнетДополнительные факты о товаре, до 10 000 символов

Ответ:

{
  "funnel_id": 123,
  "project_id": 456,
  "product": {
    "name": "Крем для рук",
    "category_id": "cosmetics",
    "known_facts": ["объём 50 мл"]
  },
  "questions": [
    {
      "id": 0,
      "question": "Для какого типа кожи?",
      "options": ["сухая", "жирная"]
    }
  ],
  "next_steps": ["idea", "setup", "generate"]
}

2. Добавить идею

POST /funnels/:funnel_id/idea

Body не требуется. Один вызов создаёт одну идею и добавляет её в пул. В пуле может быть до 10 идей; endpoint ограничен примерно 10 запросами в минуту.

{
  "idea_id": "ide_a1b2c3d4e5f60708",
  "idea": "Крупный план текстуры",
  "text": "Увлажнение 24 часа",
  "scene": "студийный свет",
  "pool_size": 2,
  "next_steps": ["setup", "generate"]
}

Сохраните idea_id, если хотите выбрать эту идею при генерации.

3. Настроить сессию

POST /funnels/:funnel_id/setup

{
  "aspect_ratio": "3:4",
  "resolution": "2K",
  "card_style": "infographic",
  "design_by_reference": true,
  "refs": {
    "design": [{"url": "https://example.com/style.jpg"}],
    "model": [{"url": "https://example.com/model.jpg"}],
    "environment": [{"url": "https://example.com/background.jpg"}]
  }
}
ПолеОписание
aspect_ratio9:16, 4:3, 1:1, 16:9, 3:4; по умолчанию 3:4
resolution1K, 2K, 4K; сохраняется и возвращается в состоянии сессии
card_styleinfographic или cinematic
design_by_referenceИспользовать design reference при infographic
refs.designДо 3 стилевых референсов; несовместимо с cinematic
refs.modelДо 3 фото модели, добавляются к product refs
refs.environmentДо 3 фото окружения, добавляются к product refs
{
  "ok": true,
  "aspect_ratio": "3:4",
  "resolution": "2K",
  "card_style": "infographic",
  "design_by_reference": true,
  "design_ref_count": 1,
  "model_ref_count": 1,
  "environment_ref_count": 1,
  "next_steps": ["idea", "generate"]
}

4. Запустить генерацию

POST /funnels/:funnel_id/generate

Передайте ответы на вопросы и, при необходимости, выбранную идею.

{
  "answers": [{"question_id": 0, "answer": "сухая"}],
  "idea_id": "ide_a1b2c3d4e5f60708",
  "wishes": "Минимализм, светлый фон"
}

Идея выбирается в таком порядке:

  1. idea_id из пула;
  2. inline override через idea / text;
  3. последняя идея пула;
  4. генерация без отдельной идеи.

Endpoint ограничен примерно 10 запросами в минуту.

{
  "action_id": 789,
  "status": "pending",
  "poll_url": "/api/v1/public/status/789",
  "funnel_id": 123,
  "card_id": 111,
  "project_id": 456,
  "first_check_after_sec": 20
}

Дальше опрашивайте GET /status/{action_id} до completed / failed или получайте агрегат сессии через GET /funnels/{funnel_id}.

Состояние сессии

GET /funnels/:funnel_id

Ответ содержит выполненные шаги, товар, вопросы, пул идей, настройки и последнюю генерацию:

{
  "funnel_id": 123,
  "project_id": 456,
  "completed": ["start", "idea", "generate"],
  "next_steps": ["setup", "generate"],
  "product": {
    "name": "Крем для рук",
    "category_id": "cosmetics",
    "known_facts": ["объём 50 мл"]
  },
  "questions": [],
  "ideas": [],
  "aspect_ratio": "3:4",
  "resolution": "2K",
  "card_style": "infographic",
  "design_by_reference": true,
  "action_id": 789,
  "status": "completed",
  "result_url": "https://...",
  "result_url_expires_at": "2026-08-30T00:00:00Z",
  "error_message": null
}

Ошибки

Ошибки используют общую оболочку FastAPI:

{
  "detail": {
    "error": "start_required",
    "message": "Session not started — call POST /public/funnels first"
  }
}
HTTPdetail.errorПричина
400start_failed, unsupported_parameterНе удалось начать сессию или несовместимы параметры
401 / 403auth / forbiddenНет ключа или сессия принадлежит другому пользователю
404not_found, unknown_ideaНет сессии или выбранной идеи
409start_required, idea_pool_fullНарушен порядок шагов или пул заполнен
422validation detailНевалидная категория или тело запроса
502intake_failed, idea_failedСбой распознавания или генерации идеи
503funnel_disabledFunnel API выключен на окружении

Пример cURL

curl -X POST https://api.aidentika.com/api/v1/public/funnels \
  -H "Authorization: Bearer ak_ваш_ключ" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-42-start" \
  -d '{"images":[{"url":"https://example.com/product.jpg"}],"locale":"ru"}'
Ошибки и лимитыГенерация