Transparent PNG generator API: prompt in, real alpha out.
A transparent PNG generator API turns a text prompt into an image with a genuine alpha channel — the subject isolated and the background actually absent, rather than painted white and merely looking isolated.
That distinction is the whole problem with asking a model for a “transparent background”. This endpoint does it in one call — generate, then run a dedicated cutout pass — and tells you on the response whether the cutout actually happened.
The long way
Two round trips. Two log entries. Two chances to lose the URL.
The short way
One call. One entry in the log. Nothing to sequence.
Why asking for a “transparent background” usually fails
It is the most common complaint about AI image generation, and the cause is straightforward: most image models have no alpha channel to write into. Ask one for a transparent background and it paints something that looks like absence — flat white, or even a drawn-on checkerboard — into ordinary opaque pixels. The file is a valid PNG. It simply has no transparency in it, which you discover the moment you composite it onto a coloured layout and a white box appears around the subject.
There are two honest ways out, and it is worth knowing which one you are buying.
Approach one
Native alpha at generation time
The model itself emits an alpha channel. Edges can be excellent because transparency was never guessed after the fact. The catch is that only some model families support it, so you are choosing a model rather than choosing a picture. Checked September 2026 — this is the part of the landscape moving fastest.
Approach two · this endpoint
Generate, then matte
Render normally with any model in the catalogue, then run a dedicated matting model over the result to cut the subject out. It works with every model rather than a shortlist, and the trade is that the cutout is a second step which can come back empty — so the response tells you whether it did.
What “transparent” actually buys you
A cutout is not a nicer picture — it is a picture that stops being a rectangle. It can overlap a heading, break out of a card, sit on a brand colour that changes with the season, or be dropped into a layout nobody had designed when the asset was made.
- Product tiles — One cutout renders correctly on white, on cream, and in dark mode.
- Stickers & reactions — Alpha is the whole point; a white box around a sticker is the bug.
- Hero compositions — The subject can cross the fold line instead of sitting politely inside it.
- Slide decks — Drop it onto any master template without a matching background.
Check isTransparent before you ship it
Matting is a model, and models sometimes come back with nothing. When that happens this endpoint does not fail the request — it returns the original opaque render so you still have something usable, and sets result.isTransparent to false to say so.
Two consequences worth being blunt about. The response is still a 200 with success: true, so an integration that only checks the status code will happily publish a flat PNG. And the call is billed in full, because the generation half did its work. If the generationfails, by contrast, the entire amount is refunded automatically.
isTransparent: true
The cutout worked. result.imageUrl is a PNG with a real alpha channel.
isTransparent: false
The matting pass came back empty. result.imageUrl is the flat render — same as originalImageUrl.
Generation failed
A 5xx with refundedCredits in the body. Nothing is charged.
The Python and Node samples below both branch on this flag rather than trusting the status code. It is one line, and it is the difference between a catalogue of cutouts and a catalogue with three white rectangles in it that nobody notices until a customer does.
Prompts that cut out cleanly
The matting step needs an obvious subject. You get that by writing the prompt as if you were briefing a studio photographer, not a landscape painter.
"A busy market street in Marrakech at dusk"
"A cosy reading nook with warm light"
"An abstract gradient background"
Nothing here is the subject. Whatever the matting model picks will be arbitrary.
"A single ceramic mug, centred, plain white background"
"A friendly robot mascot, full body, isolated on white"
"One ripe avocado half, top-down, seamless white ground"
One subject, centred, plain ground. The words “isolated” and “plain white background” do most of the work.
The request
One required field. Prompts are screened before they reach the model, so a request that trips the safety check comes back as a 400 rather than a charge.
curl -X POST "https://api.imagemcpserver.com/v1/generate-transparent" \
-H "Authorization: Bearer $IMAGEMCP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A single ceramic mug in warm terracotta,
centred, isolated on a plain white background",
"aspectRatio": "1:1"
}'The response
Both images come back: the cutout as imageUrl and the flat render as originalImageUrl, so you can compare them or fall back without paying twice.
{
"success": true,
"deductedCredits": 23,
"userCredits": 2396,
"result": {
"imageUrl": "https://cdn.imagemcpserver.com/transparent/tr_8821.png",
"originalImageUrl": "https://cdn.imagemcpserver.com/gen/gen_8820.png",
"isTransparent": true,
"action": "generate_transparent",
"model": "google/gemini-2.5-flash-image",
"aspectRatio": "1:1",
"seed": 771204,
"latency": "9.84s"
}
}Python and Node
Both samples do the one thing that matters: they refuse to continue when the cutout did not happen.
import os, requests
r = requests.post(
"https://api.imagemcpserver.com/v1/generate-transparent",
headers={"Authorization": f"Bearer {os.environ['IMAGEMCP_API_KEY']}"},
json={
"prompt": "A single ceramic mug, centred, isolated on a plain white background",
"aspectRatio": "1:1",
},
timeout=180,
)
result = r.json()["result"]
if not result["isTransparent"]:
raise RuntimeError(f"cutout failed, got the flat render: {result['originalImageUrl']}")
print(result["imageUrl"])const res = await fetch(
"https://api.imagemcpserver.com/v1/generate-transparent",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.IMAGEMCP_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ prompt, aspectRatio: "1:1" }),
},
);
const { result } = await res.json();
if (!result.isTransparent) throw new Error("cutout did not happen");
console.log(result.imageUrl);Every field
The same body works for the REST endpoint and the generate_transparent_image MCP tool.
| Field | Accepts | What it does |
|---|---|---|
prompt | string · required | Describe one clear subject. Naming a plain ground — “isolated on a plain white background” — measurably improves the cutout. |
aspectRatio | 1:1 · 16:9 · 9:16 · 4:3 · 3:4 · 21:9 | Defaults to 1:1, and genuinely reaches the model. Square is usually right for a cutout: the alpha region is the subject, not the canvas. |
referenceImages | string[] | Two or three existing assets that steer palette and treatment, so a batch comes back as one family. |
model | string | A model ID for the generation half. Omit it to use the account default; the cutout pass is fixed either way. |
responseFormat | url · b64_json | Defaults to url. b64_json adds result.b64_json and result.imageBase64 to the same response. |
style | string | Recorded on the request and echoed back as result.style. It is not sent to the model — put style direction in the prompt instead. |
What it costs, spelled out
Two stages, billed together and taken up front: the model’s generation rate, plus a flat 8 credits for the cutout pass.
Default model
23 credits
15 to generate, 8 to cut out. Roughly 29–46¢ depending on plan.
Fast model
16 credits
8 to generate, 8 to cut out. The sensible tier for drafts.
With your OpenRouter key
10 credits
2 platform fee, 8 for the cutout on our own provider.
The free plan is 30 credits a month, which is one transparent image on the default model — enough to judge the edges on your own subject before paying. How bring-your-own-key pricing works, or see plans and credit packs.
Transparent image questions
Why does asking a model for a “transparent background” usually not work?
Because most image models have no alpha channel to write to. They paint a plausible-looking white or checkerboard background into the pixels and hand you an opaque PNG that merely looks isolated. It only becomes obvious when you composite it onto a coloured layout and a white box appears around the subject. Getting real transparency means either a model that generates alpha natively, or a separate cutout pass over the finished render — which is what this endpoint does.
How do I know the cutout actually worked?
Check result.isTransparent on the response. It is true when the matting pass returned a cut-out and false when it did not, in which case result.imageUrl is the original opaque render and result.originalImageUrl points at the same thing. Reading that flag before you ship the asset is the single most useful line of code you can write against this endpoint.
Am I still charged if the cutout fails?
Yes, and we would rather say so here than have you find out from an invoice. Credits are taken up front for both stages. If the generation itself fails the whole amount is refunded automatically, but if generation succeeds and only the cutout pass comes back empty, the call is billed in full and answers 200 with isTransparent set to false. That is the case worth branching on.
Why not just generate and then remove the background myself?
You can, and the result is the same. This tool exists because it is one call instead of two — one round trip, one log entry, one thing for an agent to get right, and one set of credits taken atomically rather than two that can half-fail. On a batch of forty assets that difference is real.
What does it cost?
The model’s generation cost plus 8 credits for the cutout. On the default model that is 23 credits, roughly 29 to 46 cents depending on your plan. With your own OpenRouter key on a paid plan it is 10 — a flat 2-credit platform fee plus the 8-credit cutout, which runs on our own provider either way.
What kinds of subject cut out well?
Single, clearly bounded objects on a plain ground: products, mascots, icons, food, isolated characters. Prompts that describe a full scene give the matting step nothing obvious to isolate — ask for “on a plain white background” and it does much better. Hair, fur, glass and motion blur are the hard cases here as everywhere.
Can I control the aspect ratio?
Yes, all six ratios are available and this one genuinely reaches the model. Remember the alpha region is the subject, not the canvas — a 16:9 transparent PNG of a coffee cup is mostly empty space, which is usually not what you want. Square is the sane default for cutouts.
Can I steer it towards my brand style?
Pass referenceImages with two or three existing assets. That is how a set of twenty stickers or product renders comes back looking like one family instead of twenty separate experiments. Note that the separate style field does not do this — it is recorded and echoed back but never sent to the model, so style direction belongs in the prompt text.
Can I generate a batch of cutouts at once?
Yes, through multicall — the calls are dispatched concurrently and billed as a single deduction. Keep the same phrasing for the ground and the framing across every prompt so the set stays consistent.
Where do the finished cutouts live?
The cut-out is uploaded to Cloudflare R2 and returned as a hosted https URL in result.imageUrl, and the un-cut render stays available at result.originalImageUrl so you can fall back or compare. Pass responseFormat: "b64_json" to also get the bytes in the same response.
Already have the photo? Use background removal instead — 8 credits, no generation step.