API reference · Batch

Multicall (parallel batch) — POST /v1/multicall

Updated 7 November 2026

POSThttps://api.imagemcpserver.com/v1/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. POST /v1/batch is an alias of /v1/multicall.

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. Items that fail are refunded when the batch finishes.

Request

Headers

Field	Type	Description
`Authorization`required	`string`	`Bearer <IMAGEMCP_API_KEY>`. The header `x-api-key: <key>` is accepted as an alternative.
`Content-Type`required	`string`	`application/json`

Body parameters

Field	Type	Description
`requests`required	`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 every form we support. 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/v1/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.json

const res = await fetch("https://api.imagemcpserver.com/v1/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/v1/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.
`failedCount`	`number`	How many items failed. Their credits are refunded.
`refundedCredits`	`number`	Credits returned for the failed items.
`deductedCredits`	`number`	Credits kept for the batch — the up-front total minus `refundedCredits`.
`userCredits`	`number`	Balance remaining after the batch and any refund.

200 OK

{
  "success": true,
  "message": "Multicall completed. Processed 3 requests in parallel.",
  "count": 3,
  "failedCount": 0,
  "byok": false,
  "totalLatency": "11.07s",
  "deductedCredits": 43,
  "refundedCredits": 0,
  "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, up front; items that fail are refunded automatically, and the response reports failedCount and refundedCredits.