maginary-mcp

List Maginary prompt-DSL parameters. Args: category: Restrict to one category (e.g. ``composition``, ``video``, ``model``, ``outpaint``). Call with no filters once — the response's ``categories`` / ``statuses`` maps are the full taxonomy. status: Restrict to one status (``live``, ``mostly-dead``, ``unimplemented``). include_reserved: When False (default) drop ``unimplemented`` (recognized-but-blocked) parameters from the result. Returns: A dict with ``count``, ``source`` (``live`` vs. ``bundled-snapshot``), ``categories`` / ``statuses`` (the filter taxonomy), and ``parameters`` (the array of matching entries).

{
  "type": "object",
  "properties": {
    "category": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Filter by category, e.g. composition, video, model, outpaint.",
      "title": "Category"
    },
    "status": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Filter by status: live, mostly-dead, or unimplemented.",
      "title": "Status"
    },
    "include_reserved": {
      "default": false,
      "description": "Include unimplemented (blocked) parameters.",
      "title": "Include Reserved",
      "type": "boolean"
    }
  },
  "title": "list_parametersArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "list_parametersDictOutput"
}

Text-search over parameter names, aliases, descriptions, values, examples. Args: query: Substring match, case-insensitive. category: Optional single-category restriction. include_reserved: Whether to include ``unimplemented`` parameters. Returns: Dict with ``count``, ``source`` (``live`` vs. ``bundled-snapshot``), and ``parameters`` (ordered as they appear in the catalog).

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Search term (case-insensitive substring match).",
      "title": "Query",
      "type": "string"
    },
    "category": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Filter by category, e.g. composition, video, model.",
      "title": "Category"
    },
    "include_reserved": {
      "default": false,
      "description": "Include unimplemented (blocked) parameters.",
      "title": "Include Reserved",
      "type": "boolean"
    }
  },
  "required": [
    "query"
  ],
  "title": "search_parametersArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "search_parametersDictOutput"
}

Return the full record for a single parameter (canonical name or alias). Args: name: Parameter name with or without leading ``--`` (e.g. ``ar``, ``--ar``, ``aspect``). Case-insensitive. Returns: The parameter dict. Not-found is an ``isError`` result — surface it rather than fabricating a param.

