Generate transparent image
https://api.imagemcpserver.com/playground/generate-transparentA two-stage call: the prompt is generated normally, then the subject is isolated and the background is removed. Use it for product shots, mascots, stickers and any asset that has to sit on top of an existing layout. Both the cut-out and the original render are returned, so you can fall back if the isolation is not clean.
Overview
Generate an image from a prompt and return it as a cut-out PNG with a transparent background.
Generation is billed at the model's rate (15 credits by default) plus 8 credits for the cutout pass.
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 | Describe a single clear subject — isolation is cleaner when the scene is not crowded. |
model | string | Model used for the generation stage. Defaults to google/gemini-2.5-flash-image. |
aspectRatio | string | Forwarded to the generation stage. Defaults to "1:1". |
style | string | Recorded and echoed back; put style direction in the prompt. |
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-transparent" \
-H "Authorization: Bearer $IMAGEMCP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Red vintage sports car, three-quarter view, isolated subject, studio lighting",
"aspectRatio": "1:1"
}'imagemcp.js generate_transparent \
--prompt "Red vintage sports car, three-quarter view, isolated subject" \
--out ./car.pngconst res = await fetch("https://api.imagemcpserver.com/playground/generate-transparent", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.IMAGEMCP_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"prompt": "Red vintage sports car, three-quarter view, isolated subject, studio lighting",
"aspectRatio": "1:1"
}),
});
const data = await res.json();
console.log(data.result.imageUrl);import os
import requests
res = requests.post(
"https://api.imagemcpserver.com/playground/generate-transparent",
headers={"Authorization": f"Bearer {os.environ['IMAGEMCP_API_KEY']}"},
json={
"prompt": "Red vintage sports car, three-quarter view, isolated subject, studio lighting",
"aspectRatio": "1:1"
},
timeout=120,
)
print(res.json()){
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "generate_transparent_image",
"arguments": {
"prompt": "Red vintage sports car, three-quarter view, isolated subject, studio lighting",
"aspectRatio": "1:1"
}
}
}Response
Response fields
| Field | Type | Description |
|---|---|---|
result.imageUrl | string | Transparent PNG cut-out. |
result.originalImageUrl | string | The render before the background was removed. |
result.isTransparent | boolean | False when the cutout stage failed and the original was returned. |
deductedCredits | number | Credits taken for both stages. |
userCredits | number | Balance remaining after the call. |
{
"success": true,
"message": "Transparent image generated successfully via OpenRouter + Fal.ai Feynobg",
"deductedCredits": 23,
"userCredits": 2462,
"result": {
"imageUrl": "https://cdn.imagemcpserver.com/trans/trans_82736451.png",
"originalImageUrl": "https://cdn.imagemcpserver.com/gen/gen_82736450.png",
"isTransparent": true,
"prompt": "Red vintage sports car, three-quarter view, isolated subject",
"action": "generate_transparent",
"model": "google/gemini-2.5-flash-image",
"style": "photorealistic",
"aspectRatio": "1:1",
"seed": 733120,
"latency": "9.84s",
"cost": "$0.0630",
"deductedCredits": 23,
"userCredits": 2462
}
}When it fails
success: false with a message. See errors & troubleshooting for the status codes and whether a retry is worth it.FAQ
Why does this cost more than a normal generation?
It runs two stages. You pay the model's generation cost plus 8 credits for the background-removal pass that produces the cut-out.
What happens if the subject cannot be isolated?
The response still returns an image, with result.isTransparent set to false and result.originalImageUrl pointing at the un-cut render.