Quickstart - Magica

This guide verifies your API key, discovers a model, inspects its input schema, estimates credits, and starts a model run.

1. Get your API key

Open app.magica.com and sign in.

Open API Keys

Go to Settings -> API Keys -> Manage.

Create a key

Click Create Key, label it, and copy the full gx_... token immediately. It is only shown once.

Store the key in an environment variable like MAGICA_API_KEY. Never paste it in committed code or screenshots.

See Authentication for rate limits, key rotation, and revocation.

2. Base URL

https://api.magica.com/api

Every endpoint in this reference is relative to that base. The current REST version is /v1.

3. List models

Use a read-only call to verify the key and discover model identifiers.

cURL
Node.js
Python

curl https://api.magica.com/api/v1/models \
  -H "Authorization: Bearer $MAGICA_API_KEY"

const res = await fetch("https://api.magica.com/api/v1/models", {
  headers: { Authorization: `Bearer ${process.env.MAGICA_API_KEY}` },
});
const models = await res.json();
console.log(models.map((model) => model.nodeType));

import os, requests

res = requests.get(
    "https://api.magica.com/api/v1/models",
    headers={"Authorization": f"Bearer {os.environ['MAGICA_API_KEY']}"},
)
print([model["nodeType"] for model in res.json()])

A 401 Unauthorized here means the key is missing, malformed, revoked, or expired.

4. Inspect model schema

Pick a modelId from subModels[].subModelId, or use nodeType for a single-mode model.

cURL
Node.js
Python

curl https://api.magica.com/api/v1/models/flux-2-max-text/schema \
  -H "Authorization: Bearer $MAGICA_API_KEY"

const modelId = "flux-2-max-text";
const schema = await fetch(
  `https://api.magica.com/api/v1/models/${modelId}/schema`,
  { headers: { Authorization: `Bearer ${process.env.MAGICA_API_KEY}` } },
).then((res) => res.json());

console.log(schema.fields.filter((field) => field.required));

model_id = "flux-2-max-text"
schema = requests.get(
    f"https://api.magica.com/api/v1/models/{model_id}/schema",
    headers={"Authorization": f"Bearer {os.environ['MAGICA_API_KEY']}"},
).json()

print([field for field in schema["fields"] if field.get("required")])

Use the schema response to render client-side forms and validate required fields before sending payloads to your backend.

5. Estimate credits

Estimate cost before a model or workflow execution.

curl -X POST https://api.magica.com/api/v1/nodes/estimate-credits \
  -H "Authorization: Bearer $MAGICA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nodes": [
      {
        "nodeType": "flux_2_max",
        "subModelId": "flux-2-max-text",
        "input": {
          "prompt": "A cinematic product photo of a glass speaker"
        }
      }
    ]
  }'

Check GET /v1/credits/balance before submitting expensive jobs.

6. Start a model run

curl -X POST https://api.magica.com/api/v1/nodes/flux_2_max/run \
  -H "Authorization: Bearer $MAGICA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subModelId": "flux-2-max-text",
    "input": {
      "prompt": "A cinematic product photo of a glass speaker"
    }
  }'

The response includes a runId. Poll GET /v1/nodes/runs/{runId} until the run reaches COMPLETED, FAILED, or CANCELED. For workflow execution, use POST /v1/runs and poll GET /v1/runs/{runId}.

OpenAPI spec

The full OpenAPI 3.1 specification is at:

https://api.magica.com/api/v1/openapi.json

Import it into Postman, Insomnia, or any OpenAPI-compatible client to generate typed SDKs.

Next steps

Model catalog

Browse available models and their identifiers.

Run workflows

Start workflow runs and poll results.

Concepts

Understand models, nodes, credits, system workflows, and run history.

​1. Get your API key

​2. Base URL

​3. List models

​4. Inspect model schema

​5. Estimate credits

​6. Start a model run

​OpenAPI spec

​Next steps

Model catalog

Run workflows

Concepts

1. Get your API key

2. Base URL

3. List models

4. Inspect model schema

5. Estimate credits

6. Start a model run

OpenAPI spec

Next steps