Пресети

Перегляд, створення та оновлення фотографічних пресетів з рекомендаціями та референсними зображеннями.

GET /api/external/presets

Повертає список доступних пресетів. Пресети є спільними глобально та визначають рекомендації щодо фотографії для завдань генерації.

Заголовки

Заголовок	Обов'язковий	Опис
X-Api-Key	Так	Ваш API key у форматі `mk_live_xxx.secret`

Параметри запиту

Поле	Тип	Обов'язковий	Опис
maxRecords	number	Ні	Максимальна кількість пресетів для повернення (за замовчуванням: 20, обмежено до 1000). Відсутній або порожній параметр (`?maxRecords=`) означає значення за замовчуванням; будь-яке інше значення, що не є додатним цілим числом, повертає `400`.

Відповідь

{
  "presets": [
    {
      "id": "preset_abc123",
      "name": "E-commerce Standard",
      "quantityGuidelines": "3-5 angles per product",
      "qualityGuidelines": "High resolution, consistent lighting, no reflections",
      "createdAt": "2026-03-15T10:00:00.000Z",
      "bestFor": "Product photography for online stores",
      "do": "Use even, diffused lighting",
      "dont": "Use harsh direct flash",
      "inputRequirements": "One clear product photo on a plain background",
      "heroIntro": "Consistent studio-grade product shots",
      "categories": ["studio"],
      "tags": ["ecommerce", "studio"],
      "slug": "ecommerce-standard",
      "isFree": true,
      "scenery": "required"
    }
  ],
  "count": 1
}

Поле	Тип	Опис
bestFor	string	Для чого підходить пресет — той самий опис, що й у маркетплейсі. `""`, якщо не встановлено.
do	string	Що робити, використовуючи цей пресет. `""`, якщо не встановлено.
dont	string	Чого уникати, використовуючи цей пресет. `""`, якщо не встановлено.
inputRequirements	string	Якою має бути вхідна фотографія. `""`, якщо не встановлено.
heroIntro	string	Вступний/маркетинговий опис. `""`, якщо не встановлено.
categories	string[]	Категорії в маркетплейсі. `[]`, якщо немає.
tags	string[]	Теги в маркетплейсі. `[]`, якщо немає.
slug	string	Slug URL-адреси в маркетплейсі. `""`, якщо не встановлено.
isFree	boolean	Чи пресет безкоштовний.
scenery	`"required"` \| `"recommended"` \| `null`	Чи потребує замовлення з цим пресетом сценерії. `"required"`: пресет не має запасного варіанту — не замовляйте без сценерії. `"recommended"`: без сценерії пресет використовує задокументований варіант за замовчуванням. `null`: ніхто ще не перевірив цей пресет — трактуйте як невідоме, ніколи як «сценерія не потрібна». Значення зберігається напряму, ніколи не обчислюється з `inputRequirements`.

Відповіді з помилками

Код	Значення
401	Відсутній або недійсний API key
500	Внутрішня помилка сервера

Примітки

Цей ендпоінт не витрачає кредити.
Повертає як системні пресети, так і створені користувачем.
Поля вище є адитивними: п'ять оригінальних ключів (id, name, quantityGuidelines, qualityGuidelines, createdAt) зберігають назви, типи та значення, а POST/PUT /api/external/presets повертають ту саму форму елемента.

Приклад

curl -X GET "https://qamera.ai/api/external/presets?maxRecords=50" \
  -H "X-Api-Key: mk_live_abc123.secret456"

POST /api/external/presets

Створює новий користувацький пресет з рекомендаціями та необов'язковими референсними зображеннями.

Заголовки

Заголовок	Обов'язковий	Опис
X-Api-Key	Так	Ваш API key у форматі `mk_live_xxx.secret`
Content-Type	Так	`multipart/form-data`

Тіло запиту

Поле	Тип	Обов'язковий	Опис
name	string	Так	Назва пресета
quantityGuidelines	string	Так	Рекомендації щодо кількості та різноманітності зображень для генерації
qualityGuidelines	string	Так	Рекомендації щодо якості зображень, освітлення та стилю
cover	file	Ні	Обкладинка для пресета
gallery	file[]	Ні	Галерея референсних зображень

Відповідь

{
  "success": true,
  "presetId": "preset_new123"
}

Відповіді з помилками

Код	Значення
400	Відсутні обов'язкові поля (name, quantityGuidelines або qualityGuidelines)
401	Відсутній або недійсний API key
500	Внутрішня помилка сервера

Примітки

Створений пресет має тип USER, статус published та видимість private.
Пресет прив'язується до акаунта, пов'язаного з API key.
Цей ендпоінт не витрачає кредити.

Приклад

curl -X POST "https://qamera.ai/api/external/presets" \
  -H "X-Api-Key: mk_live_abc123.secret456" \
  -F "name=My Custom Preset" \
  -F "quantityGuidelines=Generate 5 variations per product" \
  -F "qualityGuidelines=Bright studio lighting, minimal shadows, 4K resolution" \
  -F "cover=@/path/to/cover.jpg" \
  -F "gallery=@/path/to/ref1.jpg" \
  -F "gallery=@/path/to/ref2.jpg"

PUT /api/external/presets

Оновлює існуючий користувацький пресет. Ви можете змінити рекомендації, замінити обкладинку та керувати зображеннями галереї.

Заголовки

Заголовок	Обов'язковий	Опис
X-Api-Key	Так	Ваш API key у форматі `mk_live_xxx.secret`
Content-Type	Так	`multipart/form-data`

Тіло запиту

Поле	Тип	Обов'язковий	Опис
presetId	string	Так	ID пресета для оновлення
name	string	Ні	Оновлена назва пресета
quantityGuidelines	string	Ні	Оновлені рекомендації щодо кількості
qualityGuidelines	string	Ні	Оновлені рекомендації щодо якості
cover	file	Ні	Нова обкладинка (замінює існуючу)
gallery	file[]	Ні	Нові зображення для додавання до галереї
existingGalleryIds	string	Ні	JSON-рядок масиву ID існуючих зображень галереї для збереження (наприклад, `["id1","id2"]`)
removeCover	string	Ні	Встановіть `"true"` для видалення поточної обкладинки

Відповідь

{
  "success": true
}

Відповіді з помилками

Код	Значення
400	Відсутній presetId або недійсний запит
401	Відсутній або недійсний API key
403	Ви не є власником цього пресета
500	Внутрішня помилка сервера

Примітки

Ви можете оновлювати лише пресети, що належать вашому акаунту. Спроба оновити пресет іншого користувача повертає помилку 403.
Галерея підтримує максимум 6 зображень.
Використовуйте existingGalleryIds для вказівки, які поточні зображення галереї зберегти. Зображення, не зазначені в списку, видаляються.
Встановіть removeCover у значення "true" для видалення обкладинки без завантаження заміни.
Цей ендпоінт не витрачає кредити.

Приклад

curl -X PUT "https://qamera.ai/api/external/presets" \
  -H "X-Api-Key: mk_live_abc123.secret456" \
  -F "presetId=preset_abc123" \
  -F "name=Updated Preset Name" \
  -F "qualityGuidelines=Soft natural lighting, warm tones, lifestyle feel" \
  -F "gallery=@/path/to/new_ref.jpg" \
  -F 'existingGalleryIds=["gallery_img_001","gallery_img_002"]' \
  -F "removeCover=false"