Skip to main content
The Magica API and MCP server shut down on December 1, 2026, and new API keys and MCP connections are paused. Migrate to Spiral with one prompt.
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

1

Sign in

Open magica.com and sign in.
2

Open API Keys

Go to Settings -> API Keys -> Manage.
3

Create a key

Enter a label, click Create key, 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

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.
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.
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 execution.
Check GET /v1/credits/balance before submitting expensive jobs.

6. Start a model run

The response includes a runId. Poll GET /v1/nodes/runs/{runId} until the run reaches COMPLETED, FAILED, or CANCELED.

7. Poll the run

Run-start endpoints return before generation finishes. Save the runId, then poll the matching status endpoint.

OpenAPI spec

The full OpenAPI 3.1 specification is at:
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 a model

Start a standalone model run and poll its result.

Choose an endpoint

Map your integration task to the right REST route.

Concepts

Understand models, standalone runs, credits, and webhooks.