API Reference

Image generation API

One endpoint for all modes — single image, gacha grid, or multi-prompt compose layout. Authenticate with a Bearer API key, get results synchronously.

Endpoints

Main

POSThttps://gridbulk.com/api/v1/generate

Async + Query + History

POSThttps://gridbulk.com/api/v1/generate/async

GEThttps://gridbulk.com/api/v1/generate/jobs/{jobId}

GEThttps://gridbulk.com/api/v1/generate/history?page=1&limit=20

POST

Request Fields

POST https://gridbulk.com/api/v1/generate

Field	Type	Values	Description
`model`	enum	gemini \| gpt-image-2	Generation model. gemini (default) uses Google Gemini; gpt-image-2 uses OpenAI GPT Image 2. Available ratios vary by model.
`mode`required	enum	single \| gacha \| compose	Generation mode. single = one image; gacha = repeated grid with one prompt; compose = one prompt per grid cell.
`ratio`required	enum	1:1 · 3:2 · 2:3 · 4:3 · 3:4 · 16:9 · 9:16 · 4:5 · 5:4 · 21:9 · 2:1 · 9:21 · 1:3 · 3:1 · 1:2	Output aspect ratio. Gemini supports all except 9:21/1:3/3:1/1:2; GPT Image 2 supports all except 2:1.
`resolution`required	enum	1k · 2k · 4k	Output resolution tier.
`gridCols`	integer	1–4	Grid columns. Required for gacha / compose mode. Ignored for single.
`gridRows`	integer	1–4	Grid rows. Required for gacha / compose mode. Ignored for single.
`prompts`required	string[]	min 1 item	Prompt array. single takes [0]; gacha repeats [0] across grid; compose expects one prompt per cell.
`references`	string[]	URL strings	Optional reference image URLs for style guidance.

Example Request

cURL

curl -X POST https://gridbulk.com/api/v1/generate \  -H "Authorization: Bearer sk_live_your_key" \  -H "Content-Type: application/json" \  -d '{    "mode": "compose",    "ratio": "1:1",    "resolution": "1k",    "gridCols": 3,    "gridRows": 3,    "prompts": [      "museum-display portrait series",      "cyberpunk city nightscape",      "watercolor still life"    ]  }'

Response

Returns generated images with presigned URLs, credit usage, and remaining balance.

JSON

{  "images": [    {      "url": "https://cdn.gridbulk.com/gen/abc...?X-Amz-Expires=3600",      "key": "gen/abc.png",      "width": 1024,      "height": 1024,      "expiresAt": "2026-04-16T12:00:00Z"    }  ],  "creditsUsed": 1,  "creditsRemaining": 120}

Async Request

cURL

curl -X POST https://gridbulk.com/api/v1/generate/async \  -H "Authorization: Bearer sk_live_your_key" \  -H "Content-Type: application/json" \  -d '{    "mode": "gacha",    "ratio": "1:1",    "resolution": "1k",    "gridCols": 2,    "gridRows": 2,    "prompts": ["the same cat in four different styles"]  }'

Async Response

Returns immediately with a jobId. Poll GET /api/v1/generate/jobs/{jobId} for status.

JSON

{  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",  "status": "pending"}

Poll Job Status

Poll until status becomes completed or failed.

cURL

curl https://gridbulk.com/api/v1/generate/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \  -H "Authorization: Bearer sk_live_your_key"

Response (pending)

JSON

{  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",  "status": "processing"}

Response (completed)

JSON

{  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",  "status": "completed",  "images": [    {      "url": "https://cdn.gridbulk.com/gen/cat-1.png?X-Amz-Expires=3600",      "key": "gen/cat-1.png",      "width": 512,      "height": 512,      "expiresAt": "2026-04-16T12:00:00Z"    },    {      "url": "https://cdn.gridbulk.com/gen/cat-2.png?X-Amz-Expires=3600",      "key": "gen/cat-2.png",      "width": 512,      "height": 512,      "expiresAt": "2026-04-16T12:00:00Z"    }  ]}

Error Responses

401 — API key missing or invalid: check the Authorization header. 402 — Insufficient credits: top up on the pricing page, then retry. 429 — Rate limited: wait for the Retry-After interval, then retry. 422 — Invalid params: fix the fields flagged in the error message.

JSON

{  "error": {    "code": "RATE_LIMITED",    "message": "Too many requests. Retry after 30 seconds."  }}