{
  "type": "object",
  "properties": {
    "name": {
      "description": "Parameter name with or without --, e.g. ar, --ar, aspect.",
      "title": "Name",
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "title": "get_parameterArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "get_parameterDictOutput"
}

Kick off a generation via POST /api/gens/. Args: prompt: The user's words, passed through as-is. Do NOT add flags the user did not ask for — no ``--ar``, no ``--flagship``, no model flags. Every extra flag costs credits; adding them unrequested is wrong. Standard quality is the default and is cheap; ``--flagship`` is ~4× more expensive and must only be used when the user explicitly asks for best quality. If the user asks about quality or aspect ratio: ask them first (standard vs flagship, landscape vs portrait) before generating. Flags go at the END, only when the user asked: ``--1``/``--2``/``--3``/``--4`` = image count (default 4), ``--ar 16:9`` = aspect ratio, ``--flagship`` = best quality. Unknown flag: call ``get_parameter(name)`` first — never guess. Examples — user says "a fox": prompt is ``"a fox"``. User says "a fox, landscape, best quality": prompt is ``"a fox --ar 16:9 --flagship"``. **Image-to-image (img2img):** Place one or more public image URLs in the prompt, followed by editing instructions: ``"https://cdn.example.com/photo.webp reimagine as oil painting --ar 16:9"`` The engine extracts URLs automatically and switches to img2img mode. Multiple URLs trigger multi-input mode (compositing/combining). Use ``upload_image`` first if images aren't already hosted. **Image-to-video:** Place an image URL in the prompt AND add ``--mp4`` plus video flags (``--5sec``, ``--1080p``). Or use ``execute_action`` with ``action_type="img2vid_basic"`` on a completed generation's image. **Style reference (--sref) is NOT img2img:** ``--sref <url>`` copies the visual *style* of a reference image (colors, mood, composition) without using the image content as input. A bare URL in the prompt edits the actual image; ``--sref`` transfers style. callback_url: Optional HTTPS URL that will receive a webhook when the generation reaches done / failed. See https://maginary.ai/blog/webhooks-guide for signature verification. Returns: On success, the created generation record. Key fields: ``uuid`` (use to poll), ``action_type``, ``processing_state``, ``expected_output_count``. On failure, an ``isError`` result instead (nothing is raised), with a JSON body whose ``error`` field is one of: - ``"auth"`` — no/invalid API key. Surface the message directly to the human. - ``"payment_required"`` — out of credits. The body carries ``billing_url`` and top-level x402 fields (``accepts``, ``resource``): either send the human to ``billing_url`` to top up, or pay programmatically via x402 (settle ``accepts[0]`` with USDC on Base and retry). - ``"demo_not_found"`` — ``--demo`` prompt has no matching seeded generation. ``available_demos`` lists valid prompts. - ``"failed"`` — anything else (invalid prompt, rate limit, backend or network error); see ``message``. x402 over MCP: a ``payment_required`` result also carries the x402 fields at the top level (``accepts``, ``resource``); an x402-capable client signs ``accepts[0]`` and calls this tool again with the payment in ``_meta["x402/payment"]``. The settled call returns the generation with ``x402_receipt`` (and ``_meta["x402/payment-response"]``); a wallet's first settlement creates its account. Subsequent requests use wallet-signed auth headers (X-Wallet-Address/Signature/Timestamp) or pass an API key as ``_meta["maginary/api_key"]``. 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)`.

{
  "type": "object",
  "properties": {
    "prompt": {
      "description": "The user's words as-is, flags at the end. Do NOT add flags the user did not ask for.",
      "title": "Prompt",
      "type": "string"
    },
    "callback_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "HTTPS webhook URL for done/failed notifications.",
      "title": "Callback Url"
    }
  },
  "required": [
    "prompt"
  ],
  "title": "generateArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "generateDictOutput"
}

Fetch a generation by UUID (GET /api/gens/{uuid}/). Args: uuid: The UUID returned by ``generate``. Returns: The full generation record. If terminal, ``image_urls[]`` holds the finished outputs and ``processing_result.slots[]`` the per-slot detail. NOTE: a generation that failed server-side is a SUCCESSFUL tool call returning ``processing_state: "failed"`` — always check the state, never infer success from the absence of a tool error. **Follow-up actions:** A completed generation's ``processing_result.available_actions`` maps slot indices to valid action types. E.g. ``{"0": ["upscale_2x", "vary_strong", ...], "global": ["reroll"]}``. Use ``execute_action`` with the ``uuid``, a chosen ``action_type``, and the ``parent_image_index`` (the slot key as an int) to run an action. Hosted: a key obtained mid-session may be passed as ``_meta["maginary/api_key"]``.

{
  "type": "object",
  "properties": {
    "uuid": {
      "description": "Generation UUID from generate or execute_action.",
      "title": "Uuid",
      "type": "string"
    }
  },
  "required": [
    "uuid"
  ],
  "title": "get_generationArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "get_generationDictOutput"
}

Poll ``get_generation`` on a backoff until it reaches done / failed. Args: uuid: The UUID returned by ``generate``. timeout_s: Return after this many seconds even if still running. Default 45 stays under the 60 s per-call limit most MCP clients enforce; a ``timeout`` result just means "call again". Only raise it (e.g. for video) on clients you know allow long tool calls. Returns: The terminal generation record — which includes generations that failed server-side: those are SUCCESSFUL tool calls returning ``processing_state: "failed"`` with empty ``image_urls``, so always check the state. On tool failure, an ``isError`` result whose ``error`` field is ``"timeout"`` (``message`` names the last observed state — the generation keeps running server-side and can be re-fetched with ``get_generation`` later), ``"auth"``, or ``"failed"``. **Follow-up actions:** A ``done`` generation's ``processing_result.available_actions`` maps slot indices to valid action types — e.g. ``{"0": ["upscale_2x", "vary_strong", "pan_left", "zoom_out_2x", "img2vid_basic", ...], "global": ["reroll"]}``. Use ``execute_action`` with the ``uuid``, a chosen ``action_type``, and the ``parent_image_index`` (the slot key as an int) to run an action on a specific output image.

{
  "type": "object",
  "properties": {
    "uuid": {
      "description": "Generation UUID to poll.",
      "title": "Uuid",
      "type": "string"
    },
    "timeout_s": {
      "default": 45,
      "description": "Max seconds to wait before returning a timeout result.",
      "title": "Timeout S",
      "type": "number"
    }
  },
  "required": [
    "uuid"
  ],
  "title": "wait_for_generationArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "wait_for_generationDictOutput"
}

Upload a local image and get a CDN URL for img2img or ``--sref``. Only available on local (stdio) connections. On hosted/remote connections, place an existing image URL directly in the prompt. Place the returned ``url`` in a ``generate`` prompt: ``generate("https://cdn.maginary.ai/…/photo.webp reimagine as oil painting")`` Args: file_path: Path to an image file on disk (JPEG, PNG, WebP, HEIC). filename: Original filename. Inferred from ``file_path`` if omitted. Returns: Dict with ``url`` (the public CDN URL), ``exists`` (deduplicated), ``credits_deducted``, and ``message``.

{
  "type": "object",
  "properties": {
    "file_path": {
      "description": "Path to a local image (JPEG, PNG, WebP, HEIC).",
      "title": "File Path",
      "type": "string"
    },
    "filename": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Override filename. Inferred from file_path if omitted.",
      "title": "Filename"
    }
  },
  "required": [
    "file_path"
  ],
  "title": "upload_imageArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "upload_imageDictOutput"
}

Run a follow-up action on a completed generation's image. After ``generate`` → ``wait_for_generation``, the response's ``processing_result.available_actions`` lists what's possible per slot. Call this tool with one of those action types. Args: generation_uuid: UUID of the parent generation (from ``generate``). action_type: One of the values from ``available_actions`` — e.g. ``"upscale_2x"``, ``"upscale_1_5x"``, ``"vary_strong"``, ``"vary_subtle"``, ``"pan_left"``, ``"pan_right"``, ``"pan_up"``, ``"pan_down"``, ``"zoom_out_2x"``, ``"zoom_out_1_5x"``, ``"img2vid_basic"``, ``"reroll"``. parent_image_index: The slot index of the image to act on (0, 1, 2, or 3 for a 4-image grid). Required for per-slot actions; omit for ``"reroll"`` (global action). prompt: Optional replacement prompt. For ``vary_*`` you can steer the variation with a new prompt; for ``img2vid_basic`` you can describe the desired motion. callback_url: Optional webhook URL (same as ``generate``). Returns: The newly created child generation record (same shape as ``generate``'s return — poll it with ``wait_for_generation``). On failure, same ``isError`` contract as ``generate``: ``"auth"``, ``"payment_required"`` (with x402 challenge), or ``"failed"``.

{
  "type": "object",
  "properties": {
    "generation_uuid": {
      "description": "UUID of the parent generation.",
      "title": "Generation Uuid",
      "type": "string"
    },
    "action_type": {
      "description": "Action from available_actions, e.g. upscale_2x, vary_strong, img2vid_basic, reroll.",
      "title": "Action Type",
      "type": "string"
    },
    "parent_image_index": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Slot index (0-3) of the image to act on. Omit for global actions like reroll.",
      "title": "Parent Image Index"
    },
    "prompt": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional replacement prompt for vary/img2vid actions.",
      "title": "Prompt"
    },
    "callback_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "HTTPS webhook URL for done/failed notifications.",
      "title": "Callback Url"
    }
  },
  "required": [
    "generation_uuid",
    "action_type"
  ],
  "title": "execute_actionArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "execute_actionDictOutput"
}

Create a new Maginary account for the given email address. Returns the auto-generated password — display it to the user ONCE so they can save it. A verification email is sent; the user must click the link before the account can generate images. After verification, use ``manage_api_key(action='create')`` with ``email`` + ``password`` to get an API key, then ``configure_api_key`` to activate it. Args: email: The user's email address. Returns: Dict with ``email``, ``password``, and ``message``. On failure, an ``isError`` result — e.g. ``error: "already_exists"`` (email taken: ask the user for their password or a different email), ``"rate_limited"``, or ``"failed"``.

{
  "type": "object",
  "properties": {
    "email": {
      "description": "Email address for the new account.",
      "title": "Email",
      "type": "string"
    }
  },
  "required": [
    "email"
  ],
  "title": "create_accountArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "create_accountDictOutput"
}

Create (or access) a Maginary account using a wallet signature. Sign the message ``Maginary: authenticate <address> at <timestamp>. This does not move funds.`` with EIP-191 ``personal_sign`` and pass all three values. On success, an API key is returned immediately — no email verification needed. Use this when you have a wallet but no email. The returned ``api_key`` should be passed as ``Authorization: Bearer <key>`` in the MCP client config, or via ``configure_api_key`` (stdio) / ``_meta["maginary/api_key"]`` (hosted, per-call). If the wallet already has an account, returns the existing account with a fresh API key. Args: address: EVM wallet address (0x..., 42 chars). signature: Hex-encoded EIP-191 personal_sign of the auth message. timestamp: Unix epoch seconds used in the signed message (must be within the last 5 minutes). Returns: Dict with ``address``, ``api_key`` (full key — show once), ``key_prefix``, ``created`` (bool), ``message``. On failure: ``isError`` with ``error`` = ``"validation"``, ``"signature_failed"``, or ``"rate_limited"``.

{
  "type": "object",
  "properties": {
    "address": {
      "description": "EVM wallet address (0x..., 42 chars).",
      "title": "Address",
      "type": "string"
    },
    "signature": {
      "description": "Hex EIP-191 personal_sign of the auth message.",
      "title": "Signature",
      "type": "string"
    },
    "timestamp": {
      "description": "Unix epoch seconds used in the signed message.",
      "title": "Timestamp",
      "type": "integer"
    }
  },
  "required": [
    "address",
    "signature",
    "timestamp"
  ],
  "title": "create_wallet_accountArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "create_wallet_accountDictOutput"
}

Check account verification status, credit balance, and API key count. Use this after ``create_account`` to poll whether the user has clicked the verification link. Pass ``email`` + ``password`` (from ``create_account``) for Basic auth, or omit both to use the configured API key. Args: email: Account email (for Basic auth). password: Account password (for Basic auth). Returns: Dict with ``verified`` (bool), ``email``, ``api_key_count``, ``credits_remaining``, ``uploads_remaining``.

{
  "type": "object",
  "properties": {
    "email": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Account email (for Basic auth). Omit to use API key.",
      "title": "Email"
    },
    "password": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Account password (for Basic auth).",
      "title": "Password"
    }
  },
  "title": "check_account_statusArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "check_account_statusDictOutput"
}

Create, list, or revoke Maginary API keys (up to 10 per account). Auth: pass ``email`` + ``password`` for Basic auth (onboarding), or omit both to use the configured API key (normal operation). Args: action: One of ``create``, ``list``, ``revoke``. name: Key name (required for ``create``). key_prefix: 8-char prefix of the key to revoke (required for ``revoke``). email: Account email (for Basic auth). password: Account password (for Basic auth). Returns: For ``create``: dict with ``raw_key`` (the full key — show once, then use ``configure_api_key`` to activate it), ``key_prefix``, ``name``. For ``list``: dict with ``keys`` array. For ``revoke``: success/error message.

{
  "type": "object",
  "properties": {
    "action": {
      "description": "One of: create, list, revoke.",
      "title": "Action",
      "type": "string"
    },
    "name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Key name (required for create).",
      "title": "Name"
    },
    "key_prefix": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "8-char prefix of key to revoke (required for revoke).",
      "title": "Key Prefix"
    },
    "email": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Account email (for Basic auth).",
      "title": "Email"
    },
    "password": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Account password (for Basic auth).",
      "title": "Password"
    }
  },
  "required": [
    "action"
  ],
  "title": "manage_api_keyArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "manage_api_keyDictOutput"
}

Activate an API key. Local (stdio) servers persist it; hosted does not. Call this after ``manage_api_key(action='create')`` returns a ``raw_key``. On a local server the key is saved to ``~/.config/maginary/api_key`` (chmod 600) and survives restarts. On the hosted server (mcp.maginary.ai) nothing can be stored — auth is per-request: the response will say ``persisted: false`` and the key must be sent as an ``Authorization: Bearer <key>`` header on every request (set it in the MCP client's connection config). Args: api_key: The full API key string returned by ``manage_api_key``. Returns: Confirmation dict.

{
  "type": "object",
  "properties": {
    "api_key": {
      "description": "Full API key string from manage_api_key.",
      "title": "Api Key",
      "type": "string"
    }
  },
  "required": [
    "api_key"
  ],
  "title": "configure_api_keyArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "configure_api_keyDictOutput"
}

List available Maginary products/plans with pricing. No authentication required. Use this to present purchase options to the user. The ``novice_pack`` ($10, 150 credits) is the recommended starting point. Returns: Dict with ``count`` and ``products`` — each product carries ``id``, ``short_name``, ``title``, ``description``, ``price_cents``, ``credits``, ``uploads``, ``is_subscription``. (The backend sends a bare array; it is wrapped here because FastMCP validates tool output against the dict annotation and rejects a top-level list.)

{
  "type": "object",
  "properties": {},
  "title": "get_productsArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "get_productsDictOutput"
}

Create a Stripe checkout session for purchasing a product. Returns a ``checkout_url`` — the user must open it in a browser to complete payment. After payment, credits are provisioned automatically via webhook. **Present the URL exactly as returned, including the ``#fragment`` — do not truncate, reformat, or strip any part of it.** If the agent has a USDC wallet, skip this entirely — just call ``generate`` and the x402 protocol handles payment on-chain. Args: product_id: Product ID from ``get_products``. email: Account email (for Basic auth during onboarding). password: Account password (for Basic auth during onboarding). Returns: Dict with ``checkout_url``. On failure, an ``isError`` result — e.g. ``error: "email_not_verified"`` until the user clicks the verification link, or ``"auth"`` / ``"failed"``.

{
  "type": "object",
  "properties": {
    "product_id": {
      "description": "Product ID from get_products.",
      "title": "Product Id",
      "type": "integer"
    },
    "email": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Account email (for Basic auth during onboarding).",
      "title": "Email"
    },
    "password": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Account password (for Basic auth).",
      "title": "Password"
    }
  },
  "required": [
    "product_id"
  ],
  "title": "checkoutArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "checkoutDictOutput"
}

Check remaining credits and uploads for the authenticated account. Args: email: Account email (for Basic auth). password: Account password (for Basic auth). Returns: Dict with ``credits_remaining`` and ``uploads_remaining``.

{
  "type": "object",
  "properties": {
    "email": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Account email (for Basic auth).",
      "title": "Email"
    },
    "password": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Account password (for Basic auth).",
      "title": "Password"
    }
  },
  "title": "get_balanceArguments"
}

{
  "type": "object",
  "additionalProperties": true,
  "title": "get_balanceDictOutput"
}