Sync, async, and batch for image APIs (OpenAI/Google context): a mode matrix for Bubble catalog bulk via BIAIG
One builder-facing choice: sync bursts in backend workflows, async jobs with coarse polling, or mass generation via OpenAI/Gemini Batch or a BIAIG-style batch job—mapped to Bubble’s ~30s Connector behavior, 300s caps, and WU.
Why one matrix beats another provider-specific post
After the October lineup changes (GPT Image family, Nano Banana / Gemini image models), I kept hitting the same wall: a fresh vendor essay every month does not help when you need one decision framework for sync, async, and batch. Public docs overlap on three patterns: synchronous single-call generation, asynchronous jobs via polling or webhooks, and provider Batch APIs (separate rate-limit pools, up-to-~24h windows, roughly 50% lower unit cost vs standard/sync tiers on both OpenAI and Gemini Batch).
On Bubble I treat platform limits as the real constraint, often ahead of the provider feature list. This piece maps modes for bulk catalog work (many SKUs, variants, previews), ties them to workload units (WU) and stuck-workflow risk, and I am not retelling failover history from 14.10. A closer look: ChatGPT is not bulk-native: where.
BIAIG in our editorial stack is shorthand for batch-job orchestration for mass generation. The closest documented public analogue in the Scout packet is BulkImagen (POST /v1/batches, poll GET /v1/batches/{id}). If your stack is a Bubble plugin or internal worker with the same shape, use the same rows. A closer look: The ~500-row bulk-tools ceiling in.
Three modes (what you actually call)
| Mode | Typical API surface | Completion | Economics (provider list price only) |
|---|---|---|---|
| Sync burst | OpenAI POST /v1/images/generations / edits; Gemini generateContent with image output; legacy Vertex Imagen :predict |
Seconds; caller waits on HTTP | Standard tier; sync capped by IPM (e.g. Build tier ~20 IPM on GPT Image 2.5 Flare/Sunburst model pages) |
| Async job | Provider or intermediary returns an id; you poll or receive a webhook | Minutes | Standard pricing plus your WU for polls |
| Batch (provider or BIAIG) | OpenAI Batch on /v1/images/generations; Gemini batchGenerateContent for Nano Banana image models; BulkImagen-style batches |
Up to ~24h (documented OpenAI/Gemini Batch window) | ~50% vs standard (OpenAI: e.g. ~$30/M vs ~$15/M image output tokens for gpt-image-2.5 batch vs standard per pricing page; Gemini Batch docs cite the same discount pattern) |
Terminology: vendor Batch API ≠ “I scheduled an API workflow on a list of 5,000 Things.” I have seen that confusion produce bad WU and rate-limit advice.
Pin API model IDs, not marketing nicknames alone. OpenAI: primary sync path via Image API (gpt-image-2.5-sunburst / flare); gpt-image-1 shutdown 2026-10-23 (deprecations). Google: gemini-2.5-flash-image (Nano Banana, GA 2025-10-02); Nano Banana 2 line (gemini-3.1-flash-image, gemini-nano-banana-2.1, etc.) with Batch support; Nano Banana 2 GA in changelog 2026-05-28—the 2025-10-29 note is a different release. gemini-2.5-flash-image shuts down 2027-03-15, replacement gemini-3.1-flash-lite-image. Plan migration using OpenAI deprecations and Gemini deprecations.
Bubble constraints that break naïve sync
Sources: API Connector, hard limits, forum signal on ~30s external calls (discussion).
- API Connector calls beyond ~30 seconds get retried → duplicate generations and charges unless the call is idempotent.
- 300-second workflow hard stop — you cannot sync-generate hundreds of images inside one run.
- API Connector recursion depth (3 direct / 10 cross-app) — self-triggering workflow chains hit caps fast.
- Schedule API workflow on a list caps fan-out (50k–100k depending on sort) — not a substitute for provider Batch SLAs at thousands of image requests.
- ~50 MB response cap — I default to URL/storage handoff instead of large inline base64 payloads.
Marketplace plugins document the same rule: avoid client-side blocking >30s; use backend workflows and webhooks where available (Flux/Replicate plugin). The OpenAI plugin exposes Batch Operations as an alternative to raw Connector calls (plugin page).
Decision matrix for catalog bulk
| Scenario | Volume / SLA | Mode | Where in Bubble | WU / stuck-workflow risk |
|---|---|---|---|---|
| Admin preview; user waits on screen | 1–5 images, each reliably under ~25–30s | Sync in a backend workflow (not the client) | API Connector or plugin action | Low if you respect provider IPM |
| Overnight catalog refresh; tens to low hundreds | Minutes; no live UI requirement | Async job: ImageJob record + coarse scheduled polling |
Optional webhook if intermediary supports it | Medium — each poll is a run; need max iterations and terminal states |
| Backfill; hundreds–thousands+; cost and rate limits matter | Hours SLA acceptable | Provider Batch or BIAIG batch-job | Submit once → persist batch_id → infrequent poll → import results |
Low fan-out WU; high mapping-error risk |
| Legacy Vertex Imagen | Sync :predict |
Footnote / migrate toward Gemini Nano Banana | Separate from Gemini Batch API path | Same as sync burst |
Practical thresholds
- Stay on sync while a single image call plus Bubble overhead stays under ~30s and session volume fits your IPM tier.
- Move to async jobs when sync hits retries/timeouts or you need more than roughly 10–20 images without blocking the UI—poll on minute-scale intervals with backoff, not every few seconds.
- Move to Batch / BIAIG when jobs run hours, you want batch pricing, or standard pools throttle you; persist batch ids and custom_id / task keys (OpenAI output order ≠ input order). Worth reading next: OpenAI Images API: up to.
BIAIG batch-job flow in Bubble
Reference pattern (BulkImagen API):
- Backend workflow: build prompt list with stable catalog keys → create batch.
- Store
batch_id, timestamps, and exact model id. - Scheduled workflow (e.g. every 15–60 minutes): poll until
done, failed, or expired. - Write URLs to Storage/CDN; Bubble Things hold metadata only.
Third-party orchestrators typically require server-side keys—I do not run bulk catalog generation from client workflows.
Cutover calendar: digest dates vs vendor tables
Internal digest cited “23.10 gpt-image-1 / 29.10 Nano Banana 2.” I reconciled that against Scout on 2026-10-22:
- OpenAI
gpt-image-1shutdown: 2026-10-23 (not October 2025). - Nano Banana 2 GA: 2026-05-28 in Gemini release notes; 2025-10-29 is unrelated (logging/datasets tooling).
Plan migrations from official deprecation pages, not from undated digest lines.
Pre-production checklist
- Idempotency for any sync path still in use.
- Job entity with explicit terminal states including expired (24h batch windows).
- Poll guards: max attempts, alerting.
- Result import keyed by
custom_id/ task id. - Avoid shipping large binaries through Connector responses.
- Measure provider spend and Bubble WU separately on staging (official WU breakdown for poll-heavy vs one long call was not verified in Scout).
| Check | For | Not for |
|---|---|---|
| Idempotency on active sync paths | Any sync path still in use | — |
| Job entity with terminal states | Explicit terminal states, including expired (24h batch windows) | — |
| Poll guards | Max attempts and alerting on polls | — |
| Result import | Keying by custom_id / task id |
— |
| Connector responses | Normal Connector response payloads | Large binaries |
| Staging cost measurement | Provider spend and Bubble WU measured separately | Official WU breakdown (poll-heavy vs one long call)—not verified in Scout |
Sources
OpenAI: Batch guide, pricing, image generation guide. Google: Gemini Batch API, image generation, changelog. Bubble: API Connector, hard limits. Orchestrator reference: BulkImagen API.
Internal draft — not for external publication.