Skip to main content
Building an agent your customers use? Put Spiral inside it. One API key gives your agent the models it thinks with and the tools it works with (image, video, audio, search, scraping and data), billed per run on your Spiral balance at the providers’ list prices. You add no provider accounts and sign no contracts; your customers never see Spiral. Magica.com serves 2M+ users across 150+ countries, running millions of AI tasks every month, making it one of the fastest-growing AI products in the world.

Tools over MCP

Connect https://api.spiral.ai/mcp as an MCP server. Your agent searches the catalog, checks a price and runs any tool, with no tool code of your own.

Models on the same key

Point your framework’s model client at Spiral’s LLM APIs (Anthropic Messages and OpenAI formats). Claude, GPT, Gemini and the rest, on the same balance.

Set up

Create a key under API keys in the console and store it on your server as SPIRAL_API_KEY. Give it a spend cap: see keys below. Every example on this page uses that one key and nothing else.

Pick your framework

Each example is a complete program. It asks the agent for an image; the agent looks the tool up on Spiral, runs it and answers with the image’s link.
The SDK runs Claude Code’s agent loop. Point it at Spiral for the model and add Spiral as an MCP server. allowedTools keeps the agent to Spiral’s tools, without file or shell access.
Any other framework that speaks MCP (Mastra, Pydantic AI, Google’s ADK, CrewAI and the rest) connects the same way: the URL https://api.spiral.ai/mcp and the header Authorization: Bearer <key>. The MCP tools page lists every tool and its arguments.

Run it in production

Keys and your customers

Your agent’s key stays on your server: never ship it in a browser or app bundle, and never hand it to your customers.
  • One key per agent or deployment, each with its own spend cap and rate limits, created under API keys. A cap is reserved before a run starts, so a runaway loop stops at the cap instead of spending your balance.
  • One key per large customer when you want a hard cap for that customer, or want to revoke one customer’s access without touching the rest.
  • Name the customer on every run with end_user_id (REST, and the MCP run tool) or the X-Spiral-End-User-Id header (LLM APIs). GET /v1/runs?end_user_id=… then lists that customer’s runs and their cost, to bill them from.
If your agent shows prices to your customers, set its key to the customer price view: every amount is then stated in your own unit with your markup, and Spiral’s USD cost is never shown.

Long runs: webhooks or polling

Search, scraping and LLM calls answer in seconds. Images take seconds to a minute; video and long audio can take minutes.
  • Over MCP, the run tool waits up to 60 seconds and returns the finished run; a run still going comes back with its id, and the agent calls get_run until it ends.
  • Over REST, add webhook.url to POST /v1/runs and Spiral posts the finished run to your server, signed: see webhooks. Without a webhook, long-poll GET /v1/runs/{id}?wait_seconds=30.
A run cannot be canceled once it starts, so start it only when the user asked for it. Output links expire after 30 days: copy the files your customers keep to your own storage.

Cost and balance

Every run holds its estimated price before it starts and is charged the measured usage when it ends; the run’s cost shows both.
  • estimate_cost (MCP) or POST /v1/estimate (REST) gives a run’s price before starting it, so your agent can ask your customer before an expensive video.
  • A run your balance or the key’s cap cannot cover is refused before any work, with 402 INSUFFICIENT_BALANCE or a spend-cap error: nothing is charged.
  • A model call holds the most it can cost, its whole output cap included, until it ends. Agent loops send large output caps, so many agents running at once can hold far more than they are charged. Keep headroom in the balance, or lower the output cap where your framework sets one.
  • Turn on auto top-up and balance alerts under Billing, so your agent never stops for lack of credit. See pricing.

Retries without double charges

Send an Idempotency-Key on every POST /v1/runs: a UUID you create for the intent and store with your task. A retry with the same key returns the first run, never a second run or charge. The MCP run tool sends one for you, and the LLM APIs take the same header. See idempotency. Tool errors carry the same codes as the REST API, with retryable saying whether a retry can succeed: see errors.

Next

MCP tools

Every tool your agent can call, with its arguments.

LLM APIs

The models on your key, in Anthropic and OpenAI formats.

Webhooks

Get finished runs pushed to your server, signed.

Pricing

Holds, charges, spend caps and your own prices.