Генерация

Все эндпоинты генерации работают асинхронно: вы отправляете запрос, получаете action_id, затем опрашиваете статус до завершения. Опционально можно указать webhook_url для получения уведомления.

Авто-определение

Все параметры генерации кроме images — опциональны. Если category_id, concept_id или product_name не указаны, они определяются автоматически по фото товара с помощью AI.

Минимальный запрос для генерации:

{"images": [{"url": "https://example.com/product.jpg"}]}

Для предварительного анализа товара без генерации используйте POST /analyze.

POST /analyze

Анализ фото товара — определение категории, названия и ключевых качеств. Бесплатно (не тратит искры).

Запрос:

{
  "image": {"url": "https://example.com/product.jpg"}
}

Ответ:

{
  "category_id": "cosmetics",
  "product_name": "Крем для лица",
  "qualities": [
    "Натуральный состав",
    "Увлажняющий эффект",
    "Стеклянная баночка"
  ]
}

Результат можно использовать в запросе генерации. Поле qualities удобно передать как comment (для фото) или user_text (для карточек) через "\n".join(qualities).

Загрузка изображения

POST /upload

Загрузите изображение один раз и используйте upload_id в нескольких запросах генерации. Полезно, если нужно сгенерировать несколько вариантов для одного товара.

Запрос:

{
  "image": {
    "data": "BASE64_ДАННЫЕ_ИЗОБРАЖЕНИЯ",
    "media_type": "image/jpeg"
  }
}

Ответ:

{
  "upload_id": "upl_aBcDeFgHiJkLmNoP",
  "expires_in": 3600
}

Загрузка действительна 1 час. Максимум 20 активных загрузок на аккаунт.

Использование upload_id

Вместо base64-данных передавайте upload_id в поле data:

{
  "images": [{"data": "upl_aBcDeFgHiJkLmNoP", "media_type": "image/jpeg"}]
}

Формат изображений

Изображения можно передать тремя способами. Укажите одно из полей url или data:

Примеры:

// Вариант 1: URL
{"url": "https://example.com/product.jpg"}
 
// Вариант 2: Base64
{"data": "iVBORw0KGgo...", "media_type": "image/jpeg"}
 
// Вариант 3: Upload ID (для переиспользования)
{"data": "upl_aBcDeFgHiJkLmNoP"}

Поддерживаемые форматы: JPEG, PNG, WebP, HEIC (автоконвертация). Максимальный размер: 15 МБ.

Генерация фото

POST /generate/photo

Генерация продуктового фото на основе референсных изображений товара.

Запрос:

{
  "images": [
    {"url": "https://example.com/product-front.jpg"},
    {"url": "https://example.com/product-side.jpg"}
  ],
  "category_id": "cosmetics",
  "concept_id": "cosmetics_catalog",
  "product_name": "Крем для лица",
  "comment": "На белом фоне с каплями воды",
  "photo_style": "classic",
  "aspect_ratio": "3:4",
  "webhook_url": "https://example.com/webhook"
}

Если category_id, concept_id или product_name не указаны — они определяются автоматически по фото товара. Минимальный запрос: {"images": [{"url": "..."}]}.

Соотношения сторон: 9:16, 4:3, 1:1, 16:9, 3:4

Стоимость: 4 искры | Время: 20–60 сек (типичное)

Ответ:

{
  "action_id": 12345,
  "status": "pending",
  "poll_url": "/api/v1/public/status/12345",
  "project_id": 678,
  "detected": {
    "category_id": "cosmetics",
    "concept_id": "cosmetics_composition",
    "product_name": "Крем для лица"
  }
}

Поле detected присутствует только когда были авто-определены хотя бы один параметр. Если все параметры указаны явно — detected отсутствует.

Категории и концепты

Список всех доступных категорий и концептов можно получить через GET /categories (подробнее). Основные категории:

Каждая категория имеет несколько концептов съёмки (например, cosmetics_catalog, cosmetics_in_use, cosmetics_lifestyle).

