Maginary Gens API
The gens API from Maginary — 8 operation(s) for gens.
The gens API from Maginary — 8 operation(s) for gens.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/maginary-ai:maginary-ai-gens-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Maginary Gens API
description: Public API documentation for Maginary — AI image and video generation platform.
version: v1
servers:
- url: https://app.maginary.ai/api
security:
- Basic: []
- Bearer: []
tags:
- name: gens
paths:
/gens/:
parameters: []
get:
operationId: gens_list
description: List generations with rate limiting.
parameters:
- name: limit
in: query
description: Number of results to return per page.
required: false
schema:
type: integer
- name: offset
in: query
description: The initial index from which to return the results.
required: false
schema:
type: integer
responses:
'200':
description: ''
content:
application/json:
schema:
required:
- count
- results
type: object
properties:
count:
type: integer
next:
type:
- string
- 'null'
format: uri
previous:
type:
- string
- 'null'
format: uri
results:
type: array
items:
$ref: '#/components/schemas/GenerationOutput'
tags:
- gens
summary: Gens list
x-summary-source: derived
post:
operationId: gens_create
description: 'Kick off a generation. The prompt is subject text followed by `--flag` modifiers (aspect ratio, model, quality, video, ...) — enumerate them at https://maginary.ai/docs/parameters.json (absolute: it lives on the landing domain, not this API host). Async: the response carries a `uuid`; poll GET /gens/{uuid}/ until a terminal status, then read `image_urls[]`.'
responses:
'201':
description: Generation created (GenerationOutput). When the request was settled via x402 the response also carries a PAYMENT-RESPONSE header (base64 JSON receipt with the on-chain tx). A wallet's first settlement creates its account. Subsequent requests use wallet-signed auth headers (X-Wallet-Address/Signature/Timestamp).
content:
application/json:
schema:
type: object
$ref: '#/components/schemas/GenerationOutput'
'402':
description: 'Payment required (x402 v2). Sent to API-key callers whose credits are short and, when keyless is enabled, to requests with no credentials at all — priced for THIS prompt. Body and the PAYMENT-REQUIRED header (base64 of the body) carry the same PaymentRequired JSON: `accepts[]` (exact USDC amount on Base, payTo, EIP-712 `extra`), `resource`, and `extensions.bazaar`. Sign an EIP-3009 authorization for `accepts[0]` and retry with it in the PAYMENT-SIGNATURE header; an x402 SDK client does this automatically. No account, email or key is needed to pay.'
'417':
description: Insufficient credits (session-authenticated humans only; agents get 402).
tags:
- gens
requestBody:
content:
application/json:
schema:
required:
- prompt
type: object
properties:
prompt:
description: Subject text plus optional --flags.
type: string
example: a fox in autumn foliage --ar 16:9 --flagship --4k
callback_url:
description: Optional webhook POSTed when the generation reaches a terminal state (alternative to polling).
type: string
required: true
summary: Gens create
x-summary-source: derived
/gens/check-slug/:
parameters: []
get:
operationId: gens_check_slug
description: Check if a slug is available for use.
parameters:
- name: limit
in: query
description: Number of results to return per page.
required: false
schema:
type: integer
- name: offset
in: query
description: The initial index from which to return the results.
required: false
schema:
type: integer
- name: slug
in: query
description: Slug to check
required: true
schema:
type: string
responses:
'200':
description: Slug availability result
content:
application/json:
example:
available: true
reason: null
tags:
- gens
summary: Gens check slug
x-summary-source: derived
/gens/current/:
parameters: []
get:
operationId: gens_get_current_generation
description: Get the user's active generations (processing or completed within last 30 minutes).
parameters:
- name: limit
in: query
description: Number of results to return per page.
required: false
schema:
type: integer
- name: offset
in: query
description: The initial index from which to return the results.
required: false
schema:
type: integer
responses:
'200':
description: Active generations
content:
application/json:
example:
gens: []
count: 0
tags:
- gens
summary: Gens get current generation
x-summary-source: derived
/gens/demo-prompts/:
parameters: []
get:
operationId: gens_demo_prompts
description: Get available demo prompts for landing page (no auth required).
parameters:
- name: limit
in: query
description: Number of results to return per page.
required: false
schema:
type: integer
- name: offset
in: query
description: The initial index from which to return the results.
required: false
schema:
type: integer
responses:
'200':
description: List of demo prompts
content:
application/json:
example:
success: true
prompts:
- a magical forest
- cyberpunk city
tags:
- gens
summary: Gens demo prompts
x-summary-source: derived
/gens/discover/:
parameters: []
get:
operationId: gens_discover_list
summary: Public endpoint to list/search discoverable generation slugs
description: 'Each GenerationSlug is a separate discover item (a Gen with 4 slugs = 4 items).
Slot-specific slugs show their respective slot''s image as thumbnail.
GET /api/gens/discover/
Query params:
- search: str (optional) - searches prompt, slug, seo_title, seo_description
- limit: int (default 12, max 50)
- offset: int (default 0)'
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DiscoverableSlug'
tags:
- gens
/gens/{uuid}/:
parameters:
- name: uuid
in: path
required: true
schema:
type: string
get:
operationId: gens_read
description: Retrieve a specific generation by UUID.
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GenerationOutput'
tags:
- gens
summary: Gens read
x-summary-source: derived
/gens/{uuid}/actions/:
parameters:
- name: uuid
in: path
required: true
schema:
type: string
post:
operationId: gens_execute_action
description: 'Execute a follow-up action on a generation: upscale, vary, pan, zoom, edit with an instruction, turn into a video, reroll. The actions available for each image are listed in `processing_result.available_actions`.'
responses:
'201':
description: Action generation created
content:
application/json:
schema:
type: object
$ref: '#/components/schemas/GenerationOutput'
'400':
description: Invalid request (missing action_type, parent not completed, "img2img_basic" without a prompt, "img2img_inpaint" without a --mask or on an image too large for it, etc.)
'402':
description: 'Payment required (x402): API-key callers short on credits get a priced challenge; see POST /gens/.'
'417':
description: Insufficient credits (session-authenticated humans only; agents get 402).
tags:
- gens
requestBody:
content:
application/json:
schema:
required:
- action_type
type: object
properties:
action_type:
description: 'Action to perform: a value from `processing_result.available_actions` (e.g., "upscale_2x", "vary_strong", "pan_left", "zoom_out_1_5x", "img2img_basic", "img2img_inpaint", "img2vid_basic", "reroll")'
type: string
parent_image_index:
description: Index of the parent image to act on (0-3). Required for image-based operations.
type: integer
prompt:
description: 'Prompt for the action. Required for "img2img_basic", where it is the edit instruction (e.g. "make the hat red"), and for "img2img_inpaint", where it is the instruction (may be empty) followed by "--mask <shapes>" (e.g. "make the hat red --mask rect(.2,.1 .8,.4)"). Optional otherwise: if omitted, the parent generation''s prompt is inherited. Not allowed for "reroll".'
type: string
callback_url:
description: Optional HTTPS endpoint. If provided, we POST the GET /gens/{uuid}/ payload (HMAC-SHA256 signed) once this action reaches a terminal state.
type: string
format: uri
required: true
summary: Gens execute action
x-summary-source: derived
/gens/{uuid}/progress/:
parameters:
- name: uuid
in: path
required: true
schema:
type: string
get:
operationId: gens_get_progress
description: Get combined progress for a generation (Django + Engine). Polls during processing.
responses:
'200':
description: Progress information
content:
application/json:
example:
overall_progress: 65
completed: false
tags:
- gens
summary: Gens get progress
x-summary-source: derived
components:
schemas:
DiscoverableSlug:
type: object
properties:
uuid:
title: Uuid
type: string
readOnly: true
minLength: 1
slug:
title: Slug
type: string
readOnly: true
minLength: 1
slot_index:
title: Slot index
description: NULL = full generation (grid view), 0-3 = specific slot (single image view)
type:
- integer
- 'null'
readOnly: true
prompt:
title: Prompt
type: string
readOnly: true
minLength: 1
thumbnail_url:
title: Thumbnail url
type: string
readOnly: true
is_video:
title: Is video
type: boolean
readOnly: true
poster_url:
title: Poster url
type: string
readOnly: true
owner_username:
title: Owner username
type: string
readOnly: true
minLength: 1
seo_title:
title: Seo title
type: string
readOnly: true
seo_description:
title: Seo description
type: string
readOnly: true
created_at:
title: Created at
type: string
format: date-time
readOnly: true
GenerationOutput:
required:
- prompt
type: object
properties:
id:
title: ID
type: integer
readOnly: true
uuid:
title: Uuid
type: string
readOnly: true
minLength: 1
prompt:
title: Prompt
description: Text prompt for image generation
type: string
maxLength: 4000
minLength: 1
action_type:
title: Action type
description: Type of action being performed
type: string
enum:
- txt2img_basic
- txt2img_sref
- img2img_basic
- img2img_sref
- img2img_multiinput
- img2img_inpaint
- vary_strong
- vary_subtle
- upscale_1_5x
- upscale_2x
- zoom_out_1_5x
- zoom_out_2x
- zoom_out_expand_1_5x
- zoom_out_expand_2x
- pan_left
- pan_right
- pan_up
- pan_down
- reroll
- txt2vid_basic
- img2vid_basic
- img2vid_multiinput
parent_image_index:
title: Parent image index
description: parent_gen target image index for this action
type:
- string
- 'null'
readOnly: true
minLength: 1
parent_gen:
title: Parent gen
type:
- integer
- 'null'
parent_gen_uuid:
title: Parent gen uuid
type: string
readOnly: true
parent_expected_output_count:
title: Parent expected output count
type: integer
readOnly: true
created_at:
title: Created at
type: string
format: date-time
readOnly: true
processing_state:
title: Processing state
description: Current state of generation processing
type: string
enum:
- queued
- running
- done
- failed
readOnly: true
processing_started_at:
title: Processing started at
type:
- string
- 'null'
format: date-time
readOnly: true
processing_ended_at:
title: Processing ended at
type:
- string
- 'null'
format: date-time
readOnly: true
processing_result:
title: Processing result
description: 'Full result payload (slots, available_actions, error_message). Shape: {slots: [{index, status, url, charged, ...}], available_actions: {...}, error_message?: str}. `url` inside each slot is the image URL.'
type: string
readOnly: true
processing_progress:
title: Processing progress
type: string
readOnly: true
tokens:
title: Tokens
type: integer
readOnly: true
url:
title: Url
description: API endpoint URL for this generation (NOT an image URL). For image URLs, use `image_urls` (convenience) or `processing_result.slots[].url`.
type: string
readOnly: true
image_urls:
description: 'Flat list of image URLs for successfully-generated slots. Convenience accessor: for most clients this is the only field they need on a done generation.'
type: array
items:
type: string
format: uri
minLength: 1
readOnly: true
webhook:
title: Webhook
description: 'Webhook delivery status. `null` when no callback_url was set. Otherwise an object: {delivered_at, attempts, last_status_code, last_attempt_at, last_error}. `delivered_at` is set ONCE on first 2xx; `last_*` fields refresh on every attempt. Field-by-field timeline of your integration''s last 6 attempts at most (see /docs/webhooks).'
type: string
readOnly: true
is_demo_owned:
title: Is demo owned
type: boolean
readOnly: true
expected_output_count:
title: Expected output count
type: integer
readOnly: true
recipe_metadata:
title: Recipe metadata
type: string
readOnly: true
url_slug:
title: Url slug
type: string
readOnly: true
owner_username:
title: Owner username
type: string
readOnly: true
resolved_slug:
title: Resolved slug
type: string
readOnly: true
resolved_slot_index:
title: Resolved slot index
type: integer
readOnly: true
securitySchemes:
Basic:
type: http
scheme: basic
Bearer:
type: apiKey
name: Authorization
in: header