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
| 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 -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
| 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.
{ "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after 30 seconds." }}