Generate image
https://api.imagemcpserver.com/playground/generateThe core text-to-image call. Pass a prompt and, optionally, one or more reference images to steer the result toward an existing subject, layout or palette. The generated file is uploaded to storage and returned as a public URL; pass responseFormat: "b64_json" if your agent needs the bytes inline instead.
Overview
Turn a text prompt — optionally guided by reference images — into a hosted image.
Deducts the selected model's costPerReq (15 credits when the model has no cost recorded).
Request
Headers
| Field | Type | Description |
|---|---|---|
Authorizationrequired | string | Bearer <IMAGEMCP_API_KEY>. The header x-api-key: <key> is accepted as an alternative. |
Content-Typerequired | string | application/json |
Body parameters
| Field | Type | Description |
|---|---|---|
promptrequired | string | What to draw. Detail and explicit style cues matter more than any other parameter. |
model | string | Model id from /playground/models. Defaults to google/gemini-2.5-flash-image. |
aspectRatio | string | Forwarded to the model as aspect_ratio. Defaults to "1:1". Common values: 1:1, 16:9, 9:16, 4:3, 3:4, 21:9. |
style | string | Recorded on the request and echoed back in result.style. It is not sent to the model — put style direction in the prompt itself. |
image | string | A single reference image (https URL or base64 data URI) to guide generation. imageBase64 is an alias. |
referenceImages | string[] | Several reference images at once. Merged with image before the request is sent. |
responseFormat | "url" | "b64_json" | Defaults to "url". Pass "b64_json" to also receive result.b64_json and result.imageBase64 alongside the hosted URL. |
Examples
The same call in five forms. The MCP tab is what an MCP client sends under the hood; the CLI tab is what an agent with the agent skill runs.
curl -X POST "https://api.imagemcpserver.com/playground/generate" \
-H "Authorization: Bearer $IMAGEMCP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Futuristic cyberpunk workstation, glowing neon displays, volumetric haze, highly detailed",
"model": "google/gemini-2.5-flash-image",
"aspectRatio": "16:9"
}'imagemcp.js generate \
--prompt "Futuristic cyberpunk workstation, glowing neon displays" \
--model "google/gemini-2.5-flash-image" \
--aspect-ratio "16:9" \
--out ./workstation.pngconst res = await fetch("https://api.imagemcpserver.com/playground/generate", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.IMAGEMCP_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"prompt": "Futuristic cyberpunk workstation, glowing neon displays, volumetric haze, highly detailed",
"model": "google/gemini-2.5-flash-image",
"aspectRatio": "16:9"
}),
});
const data = await res.json();
console.log(data.result.imageUrl);import os
import requests
res = requests.post(
"https://api.imagemcpserver.com/playground/generate",
headers={"Authorization": f"Bearer {os.environ['IMAGEMCP_API_KEY']}"},
json={
"prompt": "Futuristic cyberpunk workstation, glowing neon displays, volumetric haze, highly detailed",
"model": "google/gemini-2.5-flash-image",
"aspectRatio": "16:9"
},
timeout=120,
)
print(res.json()){
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "generate_image",
"arguments": {
"prompt": "Futuristic cyberpunk workstation, glowing neon displays, volumetric haze, highly detailed",
"model": "google/gemini-2.5-flash-image",
"aspectRatio": "16:9"
}
}
}Response
Response fields
| Field | Type | Description |
|---|---|---|
result.imageUrl | string | Public URL of the generated image. |
result.model | string | Model that actually served the request. |
result.seed | number | Seed recorded for the generation. |
result.latency | string | Wall-clock time for the call, e.g. "4.21s". |
result.hasInputImage | boolean | Whether reference images were supplied. |
deductedCredits | number | Credits taken for this call. |
userCredits | number | Balance remaining after the call. |
{
"success": true,
"message": "Image processed successfully via OpenRouter Images API",
"deductedCredits": 15,
"userCredits": 2485,
"result": {
"imageUrl": "https://cdn.imagemcpserver.com/gen/gen_91827364.png",
"prompt": "Futuristic cyberpunk workstation, glowing neon displays",
"action": "generate",
"hasInputImage": false,
"referenceImagesCount": 0,
"model": "google/gemini-2.5-flash-image",
"style": "photorealistic",
"aspectRatio": "16:9",
"seed": 481923,
"latency": "4.21s",
"cost": "$0.0380",
"deductedCredits": 15,
"userCredits": 2485
}
}When it fails
success: false with a message. See errors & troubleshooting for the status codes and whether a retry is worth it.FAQ
How many credits does generating an image cost?
It depends on the model: the call deducts that model's costPerReq, or 15 credits when no cost is recorded for it. Call /playground/models to see the cost of each model before you generate.
Can I guide generation with an existing image?
Yes. Pass image (or referenceImages for several) as an https URL or base64 data URI. The references are sent to the model alongside your prompt.
How do I get raw bytes instead of a URL?
Send responseFormat: "b64_json". The response then includes result.b64_json and result.imageBase64 in addition to result.imageUrl.