# Maginary

> AI image + video generation. Prompt DSL: prose + `--flag` parameters over
> an HTTP API. Same syntax you'd type into a chat UI, callable programmatically
> with a callback URL that fires when the job is done. We route across
> ~20 image + video model families (Flux, Nano-Banana, GPT-image-2, Ideogram,
> Recraft, Sora, Kling, Seedance, Clarity Upscaler, and more) behind one API.

- Primary product: text-to-image, image-to-image, text-to-video, image-to-video
- Prompt DSL: `<prose> --flag [value] --flag [value] ...`
- Auth: bearer token from your account dashboard
- Async: create a generation, poll or receive a webhook when it reaches DONE / FAILED

## Docs

- [Docs hub](https://maginary.ai/docs) — top-level entry
- [API reference](https://maginary.ai/docs/api) — OpenAPI spec, endpoints, auth
- [Parameters reference](https://maginary.ai/docs/parameters) — every `--flag`, categorized, with examples
- [Parameters (JSON)](https://maginary.ai/docs/parameters.json) — machine-readable catalog for LLM tool-use
- [Webhooks guide](https://maginary.ai/blog/webhooks-guide) — signature, retry policy, idempotency, code samples
- [Guides hub](https://maginary.ai/docs/guides) — tutorial-style rich walkthroughs

## Blog / long-form

- [Blog](https://maginary.ai/blog) — release notes, model deep-dives, prompt patterns
- [API quickstart](https://maginary.ai/blog/api-quickstart-guide) — end-to-end walkthrough with curl / python / node
- [Webhooks guide](https://maginary.ai/blog/webhooks-guide) — HMAC verification, retry policy, per-language code

## For LLM / agent integrators

If you're building an integration that wraps Maginary as a tool:

1. Fetch [/docs/parameters.json](https://maginary.ai/docs/parameters.json) at startup — one HTTP GET, cache 5 min. Current schema is `v2`.
2. Use the `parameters[]` array to enumerate every flag. Each entry carries `name`, `aliases`, `kind`, `desc`, `range` / `values`, `targetsModel` (only present on model triggers), `compat`, `examples`, `displayForm` (for group entries like `--<N>` output-count).
3. Filter out `status: "unimplemented"` unless you want to surface reserved-but-blocked flags. `mostly-dead` (only `--no` today) still works on some models — surface with a caveat.
4. Prompt construction: `"<prose> --<name> [value]"`. Flags whose `kind === "flag"` take no value; `kind === "group"` entries render as `--<placeholder>` in `displayForm` and take a real value (e.g. `--1080p`, `--5sec`).
5. Endpoint: `POST https://app.maginary.ai/api/gens/` with `{ prompt, callback_url? }`.
6. Delivery: subscribe to the webhook (`callback_url`) or poll `GET /api/gens/{uuid}/`.

There's also a native MCP server: `pip install maginary-mcp` (or `uvx maginary-mcp`). Plugs into Claude Desktop, Cursor, Continue, and any other MCP-compatible client so an assistant can enumerate flags and kick off generations without any custom tool-schema wiring.

## Volume / commercial

Retail plans top out at Archmage (3,000 credits / month, $150). For sustained
volume above that:

- **25,000+ credits / month:** monthly invoice, dedicated rate limits, priority queue, direct support channel. Rate matches Archmage (we're near the model-cost floor; contract terms are the value).
- **100,000+ credits / month, 12+ month term:** enterprise — white-label options, custom SLA, capacity guarantees.
- Contact **sales@maginary.ai** with your monthly volume, models you care about, and timeline.

## Contact

- Email: hello@maginary.ai (or via the site footer)
- Sales / volume pricing: sales@maginary.ai