Public API

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

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

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

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

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

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

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

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


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

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


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

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

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

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

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

По URL


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

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

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

Python


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')}")

JavaScript


import fs from "fs";
 
const API_KEY = "ak_ваш_ключ";
const BASE = "https://api.aidentika.com/api/v1/public";
const headers = {
  Authorization: `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
};
 
// 1. Запустить генерацию (несколько фото товара по URL)
const genResp = await fetch(`${BASE}/generate/photo`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    images: [
      { url: "https://example.com/product-front.jpg" },
      { url: "https://example.com/product-side.jpg" },
    ],
    category_id: "cosmetics",
    concept_id: "cosmetics_catalog",
    product_name: "Крем для лица",
  }),
});
const { action_id } = await genResp.json();
console.log(`Генерация запущена: action_id=${action_id}`);
 
// Альтернатива — передать base64:
// const images = ["front.jpg", "side.jpg"].map((f) => ({
//   data: fs.readFileSync(f).toString("base64"),
//   media_type: "image/jpeg",
// }));
// images: images
 
// 2. Ждать результат (polling, первый запрос не раньше 20 сек)
await new Promise((r) => setTimeout(r, 20000));
let status;
while (true) {
  const resp = await fetch(`${BASE}/status/${action_id}`, { headers });
  status = await resp.json();
  console.log(`  Статус: ${status.status}`);
  if (["completed", "failed"].includes(status.status)) break;
  await new Promise((r) => setTimeout(r, 10000));
}
 
// 3. Скачать результат
if (status.status === "completed") {
  const img = await fetch(`${BASE}/results/${action_id}/download`, { headers });
  fs.writeFileSync("result.png", Buffer.from(await img.arrayBuffer()));
  console.log("Результат сохранён в result.png");
} else {
  console.error(`Ошибка: ${status.error_message}`);
}

cURL


# 1. Запустить генерацию (несколько фото товара по URL)
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": "Крем для лица"
  }'
# => {"action_id": 12345, "status": "pending", ...}
 
# Альтернатива — base64:
# "images": [
#   {"data": "BASE64_ФОТО_1", "media_type": "image/jpeg"},
#   {"data": "BASE64_ФОТО_2", "media_type": "image/jpeg"}
# ]
 
# 2. Проверить статус (подождать ~20 сек, повторять каждые 10 сек)
curl https://api.aidentika.com/api/v1/public/status/12345 \
  -H "Authorization: Bearer ak_ваш_ключ"
# => {"action_id": 12345, "status": "completed", ...}
 
# 3. Скачать результат
curl -L https://api.aidentika.com/api/v1/public/results/12345/download \
  -H "Authorization: Bearer ak_ваш_ключ" \
  -o result.png

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

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

Генерация

Метод	Путь	Описание	Стоимость
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

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

Аутентификация — API-ключи, rate limiting
Генерация — фото, карточки, видео, редактирование
Статус и результаты — polling, отмена, скачивание
AI-помощники — тексты, сценарии
Webhooks — уведомления о завершении генерации
Информация — баланс, цены, категории
Ошибки и лимиты — формат ошибок, HTTP-коды