Quickstart
Get an API key, make your first image generation call, and connect an agent — the whole path from empty terminal to a hosted image URL takes about five minutes.
1. Get an API key
- 1
Create an account
Sign in with Google or GitHub. New accounts start on the free tier with 30 credits a month — no card required.
- 2
Open the API keys tab
In the dashboard, open the
API keystab and create one. Copy it immediately — the full key is shown once, at creation. - 3
Put it in your environment
terminal export IMAGEMCP_API_KEY="sk-img-gen-…"
2. Your first call
The smallest useful request is a prompt sent to POST /playground/generate. Everything else — model, aspect ratio, reference images — has a sensible default.
curl -X POST "https://api.imagemcpserver.com/playground/generate" \
-H "Authorization: Bearer $IMAGEMCP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A paper-craft fox standing in tall grass, soft morning light",
"aspectRatio": "16:9"
}'const 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: "A paper-craft fox standing in tall grass, soft morning light",
aspectRatio: "16:9",
}),
});
const { result } = await res.json();
console.log(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": "A paper-craft fox standing in tall grass, soft morning light",
"aspectRatio": "16:9",
},
timeout=120,
)
print(res.json()["result"]["imageUrl"])What this costs
google/gemini-2.5-flash-image. See credits & pricing for the full table.3. Read the response
A successful call returns the hosted image URL plus what it cost you. deductedCredits is what this call took and userCredits is what is left, so a loop can track spend without a second request.
{
"success": true,
"deductedCredits": 15,
"userCredits": 2485,
"result": {
"imageUrl": "https://cdn.imagemcpserver.com/gen/gen_91827364.png",
"model": "google/gemini-2.5-flash-image",
"aspectRatio": "16:9",
"latency": "4.21s"
}
}If the call fails, success is false and message explains why. Insufficient balance also returns currentCredits and requiredCredits so you can tell the user exactly how short they are.
4. Connect an agent
Direct HTTP is the quickest way to see something work, but the point of the server is that an agent can call it on its own. Two routes, depending on where your agent lives:
FAQ
Do I need a credit card to try it?
No. New accounts start on the free tier with 30 credits per month, which is enough to try every tool at least once.
How long does a generation take?
The response includes result.latency for the exact call. Generation is typically a few seconds; compression and format conversion return in well under a second because no model is involved.
What do I get back — a URL or the image bytes?
A hosted URL by default, in result.imageUrl. Pass responseFormat: "b64_json" on the image tools if your agent needs the bytes inline.