Генерация карточки

POST /generate/card

Генерация карточки товара / инфографики с текстом и дизайном.

Запрос:

{
  "images": [
    {"url": "https://example.com/product.jpg"}
  ],
  "category_id": "cosmetics",
  "concept_id": "infographic",
  "product_name": "Крем для лица",
  "user_text": "Натуральный состав\nУвлажнение 24 часа\nБез парабенов",
  "design_key": "modern_light",
  "creativity": 0.5,
  "aspect_ratio": "3:4",
  "webhook_url": "https://example.com/webhook"
}

creativity:

• 0.0 — точная копия стиля референса
• 0.5 — баланс точности и креативности
• 1.0 — свободная интерпретация

Стоимость: 4 искры | Время: 20–60 сек (типичное)

Генерация видео

POST /generate/video

Создание короткого видеоролика на основе одного изображения.

Запрос:

{
  "image": {"url": "https://example.com/product.jpg"},
  "scenario": "Камера плавно приближается к товару, капли воды падают на упаковку",
  "duration_sec": 5,
  "loop_mode": false,
  "card_mode": false,
  "aspect_ratio": "3:4",
  "webhook_url": "https://example.com/webhook"
}

Стоимость: 16 искр (5 сек) / 32 искры (10 сек) | Время: 1–5 мин

Генерация видео занимает значительно больше времени (1–5 минут). Рекомендуется использовать webhooks вместо polling.

Редактирование

POST /edit/:action_id

Редактирование ранее сгенерированного изображения по текстовой инструкции.

Запрос:

{
  "instruction": "Сделай фон более ярким и добавь мягкие тени",
  "webhook_url": "https://example.com/webhook"
}

Ответ:

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

Стоимость: 2 искры | Время: 20–40 сек (типичное)

Ограничения:

• Можно редактировать только завершённые действия (status: "completed")
• Максимальная глубина редактирований: 99
• Действие должно принадлежать вашему аккаунту

Ad-hoc Webhook

Все эндпоинты генерации принимают необязательный параметр webhook_url — одноразовый webhook для конкретного запроса. При завершении генерации на этот URL будет отправлен POST-запрос с результатом.

Это удобная альтернатива зарегистрированным webhooks для простых интеграций.

• URL должен использовать HTTPS
• Без retry (одна попытка)
• Payload аналогичен зарегистрированным webhooks

Пример: полный цикл

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. Запустить генерацию
resp = requests.post(f"{BASE}/generate/photo", headers=headers, json={
    "images": [{"url": "https://example.com/product.jpg"}],
    "category_id": "cosmetics",
    "concept_id": "cosmetics_catalog",
    "product_name": "Крем для лица",
})
action_id = resp.json()["action_id"]
print(f"Генерация запущена: action_id={action_id}")
 
# 2. Ждать результат (первый запрос не раньше 20 сек)
time.sleep(20)
while True:
    status = requests.get(f"{BASE}/status/{action_id}", headers=headers).json()
    if status["status"] in ("completed", "failed"):
        break
    print(f"  Статус: {status['status']}")
    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')}")

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. Запустить генерацию
const genResp = await fetch(`${BASE}/generate/photo`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    images: [{ url: "https://example.com/product.jpg" }],
    category_id: "cosmetics",
    concept_id: "cosmetics_catalog",
    product_name: "Крем для лица",
  }),
});
const { action_id } = await genResp.json();
console.log(`Генерация запущена: action_id=${action_id}`);
 
// 2. Ждать результат (первый запрос не раньше 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();
  if (["completed", "failed"].includes(status.status)) break;
  console.log(`  Статус: ${status.status}`);
  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}`);
}

# 1. Запустить генерацию
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.jpg"}],
    "category_id": "cosmetics",
    "concept_id": "cosmetics_catalog",
    "product_name": "Крем для лица"
  }'
# => {"action_id": 12345, "status": "pending", ...}
 
# 2. Проверить статус (повторять пока status != "completed")
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