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

Public API

Aidentika Public API позволяет программно генерировать фотографии товаров, карточки/инфографику, видео, а также использовать AI-помощников для создания текстов и сценариев.

API соответствует спецификации OpenAPI 3.1 — интерактивная документация доступна в Swagger UI  и ReDoc .

Быстрый старт

1. Создайте API-ключ

  1. Зарегистрируйтесь или войдите на app.aidentika.com 
  2. Откройте Профиль → API
  3. Нажмите «Создать ключ» — ключ можно скопировать в любой момент из кабинета

Что такое API-ключ? Это секретный токен формата ak_..., который идентифицирует ваши запросы. Не передавайте его третьим лицам и не храните в коде — используйте переменные окружения.

2. Настройте подключение

Base URL для всех запросов:

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

Ключ передаётся в заголовке каждого запроса:

Authorization: Bearer ak_ваш_ключ

3. Сделайте первый запрос

Все генерации работают асинхронно: вы отправляете запрос → получаете action_id → опрашиваете статус → скачиваете результат. Генерация фото/карточки занимает 20–60 секунд, видео — 1–5 минут.

Изображения можно передать двумя способами: по URL или в base64.

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

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/product-front.jpg"}, {"url": "https://example.com/product-side.jpg"} ], "category_id": "cosmetics", "concept_id": "cosmetics_catalog", "product_name": "Крем для лица" }'

Ответ (201 Created):

{ "action_id": 12345, "status": "pending", "poll_url": "/api/v1/public/status/12345" }

Проверить статус:

curl https://api.aidentika.com/api/v1/public/status/12345 \ -H "Authorization: Bearer ak_ваш_ключ"

Ответ (когда генерация завершена):

{ "action_id": 12345, "status": "completed", "type": "generate", "result_url": "https://api.aidentika.com/api/v1/assets/..." }

Скачать результат:

curl -L https://api.aidentika.com/api/v1/public/results/12345/download \ -H "Authorization: Bearer ak_ваш_ключ" \ -o result.png

Полный пример

Готовый скрипт — скопируйте, подставьте свой ключ и запустите:

import requests import time API_KEY = "ak_ваш_ключ" BASE = "https://api.aidentika.com/api/v1/public" headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json", } # 1. Запустить генерацию (несколько фото товара по URL) resp = requests.post(f"{BASE}/generate/photo", headers=headers, json={ "images": [ {"url": "https://example.com/product-front.jpg"}, {"url": "https://example.com/product-side.jpg"}, ], "category_id": "cosmetics", "concept_id": "cosmetics_catalog", "product_name": "Крем для лица", }) action_id = resp.json()["action_id"] print(f"Генерация запущена: action_id={action_id}") # Альтернатива — передать base64 вместо URL: # import base64 # images = [] # for path in ["front.jpg", "side.jpg"]: # with open(path, "rb") as f: # images.append({"data": base64.b64encode(f.read()).decode(), "media_type": "image/jpeg"}) # "images": images # 2. Ждать результат (polling, первый запрос не раньше 20 сек) time.sleep(20) while True: status = requests.get(f"{BASE}/status/{action_id}", headers=headers).json() print(f" Статус: {status['status']}") if status["status"] in ("completed", "failed"): break time.sleep(10) # 3. Скачать результат if status["status"] == "completed": result = requests.get( f"{BASE}/results/{action_id}/download", headers=headers, allow_redirects=True, ) with open("result.png", "wb") as f: f.write(result.content) print("Результат сохранён в result.png") else: print(f"Ошибка: {status.get('error_message')}")

Вместо polling можно использовать webhooks — API сам отправит POST-запрос на ваш URL когда генерация завершится.


Группировка генераций в проекты

Чтобы серия запросов не разлеталась по отдельным проектам в кабинете, API понимает три способа группировки:

  1. Авто-инбокс (рекомендуется, включён по умолчанию для новых ключей). Все вызовы /generate/* без project_id падают в один автоматический проект API Inbox — <название ключа>. Кабинет не засоряется тысячами проектов.
  2. Явный project_id. Создайте проект через POST /projects и передавайте его id в /generate/*. Все новые карточки добавляются в этот проект.
  3. Перенос задним числом через PATCH /cards/{id} — если генерации уже созданы и их хочется собрать в одну папку.

Поведение по умолчанию настраивается прямо на API-ключе: default_grouping = "api_key_inbox" (новые ключи) или "legacy_per_request" (старые ключи — один проект на каждый запрос). Сменить режим можно через настройки ключа.

Дополнительно у любого /generate/* есть необязательный client_group_id — корреляционный тег, который возвращается в webhook’ах и фильтрах /results. На сервере он ничего не группирует, удобен чтобы клиентский код агрегировал результаты пачки.


Идемпотентность

Любой POST /generate/* принимает заголовок Idempotency-Key. Если клиент повторит запрос с тем же ключом в течение 5 минут, сервер вернёт исходный ответ и не спишет искры повторно. Используйте уникальный ключ на каждую логическую операцию (например uuid4) — это закрывает таймауты сети и автоматические retry.

Idempotency-Key: a8c3f1e2-4d5b-4a7e-9b1f-3e0d2c1a5b7e

Допустимые символы: латиница, цифры, -, _, ., :. Длина — до 128 символов.


Все эндпоинты

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

МетодПутьОписание
POST/projectsСоздать проект-контейнер
GET/projectsСписок своих проектов
GET/projects/:idСодержимое проекта (карточки, версии)
POST/projects/:idПереименовать / обновить мета (PATCH)
GET/cards/:idКарточка + история версий
POST/cards/:idПереместить карточку в другой проект (PATCH)

Генерация

МетодПутьОписаниеСтоимость
POST/analyzeАнализ товара (категория, название, качества)
POST/generate/photoГенерация фото товара4 искры
POST/generate/cardГенерация карточки/инфографики4 искры
POST/generate/videoГенерация видео5 сек — 16 искр, 10 сек — 32 искры
POST/edit/:action_idРедактирование результата2 искры
POST/uploadЗагрузка изображения для переиспользования

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

МетодПутьОписание
GET/status/:action_idПолучить статус генерации
POST/cancel/:action_idОтменить генерацию
GET/resultsСписок результатов генераций
GET/results/:action_id/downloadСкачать результат

AI-помощники

100 обращений в день бесплатно, далее 1 искра за каждые 20 обращений. Подробнее

МетодПутьОписание
POST/wishes/suggestГенерация маркетингового текста
POST/video/suggest-scenarioГенерация сценария для видео
GET/helpers/usageТекущее использование помощников за день

Информация

МетодПутьОписание
GET/balanceБаланс искр
GET/pricingСтоимость операций
GET/categoriesКатегории товаров и концепты

Webhooks

МетодПутьОписание
POST/webhooksЗарегистрировать webhook
GET/webhooksСписок webhooks
DELETE/webhooks/:idУдалить webhook

Разделы документации