GridBulk MCP Server

Tạo lưới hình ảnh AI và tự động tách chúng thành tối đa 16 tài sản thông qua một điểm cuối MCP từ xa có xác thực.

Máy chủ MCP được lưu trữ

npx add-mcp 'https://www.gridbulk.com/api/mcp'

Cài vào Claude Code, Codex, Cursor và nhiều công cụ khác

Tài liệu

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

FieldTypeValuesDescription
modelenumgemini | gpt-image-2.5Generation model. gemini (default) uses Google Gemini; gpt-image-2.5 uses OpenAI GPT Image 2.5 (flare). Available ratios vary by model.
mode requiredenumsingle | gacha | composeGeneration mode. single = one image; gacha = repeated grid with one prompt; compose = one prompt per grid cell.
ratio requiredenum1: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:2Output aspect ratio. Gemini supports all except 9:21/1:3/3:1/1:2; GPT Image 2 supports all except 2:1.
resolution requiredenum1k · 2k · 4kOutput resolution tier.
gridColsinteger1–4Grid columns. Required for gacha / compose mode. Ignored for single.
gridRowsinteger1–4Grid rows. Required for gacha / compose mode. Ignored for single.
prompts requiredstring[]min 1 itemPrompt array. single takes [0]; gacha repeats [0] across grid; compose expects one prompt per cell.
referencesstring[]URL stringsOptional reference image URLs for style guidance.

Example Request

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.

{  "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": 7,  "creditsRemaining": 120}

Async Request

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.

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

Poll Job Status

Poll until status becomes completed or failed.

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

Response (pending)

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

Response (completed)

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

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

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

MCP Tools

ToolDescription
generate_imagesGenerate images synchronously — one prompt per image. Best for a handful of prompts.
submit_generate_jobSubmit a bulk job and get a jobId immediately.
get_generate_jobPoll job status: pending → processing → completed / failed.
get_credit_balanceCheck remaining credits.
list_skillsList built-in prompt-crafting skills (names only).
load_skillLoad 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.

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