API reference

A versioned REST API for generating, editing and processing images. 12 endpoints under /v1, nearly all of them also an MCP tool and a CLI command. Bearer-token auth, JSON in, JSON out.

Request basics

Base URL — https://api.imagemcpserver.com/v1
Auth — Authorization: Bearer <IMAGEMCP_API_KEY>, or x-api-key: <key>. Required on every endpoint.
Content type — application/json on every POST
Images in — an https URL or a base64 data URI, in the image field
Images out — a hosted URL, or base64 when you pass responseFormat: "b64_json"
Versioning — breaking changes ship as a new prefix, never inside /v1

Every image endpoint returns the same top-level shape. The tool-specific output lives under result, and the credit fields appear both at the top level and inside result so either is convenient to read.

200 OK

{
  "success": true,
  "message": "…",
  "deductedCredits": 15,
  "userCredits": 2485,
  "result": { "…": "tool-specific output" }
}

Account endpoints differ

GET /v1/me and GET /v1/usage return their data directly under user and logs — there is no result to unwrap and nothing to bill.

Errors

Anything that is not a 2xx comes back with the same envelope. Switch on error.type for behaviour and error.code for the specific cause — the human-readable message is not stable enough to branch on.

401 Unauthorized

{
  "success": false,
  "message": "That API key is invalid or has been revoked.",
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "That API key is invalid or has been revoked.",
    "docs": "https://imagemcpserver.com/docs/errors"
  }
}

Status	error.type	Meaning
400	invalid_request_error	A required field is missing, or a value is out of range.
401	authentication_error	No key was sent, or the key is malformed or revoked.
404	not_found_error	No such endpoint, or the account behind the key is gone.
429	rate_limit_error	Too many requests for this key. Honour `Retry-After`.
500	api_error	Something failed on our side. Safe to retry with backoff.
502	upstream_error	The model provider failed. Credits are refunded automatically.

A revoked key is a 401, never a 403

Retry logic can therefore treat every 401 the same way: stop, and check the key.

Rate limits

Each API key may make 60 requests per 60 seconds. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 also carries Retry-After in seconds.

The limit protects the upstream model providers from a runaway loop — it is not your billing ceiling. What you can spend is governed by credits, which a single request never exceeds.

OpenAPI spec

The whole API is described by an OpenAPI 3.1 document, served live so it can never drift from what is deployed. Point a client generator, a Postman import or an agent's tool loader at it.

fetch the spec

curl https://api.imagemcpserver.com/v1/openapi.json -o imagemcp-openapi.json

GET https://api.imagemcpserver.com/v1 returns a shorter index of the same endpoints and needs no key, which makes it a quick way to confirm connectivity before you debug auth.