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"]``.