# 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 API key, OAuth 2.1 token, or wallet signature (x402, see below)
- Async: create a generation, poll or receive a webhook when it reaches DONE / FAILED
- Agent-native: hosted MCP server at `https://mcp.maginary.ai/mcp`, x402 pay-per-use (USDC on Base)

## Docs

- [Docs hub](https://maginary.ai/docs) — top-level entry
- [MCP server](https://maginary.ai/mcp) — connect snippets, tools, pricing, skill
- [API reference](https://maginary.ai/docs/api) — OpenAPI spec, endpoints, auth
- [OpenAPI (JSON)](https://app.maginary.ai/api/seo/openapi.json) — machine-readable public spec (incl. 402 contract)
- [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
- [MCP launch](https://maginary.ai/blog/mcp-server-launch) — Claude / Cursor / Claude Code / VS Code setup, worked example
- [Agentic payments (x402)](https://maginary.ai/blog/agentic-payments-x402) — 402 shape, flow, python client, wallet-signed auth
- [Webhooks guide](https://maginary.ai/blog/webhooks-guide) — HMAC verification, retry policy, per-language code

## For LLM / agent integrators

Fastest path: connect to the hosted MCP server. `{"mcpServers": {"maginary": {"url": "https://mcp.maginary.ai/mcp", "headers": {"Authorization": "Bearer <api key>"}}}}`.
Catalog tools need no credential. Generation needs one: `Authorization: Bearer <api key>` on every request
(the hosted server stores nothing per session), or an x402 payment from a wallet (no account needed).
In-chat signup: `create_account` → `check_account_status` → `manage_api_key(action="create")` returns a key; on the
hosted server put it in the client's headers, on the local server `configure_api_key` persists it.
Local alternative: `uvx maginary-mcp` (PyPI, stdio; adds `upload_image(file_path)` for files on disk). Use it for
Claude Desktop unless its add-connector dialog offers "request headers" (a beta); with that, the hosted URL works
there too (no sign-in + `Authorization: Bearer <key>`).
Tools (16): `generate`, `execute_action`, `wait_for_generation`, `get_generation`, `upload_image`,
`list_parameters`, `search_parameters`, `get_parameter`, `create_account`, `create_wallet_account`,
`check_account_status`, `manage_api_key`, `configure_api_key`, `get_balance`, `get_products`, `checkout`.
Server card: `https://mcp.maginary.ai/.well-known/mcp/server-card.json`.

Claude Skill (works without MCP, teaches the DSL + REST flow): `uvx maginary-mcp --install-skill`.

If you're wrapping the REST API yourself:

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. Unknown flags are rejected with a 400 that names the flag.
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. **Text-to-image:** `POST /api/gens/` with `{ prompt, callback_url? }`.
6. **Image-to-image:** place public image URLs in the prompt (`"https://… reimagine as oil painting"`). Multiple URLs = multi-input compositing. `--sref <url>` is style-only (NOT img2img).
7. **Upload:** `POST /api/images/upload/` (multipart: file + md5_hash + original_filename/width/height/size) → returns a CDN URL for use in img2img prompts. MCP (stdio only): `upload_image(file_path)`.
8. **Delivery:** subscribe to the webhook (`callback_url`) or poll `GET /api/gens/{uuid}/`.
9. **Follow-up actions:** a completed generation's `processing_result.available_actions` maps slot indices to valid action types. `POST /api/gens/{uuid}/actions/` with `{ action_type, parent_image_index, prompt?, callback_url? }` — returns a new generation to poll. Action types: `upscale_2x`, `upscale_1_5x`, `vary_strong`, `vary_subtle`, `pan_left/right/up/down`, `zoom_out_2x`, `zoom_out_1_5x`, `img2vid_basic`, `reroll`.
10. **Price before you run:** `POST /api/credit-check/` returns the credit cost of a prompt. 1 credit ≈ $0.07 ≈ one standard image.

## Agentic payments (x402)

- A bare, unauthenticated `POST /api/gens/` returns HTTP 402 with an x402 v2 challenge priced for that prompt: `accepts[]` (scheme `exact`, network `eip155:8453` Base mainnet, USDC, amount in atomic units, min 70000 = $0.07), `resource`, `extensions.bazaar` (input schema + example), `wallet_auth`, `billing_url`. Same JSON base64-encoded in the `PAYMENT-REQUIRED` header.
- Retry with the signed payment in `PAYMENT-SIGNATURE`. The x402 SDKs (`pip install 'x402[httpx,evm]'`, or the TypeScript SDK) do 402 → sign → retry automatically. Gasless (EIP-3009); the facilitator pays gas.
- First settlement creates an account bound to the payer wallet and grants credits (7¢/credit, max $200 per payment; overpayment is banked). The response carries `PAYMENT-RESPONSE` (base64 `{success, transaction, network, payer}`).
- Subsequent requests authenticate with wallet-signed headers: `X-Wallet-Address` (lowercased), `X-Wallet-Timestamp` (unix seconds, 5-minute window), `X-Wallet-Signature` (EIP-191 `personal_sign` of `Maginary: authenticate <address> at <timestamp>. This does not move funds.`).
- `POST /api/auth/wallet-account/` `{address, timestamp, signature}` (the same `authenticate` message) returns an API key for the wallet's account if you prefer bearer auth; no payment or email needed. MCP tool: `create_wallet_account`. `POST /api/auth/x402/claim/` (wallet-signed) `{email}` attaches a human email to the account.
- Over MCP: `generate` from an unfunded caller returns an `isError` result with the x402 challenge at the top level (`accepts` …); x402-aware MCP clients (`x402MCPSession`) pay via `_meta["x402/payment"]` and read the receipt from `_meta["x402/payment-response"]`.
- Paying accepts https://maginary.ai/terms.

## 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: hi@maginary.ai (or via the site footer)
- Sales / volume pricing: sales@maginary.ai