An image generation API your agent can call on its own.
One prompt in, a hosted image URL out. The same operation is exposed as a REST endpoint for your backend and as an MCP tool for Claude, Cursor and every other agent — so the picture your assistant needs mid-conversation never has to become a ticket for a human.
- 6
- aspect ratios
- 2
- ways to call it
- 1
- credit log entry per call
curl -X POST "https://api.imagemcpserver.com/playground/generate" \
-H "Authorization: Bearer $IMAGEMCP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A cutaway illustration of a mechanical keyboard switch, warm cream background, technical line art",
"aspectRatio": "16:9",
"style": "vector"
}'{
"success": true,
"result": {
"url": "https://cdn.imagemcpserver.com/gen/8f2c...png",
"model": "google/gemini-2.5-flash-image",
"aspectRatio": "16:9"
},
"creditsUsed": 15,
"creditsRemaining": 985
}Text-to-image and image-to-image, behind the same call
The endpoint decides which mode it is in from what you send. A prompt on its own generates from scratch. Add image and it works from your picture. Add referenceImages and it borrows style from several at once.
Text to image
Prompt only. The model composes the scene from nothing — the mode you want for hero art, illustrations and concept boards.
Image to image
Pass a source image and a prompt describing the change. Useful for restyling a photo, changing a season, or re-rendering a rough sketch.
Reference-guided
Pass two or three examples in referenceImages so a whole batch comes back in one consistent visual language instead of drifting.
Every field, and what it changes
One required field. Everything else has a sane default, so the smallest useful request is a single line of JSON.
Read the endpoint docs →| Field | Accepts | What it does |
|---|---|---|
prompt | string · required | What to draw. Long, specific prompts beat short ones — subject, medium, lighting, framing, palette. |
model | string | A model ID such as google/gemini-2.5-flash-image or black-forest-labs/flux-1.1-pro. Omit it to use the account default. |
aspectRatio | 1:1 · 16:9 · 9:16 · 4:3 · 3:4 · 21:9 | Framing of the output. Defaults to 1:1. |
style | string | A visual preset — photorealistic, anime, vector, 3d, minimalist — folded into the prompt. |
image | string | A URL or base64 data URI to generate from, turning the call into image-to-image. |
referenceImages | string[] | Several examples that steer style, layout or subject without being copied outright. |
responseFormat | url · b64_json | Defaults to url. b64_json adds the raw base64 to the response. |
Pick the frame before you pick the prompt
Cropping a square down to a banner throws away half the composition the model worked on. Asking for the shape you actually need is free.
Avatars, product tiles, app icons, Instagram posts
Hero images, YouTube thumbnails, slide backgrounds
Stories, Reels, TikTok, mobile splash screens
Blog inline figures, documentation screenshots
Pinterest pins, portrait product shots, book covers
Ultra-wide banners, GitHub social previews, page headers
Your assistant asks for the picture itself
Connect the MCP server once and generate_image shows up in the tool list of whatever client you use. The agent writes the prompt, reads back the hosted URL, and drops it straight into the file it is editing — no copy-paste round trip through a browser tab.
tools/call
{
"name": "generate_image",
"arguments": {
"prompt": "Isometric illustration of a
server rack made of paper, cream
background, soft studio light",
"aspectRatio": "4:3",
"referenceImages": [
"https://example.com/brand-style.png"
]
}
}Endpoint: https://mcp.imagemcpserver.com/mcp
What a generation costs
Fast model
8 credits
Quick drafts, thumbnails, iterating on a prompt.
Standard model
15 credits
The default tier — good detail at a sensible price.
Premium model
30 credits
When the image ships to a customer, not a mockup.
Your OpenRouter key
2 credits
BYOK on any paid plan. OpenRouter bills the model directly.
Checking your balance is free — get_user_info and list_models never deduct credits, so a careful agent can price the work before it starts it. See plans and credit packs.
Image generation API questions
What is the difference between the API and the MCP tool?
They are the same operation with two front doors. POST /playground/generate is the HTTP endpoint your own code calls. generate_image is the MCP tool an agent calls after you connect the server once. Both bill the same credits, both write to the same request log, and both return the same response shape.
Which models can I generate with?
Whatever is live on your account at the time of the call. Omit the model field and the request routes to the default, google/gemini-2.5-flash-image. Call list_models (or GET /playground/models, which is free) to read the current catalogue with each model’s cost, latency and supported aspect ratios.
Can I do image-to-image instead of text-to-image?
Yes. Pass image with a URL or base64 data URI to steer generation from a source picture, or pass referenceImages as an array to guide style, layout or subject from several examples at once.
How much does one generation cost?
The cost of the model you routed to — roughly 8 credits for a fast model, 15 for a standard one and 30 for a premium one. If a model has no recorded cost the server falls back to 15. On a paid plan with your own OpenRouter key connected, generation costs a flat 2 credits and OpenRouter bills you for the model directly.
Where do the generated images live?
Every result is uploaded to Cloudflare R2 and returned as a hosted https URL. Pass responseFormat: "b64_json" when you would rather receive the raw base64 alongside the URL — useful when the agent has to hand the bytes straight to another tool.