{"openapi":"3.1.0","info":{"title":"imagemcpserver REST API","version":"1.0.0","description":"Generate, edit and transform images over plain HTTP. Every endpoint here is also exposed as an MCP tool, so an agent and a backend service can share one API key and one credit balance.","contact":{"url":"https://imagemcpserver.com/docs/api-reference"}},"servers":[{"url":"https://api.imagemcpserver.com","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Account","description":"Key ownership, credits and usage."},{"name":"Models","description":"Which models a key can route to."},{"name":"Images","description":"Generation, editing and processing."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API key from the dashboard, e.g. `sk-img-gen-...`."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Error":{"type":"object","properties":{"success":{"type":"boolean","const":false},"message":{"type":"string"},"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","not_found_error","rate_limit_error","upstream_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"docs":{"type":"string"}}}}},"ImageResult":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"type":"object","properties":{"imageUrl":{"type":"string","description":"Public URL of the resulting image."},"b64_json":{"type":"string","description":"Base64 payload, present when responseFormat is \"b64_json\"."},"model":{"type":"string"},"seed":{"type":"number"},"latency":{"type":"string"},"style":{"type":"string"}}},"deductedCredits":{"type":"number"},"userCredits":{"type":"number"}}}},"responses":{"InvalidRequest":{"description":"The request body is missing a required field or a value is out of range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"The API key is missing, malformed or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests for this key. Honour the `Retry-After` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServerError":{"description":"Something failed on our side or at the upstream model provider.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1":{"get":{"tags":["Account"],"operationId":"getApiIndex","summary":"API index","security":[],"responses":{"200":{"description":"Endpoint listing"}}}},"/v1/me":{"get":{"tags":["Account"],"operationId":"getAccount","summary":"Account details and credit balance","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"plan":{"type":"string","enum":["free","starter","pro","business"]},"credits":{"type":"number"}}}}}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/usage":{"get":{"tags":["Account"],"operationId":"getUsage","summary":"Recent requests","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"How many log entries to return, newest first."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"count":{"type":"number"},"logs":{"type":"array","items":{"type":"object"}}}}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/models":{"get":{"tags":["Models"],"operationId":"listModels","summary":"List selectable image models","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"count":{"type":"number"},"models":{"type":"array","items":{"type":"object","properties":{"modelId":{"type":"string"},"name":{"type":"string"},"costPerReq":{"type":"number"},"isLive":{"type":"boolean"}}}}}}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/generate":{"post":{"tags":["Images"],"operationId":"generateImage","summary":"Generate an image from a prompt","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","description":"What to draw."},"model":{"type":"string","description":"Model id from /v1/models."},"aspectRatio":{"type":"string","default":"1:1","examples":["1:1","16:9","9:16","4:3","21:9"]},"style":{"type":"string","description":"Recorded and echoed back; put style direction in the prompt."},"image":{"type":"string","description":"Input image as an https URL or a base64 data URI. `imageBase64` is accepted as an alias."},"referenceImages":{"type":"array","items":{"type":"string"}},"responseFormat":{"type":"string","enum":["url","b64_json"],"default":"url","description":"Return a hosted URL (default) or additionally a base64 payload."}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageResult"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/generate-transparent":{"post":{"tags":["Images"],"operationId":"generateTransparentImage","summary":"Generate an image with a transparent background","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string"},"model":{"type":"string"},"aspectRatio":{"type":"string","default":"1:1"},"style":{"type":"string"},"responseFormat":{"type":"string","enum":["url","b64_json"],"default":"url","description":"Return a hosted URL (default) or additionally a base64 payload."}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageResult"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/edit":{"post":{"tags":["Images"],"operationId":"editImage","summary":"Edit an existing image with a prompt","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["image","prompt"],"properties":{"image":{"type":"string","description":"Input image as an https URL or a base64 data URI. `imageBase64` is accepted as an alias."},"prompt":{"type":"string","description":"The change to make."},"action":{"type":"string","enum":["edit","remove_bg","upscale"],"default":"edit"},"model":{"type":"string"},"aspectRatio":{"type":"string"},"responseFormat":{"type":"string","enum":["url","b64_json"],"default":"url","description":"Return a hosted URL (default) or additionally a base64 payload."}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageResult"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/remove-background":{"post":{"tags":["Images"],"operationId":"removeBackground","summary":"Remove the background from an image","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["image"],"properties":{"image":{"type":"string","description":"Input image as an https URL or a base64 data URI. `imageBase64` is accepted as an alias."},"responseFormat":{"type":"string","enum":["url","b64_json"],"default":"url","description":"Return a hosted URL (default) or additionally a base64 payload."}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageResult"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/upscale":{"post":{"tags":["Images"],"operationId":"upscaleImage","summary":"Upscale an image","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["image"],"properties":{"image":{"type":"string","description":"Input image as an https URL or a base64 data URI. `imageBase64` is accepted as an alias."},"scaleFactor":{"type":"string","enum":["2x","4x","8x"],"default":"4x"},"responseFormat":{"type":"string","enum":["url","b64_json"],"default":"url","description":"Return a hosted URL (default) or additionally a base64 payload."}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageResult"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/text-to-svg":{"post":{"tags":["Images"],"operationId":"textToSvg","summary":"Generate vector SVG artwork from a prompt","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string"},"style":{"type":"string","default":"icon"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"type":"object","properties":{"svgCode":{"type":"string"},"dataUrl":{"type":"string"},"imageUrl":{"type":"string"}}},"deductedCredits":{"type":"number"},"userCredits":{"type":"number"}}}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/compress":{"post":{"tags":["Images"],"operationId":"compressImage","summary":"Re-encode an image at a smaller size","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["image"],"properties":{"image":{"type":"string","description":"Input image as an https URL or a base64 data URI. `imageBase64` is accepted as an alias."},"quality":{"type":"integer","minimum":1,"maximum":100,"default":70},"targetFormat":{"type":"string","enum":["webp","jpeg","png"],"default":"webp"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"type":"object","properties":{"image":{"type":"string"},"originalSize":{"type":"string"},"compressedSize":{"type":"string"},"savedPercentage":{"type":"string"},"format":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/convert-format":{"post":{"tags":["Images"],"operationId":"convertFormat","summary":"Convert an image between formats","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["image"],"properties":{"image":{"type":"string","description":"Input image as an https URL or a base64 data URI. `imageBase64` is accepted as an alias."},"targetFormat":{"type":"string","enum":["png","jpeg","webp","avif"],"default":"png"},"responseFormat":{"type":"string","enum":["url","b64_json"],"default":"url","description":"Return a hosted URL (default) or additionally a base64 payload."}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageResult"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/batch":{"post":{"tags":["Images"],"operationId":"batch","summary":"Run several operations in one request","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["requests"],"properties":{"requests":{"type":"array","description":"Each entry names a tool and its arguments.","items":{"type":"object","required":["tool"],"properties":{"tool":{"type":"string","enum":["generate_image","edit_image","remove_background","upscale_image","text_to_svg","compress_image","convert_format","generate_transparent_image"]},"args":{"type":"object"}}}}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"results":{"type":"array","items":{"type":"object"}}}}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}