API for bulk image generation

One HTTP call turns a list of prompts into a batch of images. Built for scripts, pipelines and AI agents — poll until the batch is done, then download the results.

Create an API key OpenAPI spec Full reference (text)

Quickstart

Create a key under Dashboard → Developer → API keys, and export it as BULKIMAGEN_API_KEY.
Call GET /v1/models to pick a model and read its credit price.
POST /v1/batches with your prompts. Credits are charged immediately.
Poll GET /v1/batches/{id} until batch.done is true, then download each task's resultUrls.

curl -X POST https://bulkimagen.com/api/v1/batches \
  -H "Authorization: Bearer $BULKIMAGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": ["a red fox in snow", "a red fox in autumn leaves"],
    "model": "nano-banana-pro",
    "aspectRatio": "16:9",
    "resolution": "1K",
    "countPerCombo": 4
  }'

# {"id":"b_9f2c…","total":8,"creditsCharged":40,"status":"pending"}

Authentication

Send your key as an HTTP bearer token: Authorization: Bearer bik_live_… Every endpoint requires it. Revoking a key takes effect on the very next request.

Three rules that matter

Server-side only. The API sends no CORS headers, so a key can never be used safely from a browser or mobile app.
The full key is shown once, at creation. We store only a hash and cannot recover it.
Set a daily credit cap when an autonomous agent holds the key — it bounds the damage if a loop misbehaves.

Endpoints

Endpoint	What it does
`GET /v1/models`	Model catalog: credit price per resolution and every legal aspect-ratio × resolution pair.
`GET /v1/me`	Account, credit balance, plan limits, and this key's usage against its daily cap.
`POST /v1/batches`	Create a batch. Charges credits and returns immediately; generation is asynchronous.
`GET /v1/batches`	List batches, newest first, with an opaque cursor for paging.
`GET /v1/batches/{id}`	One batch with all of its tasks, statuses and result image URLs. This is the polling endpoint.
`POST /v1/uploads`	Upload reference images and get URLs to pass as refImages. Free — no credits charged.

Request parameters

The body of POST /v1/batches. Only prompts and model are required — everything else falls back to a default.

Field	Type	Default	Description
`prompts`required	string[]	—	One or more prompts. The batch fans out across all of them.
`model`required	string	—	A model key from GET /v1/models.
`aspectRatio`	string	"1:1"	Aspect ratio, e.g. 16:9. Must be legal at the chosen resolution — check resolutionsByRatio.
`resolution`	"1K" \| "2K" \| "4K"	"1K"	Resolution tier. Determines the credit price per image.
`countPerCombo`	1–20	1	Images per prompt — per reference image when refMode is each.
`refMode`	"none" \| "each" \| "combined"	"none"	How reference images pair with prompts. See below.
`refImages`	string[]	[]	URLs returned by POST /v1/uploads. Required unless refMode is none.
`quality`	"auto" \| "low" \| "medium" \| "high"	"auto"	Only honoured by models where supportsQuality is true; ignored elsewhere.
`background`	"transparent" \| "#RRGGBB"	"auto"	BETA, may not apply to every image. "transparent", a #RRGGBB colour, or omitted for auto. Only honoured by models where supportsBackground is true.
`note`	string	null	Free-text label shown next to the batch in the dashboard.

Reference images

Upload the images first, then pass the returned URLs as refImages. Uploading is free — credits are charged only when the batch is created.

POST the files to /v1/uploads as multipart form-data using a repeated file field. PNG, JPEG, WebP or GIF, up to 10 MB each, 20 per request.
Collect the url of each returned file into the refImages array.
Choose a refMode. Every model caps how many reference images it accepts — the limit is in the model table above.

curl -X POST https://bulkimagen.com/api/v1/uploads \
  -H "Authorization: Bearer $BULKIMAGEN_API_KEY" \
  -F "file=@shirt.png" -F "file=@mug.png"

# {"files":[
#   {"url":"https://s.bulkimagen.com/refs/9a1c….png","name":"shirt.png"},
#   {"url":"https://s.bulkimagen.com/refs/4f7b….png","name":"mug.png"}]}

How refMode changes the image count

refMode decides how prompts and reference images pair up, and therefore how many images you are billed for.

