Multicall (parallel batch)
POST
https://api.imagemcpserver.com/playground/multicall💳 Sum of the batch🛠️ MCP tool: multicall⌘ imagemcp.js multicall
Takes an array of { tool, args } objects and executes them in parallel, returning one result per item in the order you sent them. This is the difference between an agent that generates twelve assets in twelve round-trips and one that does it in a single call — and it is where the latency win is largest.
Overview
Run several image tools concurrently in a single request.
Every item is priced by its own tool and the total is deducted once, up front, before the batch runs.
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 |
|---|---|---|
requestsrequired | Array<{ tool: string, args: object }> | One entry per operation. tool is any tool name on this page (generate_image, edit_image, remove_background, upscale_image, text_to_svg, compress_image, convert_format, generate_transparent_image) and args is that tool's own body. |
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.
multicall
curl -X POST "https://api.imagemcpserver.com/playground/multicall" \
-H "Authorization: Bearer $IMAGEMCP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"requests": [
{
"tool": "generate_image",
"args": {
"prompt": "Cyberpunk city street at night",
"aspectRatio": "16:9"
}
},
{
"tool": "generate_transparent_image",
"args": {
"prompt": "Neon hoverbike, isolated subject"
}
},
{
"tool": "text_to_svg",
"args": {
"prompt": "Minimalist lightning bolt icon"
}
}
]
}'# The CLI takes the same array from a JSON file
imagemcp.js multicall ./batch_requests.jsonconst res = await fetch("https://api.imagemcpserver.com/playground/multicall", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.IMAGEMCP_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"requests": [
{
"tool": "generate_image",
"args": {
"prompt": "Cyberpunk city street at night",
"aspectRatio": "16:9"
}
},
{
"tool": "generate_transparent_image",
"args": {
"prompt": "Neon hoverbike, isolated subject"
}
},
{
"tool": "text_to_svg",
"args": {
"prompt": "Minimalist lightning bolt icon"
}
}
]
}),
});
const data = await res.json();
console.log(data.results);import os
import requests
res = requests.post(
"https://api.imagemcpserver.com/playground/multicall",
headers={"Authorization": f"Bearer {os.environ['IMAGEMCP_API_KEY']}"},
json={
"requests": [
{
"tool": "generate_image",
"args": {
"prompt": "Cyberpunk city street at night",
"aspectRatio": "16:9"
}
},
{
"tool": "generate_transparent_image",
"args": {
"prompt": "Neon hoverbike, isolated subject"
}
},
{
"tool": "text_to_svg",
"args": {
"prompt": "Minimalist lightning bolt icon"
}
}
]
},
timeout=120,
)
print(res.json()){
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "multicall",
"arguments": {
"requests": [
{
"tool": "generate_image",
"args": {
"prompt": "Cyberpunk city street at night",
"aspectRatio": "16:9"
}
},
{
"tool": "generate_transparent_image",
"args": {
"prompt": "Neon hoverbike, isolated subject"
}
},
{
"tool": "text_to_svg",
"args": {
"prompt": "Minimalist lightning bolt icon"
}
}
]
}
}
}Response
Response fields
| Field | Type | Description |
|---|---|---|
count | number | Number of items processed. |
totalLatency | string | Wall-clock time for the whole batch. |
results[].tool | string | Tool that ran for this item. |
results[].success | boolean | Per-item outcome — one failure does not fail the batch. |
results[].data | object | That tool's normal response body. |
deductedCredits | number | Total credits taken for the batch. |
{
"success": true,
"message": "Multicall completed successfully. Processed 3 requests in parallel.",
"count": 3,
"totalLatency": "11.07s",
"deductedCredits": 43,
"userCredits": 2374,
"results": [
{
"tool": "generate_image",
"status": 200,
"success": true,
"data": {
"success": true,
"result": { "imageUrl": "https://cdn.imagemcpserver.com/gen/gen_1.png" }
}
},
{
"tool": "generate_transparent_image",
"status": 200,
"success": true,
"data": {
"success": true,
"result": { "imageUrl": "https://cdn.imagemcpserver.com/trans/trans_2.png" }
}
},
{
"tool": "text_to_svg",
"status": 200,
"success": true,
"data": {
"success": true,
"result": { "svgCode": "<svg …>" }
}
}
]
}When it fails
Errors return
success: false with a message. See errors & troubleshooting for the status codes and whether a retry is worth it.FAQ
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.