Документація API

API підключає Товарку до вашого сайту, CRM чи складу. Ви надсилаєте фото товару, а сервіс повертає посилання на кадри й опис українською та російською. API доступний на тарифі Enterprise.

Швидкий старт

Базова адреса: https://aiproduct.com.ua/api/v1. Запити надсилайте зі свого сервера, а ключ тримайте в змінній середовища.

1. Створіть товар із фото

Додайте від 1 до 3 фото в поле images. AI розпізнає товар і заповнить факти про нього, це безкоштовно і займає до хвилини.

curl https://aiproduct.com.ua/api/v1/products \
  -H "Authorization: Bearer $TOVARKA_KEY" \
  -F "images=@candle.jpg"

2. Замовте кадри й опис

Без тіла запиту створюється весь комплект із 6 кадрів. Кредити списуються одразу, а кадри стають у чергу.

curl -X POST https://aiproduct.com.ua/api/v1/products/ID/frames \
  -H "Authorization: Bearer $TOVARKA_KEY"

curl -X POST https://aiproduct.com.ua/api/v1/products/ID/copy \
  -H "Authorization: Bearer $TOVARKA_KEY"

3. Заберіть результат

Перевіряйте товар раз на 5–10 секунд, поки status не стане ready. Один кадр готується приблизно пів хвилини, кадри створюються паралельно.

curl https://aiproduct.com.ua/api/v1/products/ID \
  -H "Authorization: Bearer $TOVARKA_KEY"

Ключі доступу

Ключі створюються в кабінеті, у розділі «API». Активних ключів може бути до 5. Повний ключ видно лише один раз, ми зберігаємо тільки його хеш.

Передавайте ключ у заголовку Authorization: Bearer tv_live_…. Не додавайте його в код сайту, який бачить браузер. Якщо ключ потрапив до сторонніх, видаліть його в кабінеті: він перестане працювати одразу.

Ключі працюють, поки діє підписка Enterprise. Коли вона закінчується, API відповідає помилкою plan_required, а ключі знову запрацюють після оплати.

Методи

Приклад: два кадри високої якості у світлому настрої.

curl -X PATCH https://aiproduct.com.ua/api/v1/products/ID \
  -H "Authorization: Bearer $TOVARKA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Свічка соєва","mood":"clean","ratio":"1:1"}'

curl -X POST https://aiproduct.com.ua/api/v1/products/ID/frames \
  -H "Authorization: Bearer $TOVARKA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slots":["white","scene"],"quality":"pro"}'

У PATCH можна передати: name, category, material, colors, benefits, scene, price, oldPrice, dims, notes, mood, ratio, quality.

Кадри й ціни

Кредити списуються з балансу акаунта за тими самими цінами, що й у кабінеті. Якщо кадр не вдався, кредити повертаються автоматично. Актуальні значення завжди є в GET /catalog.

• Кадр звичайної якості fast: 4 кредити.
• Кадр високої якості pro: 12 кредитів. Перші 150 таких кадрів за місяць коштують як звичайні.
• Опис двома мовами: 2 кредити.
• Розпізнавання товару: безкоштовно.

Що повертає API

Відповідь GET /products/ID виглядає так. Посилання на кадри постійні й відкриваються без ключа, поки товар не видалено.

{
  "product": {
    "id": "Xa81…",
    "title": "Соєва свічка в склі",
    "status": "ready",
    "facts": { "name": "Соєва свічка в склі", "category": "Декор", "benefits": ["…"] },
    "frames": [
      {
        "id": "Pq02…",
        "slot": "white",
        "quality": "fast",
        "status": "done",
        "error": null,
        "cost": 4,
        "image": { "url": "https://aiproduct.com.ua/media/…", "width": 1024, "height": 1024 }
      }
    ],
    "copy": {
      "status": "done",
      "uk": { "title": "…", "short": "…", "description": "…", "specs": [], "keywords": [] },
      "ru": { "title": "…", "short": "…", "description": "…", "specs": [], "keywords": [] }
    }
  }
}

Кадр може мати статус processing, done або failed. Товар має статус processing, поки хоч щось створюється, і ready, коли все завершено.

Важливо про текст на кадрах. API повертає фотографії без текстового шару: ціну, переваги й розміри сервіс друкує в браузері. Щоб додати текст, відкрийте цей самий товар у кабінеті або накладіть його на своєму боці. Товари, створені через API, видно в кабінеті.

Помилки

Помилка приходить у форматі {"error":{"message":"…","code":"…"}}. Текст у message можна показувати людині.

Обмеження

• 120 запитів за хвилину на ключ.
• 60 замовлень кадрів чи описів за хвилину на акаунт.
• 200 нових товарів за годину на акаунт.
• До 3 фото на товар, формати JPG, PNG, WebP.

Потрібно більше? Напишіть на support@aiproduct.com.ua.