openapi: 3.1.0
info:
  title: Ludo.ai REST 3D Models Animation API
  description: The Ludo.ai REST API provides programmatic access to AI-powered game asset generation capabilities. Developers can generate sprites, icons, UI assets, textures, and backgrounds through image generation endpoints, edit existing images with text instructions, convert 2D images to 3D GLB models with PBR textures, create animated spritesheets from static images, produce sound effects, music tracks, character voices, and generate short videos. All API requests require an API key passed via the Authentication header, and requests consume credits that vary by endpoint type. The API is currently in beta.
  version: 1.0.0
  contact:
    name: Ludo.ai Support
    url: https://ludo.ai
  termsOfService: https://ludo.ai/terms
servers:
- url: https://api.ludo.ai/api
  description: Production Server
security:
- apiKeyAuth: []
tags:
- name: Animation
  description: Create animated spritesheets from static sprites, transfer motion from videos or presets, and list available animation presets.
paths:
  /sprites/animate:
    post:
      operationId: animateSprite
      summary: Ludo.ai Create animated spritesheets from static images
      description: Transform a static sprite image into an animated spritesheet by describing the desired motion. Supports configurable frame counts from 4 to 64, frame sizes, seamless looping, and optional GIF output. Processing takes 30 to 90 seconds. Costs 5 credits per animation.
      tags:
      - Animation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnimateSpriteRequest'
      responses:
        '200':
          description: Successfully created animation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnimationResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /sprites/transfer-motion:
    post:
      operationId: transferMotion
      summary: Ludo.ai Transfer motion onto a static sprite
      description: Transfer motion from a video or animation preset onto a static sprite, producing an animated spritesheet. Provide either a video URL or a preset ID with perspective and direction. Costs 5 credits per transfer.
      tags:
      - Animation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferMotionRequest'
      responses:
        '200':
          description: Successfully transferred motion
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnimationResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /animation-presets:
    get:
      operationId: listAnimationPresets
      summary: Ludo.ai List available animation presets
      description: Retrieve the catalog of available animation presets for use with motion transfer. Returns preset animations with their categories, descriptions, and preview URLs, along with available perspectives and directions. Free endpoint that does not consume credits.
      tags:
      - Animation
      responses:
        '200':
          description: Successfully retrieved animation presets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnimationPresetsResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    AnimateSpriteRequest:
      type: object
      required:
      - initial_image
      - motion_prompt
      properties:
        initial_image:
          type: string
          description: URL or base64-encoded image of the starting frame.
        motion_prompt:
          type: string
          description: Description of the animation motion such as walking cycle, idle breathing, or attack slash.
        image_type:
          type: string
          description: The type of sprite being animated.
          enum:
          - sprite
          - sprite-vfx
          - ui_asset
        frames:
          type: integer
          description: Number of frames in the output spritesheet.
          enum:
          - 4
          - 9
          - 16
          - 25
          - 36
          - 49
          - 64
          default: 36
        frame_size:
          type: integer
          description: Size of each frame in pixels. Use 0 for maximum resolution.
          enum:
          - 64
          - 128
          - 256
          - 0
          default: 256
        loop:
          type: boolean
          description: Whether to create a seamless looping animation.
          default: true
        model:
          type: string
          description: Animation model to use. The new model produces higher quality results.
          enum:
          - standard
          - new
          default: standard
        duration:
          type: number
          description: Animation duration in seconds. Standard model supports 1.2 to 3 seconds. New model supports up to 4 seconds.
        final_image:
          type: string
          description: URL or base64-encoded ending frame for interpolation between start and end poses.
        gif:
          type: boolean
          description: Whether to also generate an animated GIF.
          default: false
        individual_frames:
          type: boolean
          description: Whether to extract and return individual frame images.
          default: false
        spritesheet_with_background:
          type: boolean
          description: Whether to also return the spritesheet with background intact before background removal.
          default: false
        request_id:
          type: string
          description: Client-provided ID to retrieve results later via the results endpoint.
    AnimationPresetsResponse:
      type: object
      properties:
        animations:
          type: array
          description: Array of available animation presets.
          items:
            $ref: '#/components/schemas/AnimationPreset'
        perspectives:
          type: array
          description: Array of available perspectives. All animations support all perspectives.
          items:
            type: object
            properties:
              id:
                type: string
                description: Perspective identifier.
              name:
                type: string
                description: Human-readable perspective name.
              description:
                type: string
                description: Description of the perspective.
        directions:
          type: array
          description: Available directions for animation presets. All animations support all directions.
          items:
            type: string
            enum:
            - N
            - NE
            - E
            - SE
            - S
            - SW
            - W
            - NW
    TransferMotionRequest:
      type: object
      required:
      - image
      properties:
        image:
          type: string
          description: URL or base64-encoded sprite image to apply motion to.
        video:
          type: string
          description: URL of the video to use as motion source. Videos up to 4 seconds produce better results. Either video or preset_id with perspective and direction must be provided.
        preset_id:
          type: string
          description: ID of an animation preset to use instead of a video URL. When using a preset, perspective and direction are required.
        direction:
          type: string
          description: Direction for the animation preset. Required when using a preset.
          enum:
          - N
          - NE
          - E
          - SE
          - S
          - SW
          - W
          - NW
        perspective:
          type: string
          description: Perspective ID to use with the animation preset. Required when using a preset.
        frames:
          type: integer
          description: Number of frames in the output spritesheet.
        frame_size:
          type: integer
          description: Size of each frame in pixels.
        loop:
          type: boolean
          description: Whether to trim the animation for seamless looping.
        crop:
          type: boolean
          description: Whether to crop frames to fit content.
        margin_ratio:
          type: number
          description: Padding around the sprite as a ratio from 0.0 to 1.0.
          minimum: 0.0
          maximum: 1.0
        margin_ratio_mode:
          type: string
          description: Mode for margin ratio application.
          enum:
          - manual
          - none
          default: manual
        gif:
          type: boolean
          description: Whether to also generate an animated GIF.
          default: false
        individual_frames:
          type: boolean
          description: Whether to extract and return individual frame images.
          default: false
        spritesheet_with_background:
          type: boolean
          description: Whether to also return the spritesheet with background intact before background removal.
          default: false
        request_id:
          type: string
          description: Client-provided ID to retrieve results later via the results endpoint.
    AnimationResponse:
      type: object
      properties:
        spritesheet_url:
          type: string
          format: uri
          description: URL of the generated spritesheet image. Expires after 7 days.
        video_url:
          type: string
          format: uri
          description: URL of the animation as a video file. Expires after 7 days.
        gif_url:
          type: string
          format: uri
          description: URL of the animated GIF if gif was set to true. Expires after 7 days.
        individual_frame_urls:
          type: array
          description: Array of individual frame image URLs if individual_frames was set to true.
          items:
            type: string
            format: uri
        spritesheet_with_background_url:
          type: string
          format: uri
          description: URL of the spritesheet with background intact if spritesheet_with_background was set to true.
        individual_frame_with_background_urls:
          type: array
          description: Array of individual frame URLs with background intact.
          items:
            type: string
            format: uri
        num_frames:
          type: integer
          description: Total number of frames in the spritesheet.
        num_cols:
          type: integer
          description: Number of columns in the spritesheet grid.
        num_rows:
          type: integer
          description: Number of rows in the spritesheet grid.
        request_id:
          type: string
          description: The request ID if one was provided.
    AnimationPreset:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the animation preset.
        name:
          type: string
          description: Human-readable name of the animation preset.
        category:
          type: string
          description: Category grouping for the preset.
        description:
          type: string
          description: Description of the animation motion.
        duration:
          type: number
          description: Duration of the preset animation in seconds.
        preview_url:
          type: string
          format: uri
          description: URL to preview the animation preset.
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message describing what went wrong.
        code:
          type: string
          description: Machine-readable error code.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authentication
      description: 'API key authentication. Pass your API key in the Authentication header with the format: ApiKey YOUR_API_KEY'
externalDocs:
  description: Ludo.ai API Documentation
  url: https://api.ludo.ai/api-documentation