API Reference

Image generation API

One endpoint for all modes — single image, gacha grid, or multi-prompt compose layout. Bearer API key for REST, or connect the built-in MCP server and let Claude / Cursor generate images for you.

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.5	Generation model. gemini (default) uses Google Gemini; gpt-image-2.5 uses OpenAI GPT Image 2.5 (flare). 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"    }  ]}

MCP · GB-AGENT

Use GridBulk from AI clients

GridBulk ships a native MCP server (Streamable HTTP). Connect it once and Claude Desktop, Cursor, or any MCP client can generate images, submit batch jobs, and check credits on their own — same API key, same credits as the REST API.

MCP Endpoint

POSThttps://www.gridbulk.com/api/mcp

Auth: Authorization: Bearer header, or ?key= in the URL for clients that can't set headers.

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config), then restart Claude Desktop.

claude_desktop_config.json

{  "mcpServers": {    "gridbulk": {      "type": "http",      "url": "https://www.gridbulk.com/api/mcp",      "headers": {        "Authorization": "Bearer sk_live_your_key"      }    }  }}

Cursor

Settings → MCP → Add new global MCP server.

~/.cursor/mcp.json

{  "mcpServers": {    "gridbulk": {      "url": "https://www.gridbulk.com/api/mcp?key=sk_live_your_key"    }  }}

MCP Tools

Tool	Description
`generate_images`	Generate images synchronously — one prompt per image. Best for a handful of prompts.
`submit_generate_job`	Submit a bulk job and get a jobId immediately.
`get_generate_job`	Poll job status: pending → processing → completed / failed.
`get_credit_balance`	Check remaining credits.
`list_skills`	List built-in prompt-crafting skills (names only).
`load_skill`	Load the full recipe of a skill for the AI to follow.

Agent Skills

Prompt recipes ship as Anthropic Agent Skills. They appear in your client's prompt list, or the AI can pull them via list_skills / load_skill. Two are bundled today:

bulk-prompt-matrix

How to build batch prompt matrices — variation axes, ratio pick, sync vs async.

ecommerce-batch-shots

A full ecommerce shot list per product and how to batch it in two jobs.

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."  }}