Maginary Gens API

The gens API from Maginary — 8 operation(s) for gens.

GitHub OpenAPI

Operations 9

GET /gens/ Gens list #
POST /gens/ Gens create #
GET /gens/check-slug/ Gens check slug #
GET /gens/current/ Gens get current generation #
GET /gens/demo-prompts/ Gens demo prompts #
GET /gens/discover/ Public endpoint to list/search discoverable generation slugs #
GET /gens/{uuid}/ Gens read #
POST /gens/{uuid}/actions/ Gens execute action #
GET /gens/{uuid}/progress/ Gens get progress #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/maginary-ai:maginary-ai-gens-api"
All apis
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.

Get an API 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 Specification

maginary-ai-gens-api-openapi.yml Raw ↑
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