Skip to main content
The Melius REST API drives Melius canvases and generations from your own code — create projects and canvases, add nodes, wire edges, run generations across the latest image, video, audio, and language models, and read the results. It runs on the same backend as the Melius web app, CLI, and MCP server.
You authenticate with an API key. Create one in the Melius app under Team settings → Integrations. See Authentication.

​
Base URL

Every request needs a bearer API key. You can optionally select which team to act on with the x-team-id header — it defaults to the team your key belongs to:

​
How generations work

A generation in Melius is a canvas node — there’s no separate “generate” path, so the API stays consistent with the app. You create a node, start a run, and poll the run until it finishes:
Runs are asynchronous jobs. Starting a run returns immediately with a run id; the generation runs in the background across Melius’s model providers. Poll the run until status is finished (or failed). Pass seed as a top-level field when starting a run. API-key requests preserve it even when the team’s custom-seed UI setting is disabled. The value must be an integer from 0 to 2147483647, inclusive. For image generation, call GET /generation/models?category=image and select a model whose chosen entry in variants has supportsSeed: true.
The node’s configured prompt and model are used. For repeatable requests, keep the model, prompt, inputs, settings, and seed identical. Providers may normalize seed values, and identical requests can still produce different pixels even when the provider honors the seed. API-key bulk runs also preserve seeds configured on their nodes.

​
Post-process a node

Node tools modify a finished asset in place. Use remove-background for image nodes and file nodes that contain images, or topaz-upscale to increase an image’s resolution. remove-background runs Pixelcut. Topaz accepts provider settings through toolConfig, including upscale_factor. Both tools create and activate a new version on the same node.
To upscale an image, send topaz-upscale and its provider settings:
The response is { "id": "<nodeRunId>" }. Poll GET /api/v1/node-runs/<nodeRunId> until the run finishes, just like a generation run.

​
Get the result

When a run finishes, request a download with an empty JSON body ({}):
Fetch the returned URL directly, without your Melius authorization header. The download is a ZIP archive, including for a single image; extract it to read the generated or upscaled file.

​
Rate limits and credits

  • Credits. Generations consume credits from the team you act on, exactly like the app. Image model costs are shown in GET /generation/models?category=image; use category=image_tool for image tools such as Topaz.
  • Rate limits. There is no monthly request quota on any plan. Requests can still return 429 with a Retry-After header — wait the number of seconds it gives you, then retry.
For a temporary 429, use a bounded retry loop: wait at least Retry-After seconds, add a small random delay, and retry the rejected request. The JSON body’s retryAfterSeconds is a fallback if your client cannot read the header. Keep retries within the same concurrency limit. If requests keep returning 429, stop the burst and retry later; this is not a monthly quota error. Only apply that retry policy to an explicit 429. A timeout or 5xx response can leave the outcome of a mutation uncertain; check the canvas or run state before resubmitting to avoid duplicate work. If a canvas’s saved state exceeds the 48 MiB API loading limit, the operation returns 400 with code CANVAS_TOO_LARGE. Use a smaller canvas or create a new canvas. Retrying the same operation will not help.

​
Next steps

Quickstart

Create a key and run your first generation end to end.

Authentication

API keys, the x-team-id header, and how keys are scoped.
Browse every endpoint under API reference in the sidebar — each has a live try it playground and code samples in cURL, Python, TypeScript, PHP, Go, and Ruby.
Last modified on October 7, 2026