ARTICLE

BulkImagen day-one GPT Image 2.5: eight refs, ratios, and PNG — a Bubble production checklist

BIAIG: Bulk Images AI Generator Published

BulkImagen’s day-one limits for gpt-image-2-5 break typical Bubble e-commerce flows. A production checklist: refs, aspect ratios, transparent PNG, and when to pick another model in the batch API.

Why this matters now

BulkImagen shipped GPT Image 2.5 (gpt-image-2-5) with platform limits that differ from OpenAI’s direct API. In Bubble, that shows up in production: batches fail with size_not_allowed, credit usage spikes from refMode: each, or product overlays ship without alpha. Worth reading next: gpt-image-1 sunsets 23 Oct 2026:. A closer look: BulkImagen SKU templates and POST.

Why this matters now

This is a practical integration checklist for BulkImagen’s async batch API—without assuming parity with OpenAI.

1. Reference images (up to eight per render)

  • On BulkImagen, GPT Image 2.5 allows up to eight reference images per render; GPT Image 2 allows four.
  • References go in refImages after POST /v1/uploads: multipart file field (PNG/JPEG/WebP/GIF, ≤10 MB), up to 20 files per upload request.
  • refMode: none | each | combined controls prompt × ref pairing and multiplies billed image count. each is a common billing trap: prompts × refImages × countPerCombo.

Bubble: BulkImagen is server-side only (no CORS). Keep the API key in backend workflows / API Connector with Bearer auth—not in the browser. Single-file uploads fit Form-data in the connector; eight refs may need repeated multipart file fields or middleware (Lambda/n8n)—confirm against BulkImagen’s curl examples; there is no official BulkImagen×Bubble doc. A closer look: The ~500-row bulk-tools ceiling in. Worth reading next: gpt-image-1 sunsets 23 Oct 2026:.

2. Aspect ratio × resolution

  • 2.5 exposes twelve aspect ratios, including 27:16, 16:27, 9:8, and 8:9.
  • BulkImagen states 27:16, 16:27, and the near-square pair (9:8 / 8:9) are 1K-only; other listed ratios can run through 4K.
  • Invalid pairs return size_not_allowed (retries won’t help).

Production rule: don’t hard-code ratios from marketing copy. Cache GET /v1/models → resolutionsByRatio for gpt-image-2-5 and validate before POST /v1/batches.

Credits (model registry): 1K — 5 · 2K — 10 · 4K — 16 for gpt-image-2-5 vs 4K — 20 on GPT Image 2.

Quality: auto → flare, high → sunburst (same credit tier per docs).

3. Transparent PNG for e-commerce overlays

  • The models comparison page: transparent backgrounds only on GPT Image 2 (gpt-image-2).
  • The GPT Image 2.5 landing page mentions 1K transparent beta—public copy is inconsistent.

Checklist: before relying on 2.5 for overlays, read GET /v1/models → supportsBackground for gpt-image-2-5. When you need alpha in production, route to gpt-image-2, 1K, background: "transparent" (beta; not guaranteed on every image). QA alpha edges on real SKUs.

Do not conflate OpenAI’s direct GPT Image 2.5 docs (e.g. more refs on edit routes, transparent PNG) with BulkImagen’s eight-ref cap and supportsBackground gating.

4. Batch API in Bubble

  1. POST https://bulkimagen.com/api/v1/batches — prompts + model required; eleven models in the catalog.
  2. Poll GET /v1/batches/{id} until batch.done.
  3. Fetch resultUrls (documented as public, no auth).

Respect plan caps: batch_limit_exceeded, concurrent_limit_exceeded—queue in workflows. Result URL lifetime and re-hosting policy are not stated in the packet; treat public URLs carefully for sensitive catalogs. Same topic: gpt-image-2 batch discount: unit economics. Same topic: gpt-image-2 batch discount: unit economics.

5. Model routing

Job Model
Deep ref stacks, new ratios, 4K where allowed gpt-image-2-5
Product cutouts, transparent background gpt-image-2 (1K)
Eight refs without 2.5 flux-2-pro (also eight refs per model comparison)
With reference images not z-image (text-only; batch with refs rejected)

Early-access pricing for 2.5 may change—re-check credits before large catalog runs.

Pre-flight

  • Model choice and supportsBackground from GET /v1/models
  • Ratio × resolution from resolutionsByRatio
  • Image count math for refMode: each
  • Uploads ≤10 MB, allowed formats; ≤8 refs per task
  • BulkImagen calls server-side only
  • Batch polling + policy for public resultUrls

Sources: BulkImagen models/API docs, model comparison, day-one digest; Bubble API Connector (Form-data, server-side pattern).

Related articles

← All articles