Documentation FAQ
The questions that come up most often about connecting an agent, what calls cost, which models run, and how the API behaves when things go wrong.
General
What is imagemcpserver?
One service that gives an AI agent eleven image tools — generation, transparent generation, editing, background removal, upscaling, vector SVG, compression, format conversion, batching, plus account and model lookups. The same tools are reachable over MCP, through an agent skill CLI, and as a plain REST API.
Do I need an MCP client to use it?
No. MCP is one of three ways in. If you are writing your own code, the REST API needs nothing more than an HTTP client and a bearer token.
Which AI clients can use the tools?
Any client that speaks the Model Context Protocol can connect to the hosted MCP endpoint, and any agent that can run shell commands can use the skill CLI instead.
Is there a free tier?
Yes — new accounts get 30 credits a month with no card required, which is enough to try every tool.
Which model runs by default?
google/gemini-2.5-flash-image. Pass a different modelId from list_models to route elsewhere, or omit the parameter entirely.
How are credits charged?
Flat-rate tools always cost the same: 8 for background removal, 15 for upscaling, 5 for text-to-SVG, 1 each for compression and format conversion. Generation and editing cost whatever the model costs, defaulting to 15 credits when no cost is recorded.
Do I get an image URL or the raw bytes?
A hosted URL by default, in result.imageUrl. Send responseFormat: "b64_json" on the image tools to also receive base64.
What happens if a generation fails after credits are deducted?
Credits are taken before the model runs and are not returned automatically on failure. Cap your retries and contact support if a run fails repeatedly.
Can I generate several images in one request?
Yes — multicall takes an array of tool calls, runs them concurrently, and returns one result per item.
Per tool
Questions specific to individual endpoints. Each answer links back to the reference page it came from.
Does checking my credit balance cost credits?
No. Both /auth/user-data and /playground/models are free to call and never deduct credits.
Can an agent read the balance before generating images?
Yes — that is the intended pattern. Call the get_user_info tool first, compare user.credits against the cost of the work you are about to queue, and stop early if the balance is short.
Which model is used when I omit the model parameter?
Requests fall back to google/gemini-2.5-flash-image. The same fallback applies when the model you pass is not an image model.
How do I know what a model will cost me?
Read costPerReq on the model entry. Model-priced tools deduct exactly that amount, or 15 credits when a model has no cost recorded.
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.
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.
Do I need to supply a mask?
No. The edit is driven by your instruction rather than a mask channel — describe the region you want changed in the prompt.
What is the difference between edit_image and remove_background?
edit_image with action "remove_bg" routes through the general image model, while remove_background runs a dedicated cutout model. For clean alpha cut-outs, use remove_background.
What does background removal cost?
A flat 8 credits per call — it does not vary with image size or the model you have selected elsewhere.
Can I send a local file?
Send it as a base64 data URI in the image field. Both https URLs and data URIs are accepted.
Does a larger scale factor cost more?
No. Upscaling is a flat 15 credits per call whatever scale factor you request.
Should I upscale before or after editing?
After. Editing a small image and upscaling last preserves the detail the upscaler adds; doing it the other way round discards it.
Do I get SVG source or an image of a vector?
Source. result.svgCode contains the markup, so you can edit paths, recolour with CSS and inline it in a component.
What kind of prompts work best for vectors?
Simple, bounded subjects: icons, logotypes, badges, mascots. Photographic scenes and heavy gradients do not vectorise well — use generate_image for those.
Is the compressed image returned as a URL?
No — it comes back as a base64 data URI in result.image, together with the original and compressed sizes.
What quality should I use?
70 is the default and holds up well for web delivery. Drop toward 40–50 when you are shrinking images to fit an agent's context window and fine detail does not matter.
How is this different from compress_image?
convert_format changes the container without a quality setting; compress_image re-encodes at a quality you choose and reports how much size was saved. Use compress when the goal is a smaller file.
What happens if one item in the batch fails?
The rest still run. Each entry in results carries its own success flag and status, so you can retry only the items that failed.
How are credits charged for a batch?
Each item is priced by its own tool and the total is deducted once, before the batch runs. Credits spent on an item that then fails are not returned automatically — contact support if a batch fails badly.