generate
Submit a prompt to start an image or video generation, returning a record you can poll for results. Optionally provide a webhook callback URL to be notified when the generation finishes.
Instructions
Kick off a generation via POST /api/gens/.
Args:
prompt: The full prompt string, including any ``--flag`` parameters.
E.g. ``"a fox in autumn foliage --ar 16:9 --flagship"``.
Flags go at the END of the prompt. The ones people need most:
``--1`` / ``--2`` / ``--3`` / ``--4`` = how many images (default 4;
``--1`` for a single image, cheapest), ``--ar 16:9`` = aspect ratio,
``--v <model>`` = model. Anything else: call ``get_parameter(name)``
or ``search_parameters`` first — never guess a flag.
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 ``challenge``: either send the human to
``billing_url`` to top up, or pay programmatically via x402 —
``challenge`` is the standard x402 payment-required payload (USDC
on Base); settle it and retry this call.
- ``"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 also returns ``x402_account`` with an API
key — pass it as ``_meta["maginary/api_key"]`` on later calls (or as
the Authorization header of a new connection).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).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | ||
| callback_url | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||