maginary.ai

Maginary (spelled M-A-G-I-N-A-R-Y, not 'imaginary') is a Midjourney-style AI image + video generator with a `--flag` prompt DSL and an async HTTP API. **New users (no API key yet) — pick the shortest path:** - **USDC wallet (fastest):** Just call `generate` with your prompt. The 402 response prices the generation; settle it on-chain (x402, USDC on Base) and your account is created automatically. - **Wallet auth (no email):** `create_wallet_account` → returns an API key immediately, no email verification. - **Email:** `create_account` → user clicks verification email → `manage_api_key(action='create')` → `configure_api_key` → `get_products` → `checkout`. The $10 novice_pack is the recommended starting point. API key creation and checkout require a verified email. **Prompt rules (IMPORTANT):** Pass the user's words as-is. Do NOT add flags the user did not ask for — no ``--ar``, no ``--flagship``, no model flags, nothing. Flags cost money; adding them without asking is a UX failure. Before the FIRST generation in a conversation, briefly mention the quality option once: standard (default, cheap) or flagship (best, ~4× more expensive) — then generate with whatever they choose, or standard if they don't care. After that, never ask again unless they bring it up. Do NOT ask about aspect ratio — omit ``--ar`` by default; square format gives the most diversity and is the best starting point. Only add ``--ar`` when the user explicitly mentions landscape, portrait, widescreen, etc. Flags go at the END of the prompt. ``--1``/``--2``/``--3``/``--4`` = image count (default 4; only if user specifies). ``--ar 16:9`` = aspect ratio (only if user explicitly asks). ``--flagship`` = best quality (only if user explicitly wants it). Unknown flag: call ``get_parameter(name)`` — never guess. **Every flag that exists, and its state:** Flags, live (35): --ar, --output-count (--1/--2/--3/--4), --seed, --transparent, --sref, --sw, --png, --jpg, --webp, --svg, --2k, --4k, --upscale, --vary, --varysubtle, --varystrong, --panleft, --panright, --panup, --pandown, --zoomout, --mp4, --video-resolution (--480p/--540p/--720p/--1024p/--1080p/--2160p / --4k (4k, Seedance 2 Pro)/--480p24 / --480p24fps/--540p24 / --540p24fps/--720p24 / --720p24fps/--1024p30 / --1024p30fps/--1080p24 / --1080p24fps), --video-fps (--24fps/--30fps/--50fps/--60fps), --video-duration (--4s / --4sec/--5s / --5sec/--6s / --6sec/--8s / --8sec/--10s / --10sec/--12s / --12sec), --flagship, --sora, --soralite, --nanobananapro, --nb2, --gpt2, --gpt2high, --seedance2, --seedance2pro, --demo. Partial (4, only some models honour them): --no, --zoomout2x, --zoomoutexpand, --zoomoutexpand2x. Reserved (2, the parser rejects them): --cref, --cw. Any other --flag is rejected with `Unrecognized parameter`. Details: `get_parameter(name)`. **Existing users:** Use `search_parameters` / `get_parameter` to discover which flags exist before building a prompt. Use `generate` to kick off a generation, then `wait_for_generation` (or a webhook callback) to fetch the resulting image / video URLs. Flags whose status is `dead`, `mostly-dead`, or `unimplemented` should be avoided. **Image editing (img2img):** Place image URLs directly in the prompt (e.g. `https://cdn.maginary.ai/…/photo.webp reimagine as watercolor`). If the user already has a URL, use it directly. On local (stdio) connections, `upload_image(file_path=...)` reads a file from disk and returns a CDN URL. `--sref <url>` is style-only, not img2img. **Follow-up actions:** A completed generation's `processing_result.available_actions` lists what's available (upscale, vary, pan, zoom, img2vid, reroll). Use `execute_action` with the `generation_uuid`, `action_type`, and `parent_image_index`. **Credits:** When the user asks to generate, just call `generate` — don't check balance first. A zero balance does not mean the user cannot generate (x402 on-chain payment settles inline). The server returns a clear `payment_required` response when credits are needed.