Skip to main content

Documentation Index

Fetch the complete documentation index at: https://magica.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

A short tour of the building blocks the API exposes. If you’ve used a visual workflow tool before, most of this will be familiar.

​
Workflows

A workflow is a saved graph of nodes connected by edges. Think of it as a function: it takes inputs from a Request Node, runs them through one or more processing nodes, and emits results from a Response Node.

User workflows

Workflows you create and own. Manage them with POST /v1/workflows, PATCH /v1/workflows/{id}, etc.

System workflows

Pre-built templates Magica ships (e.g. “Nano Banana Pro”, “Flux 2 Pro”). Read-only — list with GET /v1/system-workflows.

​
Nodes

A node is a single step in a workflow. Two special scaffold nodes exist in every workflow:

Request Node

Defines workflow inputs. Each input field has a name, type, and optional default value. The values you pass to start_run populate these fields.

Response Node

Defines workflow outputs. Whatever gets wired into the Response Node is what the run returns.
Between Request and Response, you add processing nodes — image generators, LLMs, video models, audio, utilities. Each node belongs to a category:
CategoryExamples
ImageFlux 2 Pro, Nano Banana Pro, GPT Image 1.5
VideoRunway, Kling, Veo
AudioTTS, music generation, sound effects
LLMGPT-5, Claude Sonnet, OpenRouter models
UtilityMerge videos, extract audio, transcription
Scaffold nodes (Request, Response) cannot be deleted. All other nodes can.

​
Ports & edges

Every node has typed input and output ports. An edge is a connection between an output port on one node and an input port on another. 
RequestNode.prompt  →  flux_2_pro.prompt        (text → text)
flux_2_pro.result   →  gpt_5.image_urls         (image → image)
gpt_5.output        →  ResponseNode.result      (text → any)
Edge creation is validated by the server:
  • Type compatibility — image ports can’t feed into text-only inputs.
  • No cycles — workflows are DAGs.
  • Single-input rule — most input ports accept exactly one upstream edge.
Port types: text · image · video · audio · avmedia · file · number · boolean · select · any.

​
Runs

A run is a single execution of a workflow. Runs are asynchronous — POST /v1/runs returns a runId immediately, and the actual execution happens in the background.

States

RUNNING → terminal: COMPLETED, FAILED, or CANCELED.

Get the result

Poll GET /v1/runs/{runId}, or register a webhook on the run to get notified.

​
Run result shape

{
  "runId": "cuid_abc123",
  "status": "COMPLETED",
  "response": { /* Response Node output */ },
  "nodes": [
    { "nodeId": "...", "type": "flux_2_pro", "status": "COMPLETED", "output": { ... } },
    { "nodeId": "...", "type": "gpt_5",      "status": "COMPLETED", "output": { ... } }
  ]
}
The response field surfaces what the Response Node received — usually the only thing you need. nodes gives per-step status + output, useful for debugging partial failures.

​
Run history in the UI

API-triggered runs aren’t invisible — they’re surfaced in the same dashboard your UI runs land in. Use this to debug a failing run, inspect a past result, or copy a runId you forgot to log. Two places to find it:
Open any workflow on the canvas and click the clock icon in the top toolbar to slide out the Execution History panel. Switch to the API Runs tab to filter to runs started via the REST API or MCP server.
Workflow editor toolbar with the Execution History clock icon highlighted
Execution History panel showing API Runs tab with completed runs and credits
The API Runs tab is your friend during integration — it shows the exact runId, status, credits, and timestamp for every call your backend made, side-by-side with the UI runs your team kicked off manually.

​
Webhooks

Instead of polling, subscribe to run events. Add a webhook object to your POST /v1/runs body: 
{
  "workflowId": "wf_abc123",
  "webhook": {
    "url": "https://your-app.com/webhooks/magica",
    "events": ["run.completed", "run.failed"]
  }
}
Magica POSTs to your URL when the listed events fire. Deliveries are signed (HMAC-SHA256) and retried with exponential backoff. Full details on the Webhooks page.

​
Credits

Each run debits credits from your account. Costs depend on the model and parameters used (resolution, duration, etc.).
  • GET /v1/credits/balance — current balance
  • GET /v1/models/catalog — model list with cost structure
  • Canceled runs refund unused estimated credits
When working in MCP, the get_balance and get_pricing tools surface the same information to your AI assistant before kicking off expensive jobs.

​
How it all fits together

1

Define a workflow

Wire processing nodes between the Request and Response scaffold nodes. Save it via POST /v1/workflows.
2

Start a run

Call POST /v1/runs with the workflow ID and any Request Node values.
3

Get the result

Either poll GET /v1/runs/{runId} or wait for the webhook.

​
Next steps

Quickstart

Walk through the API end-to-end with code samples.

MCP Server

Drive all of the above from a Claude or Cursor conversation.