СТАТТЯ

BulkImagen SKU-шаблони і POST /v1/batches: від Bubble-рядка до batch-job через BIAIG

Віталій Дорошенко Опубліковано

Чеклист для Bubble-розробника: SKU у Data Types, chunking ~500 рядків, POST /v1/batches на сервері, polling і збереження PNG у Bubble Storage — без вигаданих лімітів API.

Навіщо це зараз

У дайджесті знову виліз BulkImagen: spreadsheet-шаблони SKU на стороні сервісу і POST /v1/batches — REST, який нормально лягає на рядки Bubble Data Types. Це продовження тем про agent skill + REST batch і chunking великих каталогів (~500 рядків), але тут я фокусуюся на mapping, а не на «multi-job на 50k». Поруч із цим: Фрагментована ніша bulk-tools: Apify spreadsheet. Поруч із цим: Фрагментована ніша bulk-tools: Apify spreadsheet.

BIAIG у нашій редакційній лінії — скорочення для зв’язки BulkImagen agent skill + REST batch (див. док skill та API). Це не GenBatch MCP (окремий продукт, інші ключі та контракт).

Що API реально приймає (і що лишається в Bubble)

  • База: https://bulkimagen.com/api/v1, авторизація Bearer, виклики лише server-side — CORS для браузера немає (API docs).
  • POST /v1/batches: один JSON — спільні model, aspectRatio, resolution, refMode, refImages, countPerCombo, опційно note; масив prompts[] розгортає багато зображень за правилами fan-out (OpenAPI, llms-full.txt).
  • «SKU template» у BulkImagen — spreadsheet-first: обов’язкова колонка prompt, опційно ratio/count; Remix клонує налаштування; ZIP/manifest у UI зіставляє файли з prompt/reference (блог про SKU, bulk product photos). Окремого поля SKU в API немає — SKU живе у ваших Bubble Things; batch.note — лише вільний текст.
  • Кредити списуються на create; робота async — poll GET /v1/batches/{id} поки batch.done === true, потім resultUrls (публічні, без auth). Поруч із цим: OpenArt Bulk Create (500 CSV. Поруч із цим: OpenArt Bulk Create (500 CSV.

Планові стелі — зображення на batch і concurrent batches (на Scale: до 100 images/batch і 20 concurrent — pricing), а не «~500 рядків API». Редакційні ~500 — це клієнтський chunking каталогу Bubble під fan-out (prompts × countPerCombo, або × refImages у refMode each) та поля GET /v1/me.

Чеклист Bubble-розробника

1. SKU template → Data Types

  • Зберігайте stable row id (unique id Thing або ваш SKU code) — не покладайтеся лише на текст prompt: дублікати prompt у tasks неоднозначні для зворотного mapping.
  • У prompt або в sidecar-стані (поля Chunk Job) тримайте кореляційний токен (наприклад SKU-123|row_uid), щоб після poll зіставити task з рядком.
  • Reference на SKU: у batch один масив refImages[] на весь batch (OpenAPI), не per-prompt. Варіанти без вигадок:
    • багато маленьких batch (1 SKU ≈ 1 batch), або
    • refMode без per-SKU ref, або
    • попередньо POST /v1/uploads (до 20 файлів на request) + оркестрація з backend.

2. Де API Connector, де backend workflow

Крок Рекомендація
POST /v1/batches, GET batch, GET /v1/me Backend workflow або server-side API Connector (Bubble Manual — API Connector); ключ BULKIMAGEN_API_KEY ніколи в браузері/mobile.
Старт з UI Кнопка → Schedule API workflow on a list (chunks) або one-shot backend; на нижчих tier врахуйте concurrent_limit_exceeded (на Starter — 1 concurrent batch).
Завантаження PNG API Connector: тип відповіді image/file, дія «:saved to Bubble storage» (forum pattern). Публічні resultUrls можуть не відповідати вашій retention-політиці.

2. Де API Connector, де backend workflow

Agent skill (docs/skill) дублює той самий сценарій для Cursor/CLI: catalog → cost confirm → uploads → batches → poll → download — зручно для прототипу payload, production лишається в Bubble backend.

3. Batch payload і chunking ~500

  1. GET /v1/me — перевірте ліміти плану перед run.
  2. Порахуйте images у chunk: len(prompts) × countPerCombo (і × refImages для refMode each) — не перевищуйте images per batch для вашого tier (batch_limit_exceeded).
  3. Ріжте каталог на chunks (~500 рядків як editorial ceiling, але фінальний розмір chunk — за формулою fan-out, не за «500» сліпо).
  4. На кожен chunk: POST /v1/batches → збережіть batchId, chunkIndex, список {row_id, prompt_token}.
  5. Poll ~5 s (API docs) до batch.done.
  6. Для кожного task: prompt + збережений map → оновіть відповідний Thing; завантажте PNG у Storage.

Уникнення дублікатів рядків при chunking:

  • Перед POST перевірте, що для (catalog_run_id, chunkIndex, row_id) статус не «already_submitted».
  • Публічного idempotency-key немає — при retry після 500 або concurrent_limit_exceeded не робіть сліпий повтор POST для того самого chunk без перевірки наявного batchId (повтор успішного create = подвійне списання).
  • При prompt_too_long використайте details.promptIndex у відповіді, щоб показати, який рядок у chunk зламався.

4. Статус job у Bubble

Мінімальна модель (приклад):

  • Bulk Run — catalog id, tier snapshot, загальний прогрес.
  • Bulk Chunk — batchId, chunkIndex, state (submitted / polling / done / failed), raw error code.
  • Product row — lastBulkBatchId, image, bulkStatus.

Task у відповіді містить id, prompt, status, resultUrls — promptIndex у схемі немає; покладайтеся на унікальні токени в prompt або на стабільний порядок лише як допоміжний сигнал, не як єдине джерело правди.

Ризики (коротко)

  • refMode each швидко множить billed images — легко впертися в batch/plan limit або бюджет.
  • Failed tasks — refund за документацією; успішні дублікати від retry — ні.
  • Не змішуйте в одному коннекторі BulkImagen (bik_live…) та GenBatch (gbm_…) — різні вендори та ліміти (у GenBatch — інший контракт, напр. items[] до 50 images/job у їхньому guide).

Підсумок

SKU-шаблон BulkImagen — промпт-колонка + batch-рівень налаштувань; Bubble дає SKU, chunking, dedup і Storage. BIAIG-path: server-side POST /v1/batches → poll → map по збереженому batch id + row correlation → :saved to Bubble storage. Chunking ~500 — про каталог у Bubble, а розмір batch рахуйте за fan-out і GET /v1/me, не за міфічним «500-row API limit».

Джерела: bulkimagen.com/docs/api, llms-full.txt, OpenAPI, agent skill, pricing, editorial chunking ~500, Bubble API Connector + forum upload pattern.

Схожі статті

← Усі статті