refMode	Images produced	Use when
`none`	prompts × countPerCombo	Text-only generation, with no reference images.
`each`	prompts × refImages × countPerCombo	One result per prompt per reference image — e.g. apply one prompt to each of your product photos.
`combined`	prompts × countPerCombo	Every reference image attached to every result — e.g. blend several sources into one scene.

each multiplies the image count by the number of reference images. Recalculate the cost before submitting — this is the most common way a batch ends up several times more expensive than expected.

curl -X POST https://bulkimagen.com/api/v1/batches \
  -H "Authorization: Bearer $BULKIMAGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": ["product photo on a marble table"],
    "model": "nano-banana-pro",
    "refMode": "each",
    "refImages": [
      "https://s.bulkimagen.com/refs/9a1c….png",
      "https://s.bulkimagen.com/refs/4f7b….png"
    ],
    "countPerCombo": 2
  }'

# 1 prompt × 2 reference images × 2 = 4 images

Polling and downloading

Generation runs in the background. Poll the batch every 5 seconds or so; it is finished when batch.done is true. Result URLs are public — download them directly, no authentication needed. Tasks that fail are refunded automatically.

curl https://bulkimagen.com/api/v1/batches/b_9f2c… \
  -H "Authorization: Bearer $BULKIMAGEN_API_KEY"

# {"batch":{"done":false,"counts":{"pending":6,"running":2,
#   "succeeded":0,"failed":0}, …},"tasks":[…]}

Models and pricing

Credits per image, by resolution. Not every aspect ratio is available at every resolution — resolutionsByRatio in GET /v1/models is the authoritative source, and sending an illegal pair returns size_not_allowed.

Model	Credits per image	Max reference images
`gpt-image-2`	1K 5 · 2K 10 · 4K 20	4
`nano-banana-2`	1K 4 · 2K 6 · 4K 10	4
`nano-banana-2-lite`	1K 3	4
`nano-banana-pro`	1K 5 · 2K 6 · 4K 10	4
`seedream-4-5`	2K 6 · 4K 6	4
`seedream-5-lite`	2K 5 · 4K 5	4
`seedream-5-pro`	1K 6 · 2K 12	4
`grok`	1K 4	1
`flux-2-pro`	1K 5 · 2K 6	8
`z-image`	1K 1	—

curl https://bulkimagen.com/api/v1/models \
  -H "Authorization: Bearer $BULKIMAGEN_API_KEY"

Errors

Every failure returns the same shape, shown below. The code is stable — branch on it rather than on the message. Codes marked no-retry will fail identically until something changes on the account or in the request.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits: this batch requires 40.",
    "details": { "required": 40 }
  }
}

Code	HTTP	Meaning
`invalid_api_key`No retry	401	Key not recognized, revoked, or expired.
`api_not_available_on_plan`No retry	403	Your plan does not include API access.
`invalid_request`No retry	400	Malformed body or a missing required field.
`unknown_model`No retry	400	Model key is not in the catalog.
`size_not_allowed`No retry	400	That aspect ratio is not offered at that resolution.
`content_blocked`No retry	400	The prompt hit the content policy. Edit it before resubmitting.
`prompt_too_long`No retry	400	A prompt is longer than the model accepts. The response says which one — shorten it or split it across rows.
`insufficient_credits`No retry	402	Balance is lower than the batch cost.
`daily_credit_cap_exceeded`No retry	402	This key's daily credit cap would be exceeded. It resets at 00:00 UTC.
`batch_limit_exceeded`No retry	403	More images in one batch than your plan allows.
`concurrent_limit_exceeded`	403	Too many batches already running. Wait for one to finish.
`rate_limited`	429	Too many requests. Back off and honour Retry-After.
`internal_error`	500	Server-side failure. Safe to retry.

Plan limits

Plan	API keys	Images per batch	Concurrent batches
free	No API access	4	1
starter	2	10	1
studio	5	50	10
scale	10	100	20

Using this from an AI agent

The full reference below is plain text, written to be read in one fetch by an LLM. Point your agent at it, or install the BulkImagen skill so it knows the workflow — check models, estimate the cost, confirm the spend with you, submit, poll, download.

Full reference (text)OpenAPI spec