Leonardo.AI
Leonardo.AI Variation and Upscale API

Apply post-generation transformations to existing images including unzoom (outpainting), creative upscale, background removal, and the Universal Upscaler. Retrieve variation job status by ID.
Leonardo.AI Variation and Upscale API is one of 14 APIs that Leonardo.AI publishes on the APIs.io network, described by a machine-readable OpenAPI specification.
This API exposes 1 machine-runnable capability that can be deployed as REST, MCP, or Agent Skill surfaces via Naftiko.
Tagged areas include AI, Upscale, Variation, and Image Editing. The published artifact set on APIs.io includes API documentation, an OpenAPI specification, and 1 Naftiko capability spec.
Documentation GitHub OpenAPI
OpenAPI Specification

{
  "openapi": "3.0.0",
  "info": {
    "title": "Leonardo.AI Variation & Upscale API",
    "description": "Apply variations to existing images including unzoom (outpainting), upscale, background removal, and Universal Upscaler. Retrieve variation job status.",
    "version": "v1.0.0",
    "contact": {
      "name": "Leonardo.AI Support",
      "url": "https://docs.leonardo.ai/docs/need-more-support"
    },
    "license": {
      "name": "Leonardo.AI Terms of Service",
      "url": "https://leonardo.ai/terms-of-service/"
    }
  },
  "servers": [
    {
      "url": "https://cloud.leonardo.ai/api/rest/v1",
      "description": "Leonardo.AI Production API"
    }
  ],
  "tags": [
    {
      "name": "Variation"
    }
  ],
  "paths": {
    "/variations/unzoom": {
      "post": {
        "tags": [
          "Variation"
        ],
        "summary": "Create unzoom",
        "description": "This endpoint will create an unzoom variation for the provided image ID",
        "operationId": "createVariationUnzoom",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "id": {
                    "nullable": false,
                    "title": "String",
                    "type": "string"
                  },
                  "isVariation": {
                    "nullable": true,
                    "title": "Boolean",
                    "type": "boolean"
                  }
                },
                "type": "object"
              }
            }
          },
          "description": "Query parameters can also be provided in the request body as a JSON object",
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "sdUnzoomJob": {
                      "nullable": true,
                      "properties": {
                        "id": {
                          "nullable": false,
                          "title": "String",
                          "type": "string"
                        },
                        "apiCreditCost": {
                          "nullable": true,
                          "type": "integer",
                          "description": "API Credits Cost for Unzoom Variation. Available for Production API Users. Note: it will be deprecated. Please use the cost instead.",
                          "deprecated": true
                        },
                        "cost": {
                          "$ref": "#/components/schemas/cost"
                        }
                      },
                      "title": "SDUnzoomOutput",
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "sdUnzoomJob": {
                    "id": "c2d3e4f5-g6h7-8901-ijkl-mn2345678901",
                    "apiCreditCost": null,
                    "cost": {
                      "amount": "0.0147",
                      "unit": "DOLLARS"
                    }
                  }
                }
              }
            },
            "description": "Responses for POST /api/rest/v1/variations/unzoom"
          }
        }
      }
    },
    "/variations/upscale": {
      "post": {
        "tags": [
          "Variation"
        ],
        "summary": "Create upscale",
        "description": "This endpoint will create an upscale for the provided image ID",
        "operationId": "createVariationUpscale",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "id": {
                    "nullable": false,
                    "title": "String",
                    "type": "string"
                  }
                },
                "required": [
                  "id"
                ],
                "type": "object"
              }
            }
          },
          "description": "Query parameters are provided in the request body as a JSON object",
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sdUpscaleJob": {
                      "nullable": true,
                      "properties": {
                        "id": {
                          "nullable": false,
                          "title": "String",
                          "type": "string"
                        },
                        "apiCreditCost": {
                          "nullable": true,
                          "type": "integer",
                          "description": "API Credits Cost for Upscale Variation. Available for Production API Users. Note: it will be deprecated. Please use the cost instead.",
                          "deprecated": true
                        },
                        "cost": {
                          "$ref": "#/components/schemas/cost"
                        }
                      },
                      "title": "SDUpscaleJobOutput",
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "sdUpscalerjob": {
                    "id": "d3e4f5g6-h7i8-9012-jklm-no3456789012",
                    "apiCreditCost": null,
                    "cost": {
                      "amount": "0.0147",
                      "unit": "DOLLARS"
                    }
                  }
                }
              }
            },
            "description": "Responses for POST /variations/upscale"
          }
        }
      }
    },
    "/variations/nobg": {
      "post": {
        "tags": [
          "Variation"
        ],
        "summary": "Create no background",
        "description": "This endpoint will create a no background variation of the provided image ID",
        "operationId": "createVariationNoBG",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "id": {
                    "nullable": false,
                    "title": "String",
                    "type": "string"
                  },
                  "isVariation": {
                    "nullable": false,
                    "type": "boolean",
                    "title": "Boolean"
                  }
                },
                "required": [
                  "id"
                ],
                "type": "object"
              }
            }
          },
          "description": "Query parameters are provided in the request body as a JSON object",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sdNobgJob": {
                      "properties": {
                        "id": {
                          "$ref": "#/components/schemas/uuid"
                        },
                        "apiCreditCost": {
                          "nullable": true,
                          "type": "integer",
                          "description": "API Credits Cost for No Background Variation. Available for Production API Users. Note: it will be deprecated. Please use the cost instead.",
                          "deprecated": true
                        },
                        "cost": {
                          "$ref": "#/components/schemas/cost"
                        }
                      },
                      "title": "SDUpscaleJobOutput",
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "sdNobgJob": {
                    "id": "f5g6h7i8-j9k0-l1m2-nopq-rs4567890123",
                    "apiCreditCost": null,
                    "cost": {
                      "amount": "0.0147",
                      "unit": "DOLLARS"
                    }
                  }
                }
              }
            },
            "description": "Responses for POST /variations/nobg"
          }
        }
      }
    },
    "/variations/universal-upscaler": {
      "post": {
        "tags": [
          "Variation"
        ],
        "summary": "Create using Universal Upscaler",
        "description": "This endpoint will create a high resolution image using Universal Upscaler",
        "operationId": "CreateUniversalUpscalerJob",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "creativityStrength": {
                    "nullable": true,
                    "title": "Int",
                    "type": "integer",
                    "default": 5,
                    "description": "The creativity strength of the universal upscaler. Must be between 1 and 10."
                  },
                  "detailContrast": {
                    "nullable": true,
                    "title": "Int",
                    "type": "integer",
                    "description": "The detail contrast of the universal upscaler. Must be between 1 and 10. Can only be used with ultraUpscaleStyle."
                  },
                  "generatedImageId": {
                    "nullable": true,
                    "title": "String",
                    "type": "string",
                    "description": "The ID of the generated image."
                  },
                  "initImageId": {
                    "nullable": true,
                    "title": "String",
                    "type": "string",
                    "description": "The ID of the init image uploaded."
                  },
                  "prompt": {
                    "nullable": true,
                    "title": "String",
                    "type": "string",
                    "description": "The prompt for the universal upscaler."
                  },
                  "similarity": {
                    "nullable": true,
                    "title": "Int",
                    "type": "integer",
                    "description": "The similarity of the universal upscaler. Must be between 1 and 10. Can only be used with ultraUpscaleStyle."
                  },
                  "ultraUpscaleStyle": {
                    "$ref": "#/components/schemas/universal_upscaler_ultra_style"
                  },
                  "upscaleMultiplier": {
                    "nullable": true,
                    "title": "Float",
                    "type": "number",
                    "default": 1.5,
                    "description": "The upscale multiplier of the universal upscaler. Must be between 1.0 and 2.0."
                  },
                  "upscalerStyle": {
                    "$ref": "#/components/schemas/universal_upscaler_style"
                  },
                  "variationId": {
                    "nullable": true,
                    "title": "String",
                    "type": "string",
                    "description": "The ID of the variation image."
                  }
                },
                "type": "object"
              }
            }
          },
          "description": "Query parameters are provided in the request body as a JSON object",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "universalUpscaler": {
                      "properties": {
                        "id": {
                          "$ref": "#/components/schemas/uuid"
                        },
                        "apiCreditCost": {
                          "nullable": true,
                          "type": "integer",
                          "description": "API Credits Cost for Universal Upscaler Variation. Available for Production API Users. Note: it will be deprecated. Please use the cost instead.",
                          "deprecated": true
                        },
                        "cost": {
                          "$ref": "#/components/schemas/cost"
                        }
                      },
                      "title": "UniversalUpscalerOutput",
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "universalUpscaler": {
                    "id": "g6h7i8j9-k0l1-m2n3-opqr-st5678901234",
                    "apiCreditCost": null,
                    "cost": {
                      "amount": "0.0147",
                      "unit": "DOLLARS"
                    }
                  }
                }
              }
            },
            "description": "Responses for POST /variations/universal-upscaler"
          }
        }
      }
    },
    "/variations/{id}": {
      "get": {
        "tags": [
          "Variation"
        ],
        "summary": "Get variation by ID",
        "description": "This endpoint will get the variation by ID",
        "operationId": "getVariationById",
        "parameters": [
          {
            "required": true,
            "description": "\"id\" is required",
            "in": "path",
            "name": "id",
            "schema": {
              "pattern": "[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89aAbB][a-f0-9]{3}-[a-f0-9]{12}",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "generated_image_variation_generic": {
                      "items": {
                        "description": "columns and relationships of \"generated_image_variation_generic\"",
                        "nullable": false,
                        "properties": {
                          "createdAt": {
                            "$ref": "#/components/schemas/timestamp"
                          },
                          "id": {
                            "$ref": "#/components/schemas/uuid"
                          },
                          "status": {
                            "$ref": "#/components/schemas/job_status"
                          },
                          "transformType": {
                            "$ref": "#/components/schemas/VARIATION_TYPE"
                          },
                          "url": {
                            "nullable": true,
                            "title": "String",
                            "type": "string"
                          }
                        },
                        "title": "generated_image_variation_generic",
                        "type": "object"
                      },
                      "nullable": false,
                      "type": "array"
                    }
                  }
                }
              }
            },
            "description": "Responses for GET /variations/{id}"
          }
        }
      }
    },
    "/motion-variations/{id}": {
      "get": {
        "tags": [
          "Variation"
        ],
        "summary": "Get motion variation by ID",
        "description": "This endpoint will get the motion variation by ID",
        "operationId": "getMotionVariationById",
        "parameters": [
          {
            "required": true,
            "description": "\"id\" is required",
            "in": "path",
            "name": "id",
            "schema": {
              "pattern": "[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89aAbB][a-f0-9]{3}-[a-f0-9]{12}",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "generated_image_variation_motion": {
                      "items": {
                        "description": "columns and relationships of \"generated_image_variation_motion\"",
                        "nullable": false,
                        "properties": {
                          "createdAt": {
                            "$ref": "#/components/schemas/timestamp"
                          },
                          "id": {
                            "$ref": "#/components/schemas/uuid"
                          },
                          "status": {
                            "$ref": "#/components/schemas/job_status"
                          },
                          "motionTransformType": {
                            "$ref": "#/components/schemas/MOTION_VARIATION_TYPE"
                          },
                          "resolution": {
                            "$ref": "#/components/schemas/MOTION_RESOLUTION"
                          },
                          "url": {
                            "nullable": true,
                            "title": "String",
                            "type": "string"
                          }
                        },
                        "title": "generated_image_variation_motion",
                        "type": "object"
                      },
                      "nullable": false,
                      "type": "array"
                    }
                  }
                }
              }
            },
            "description": "Responses for GET /motion-variations/{id}"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "cost": {
        "nullable": true,
        "type": "object",
        "title": "Cost",
        "description": "The cost of the operation.",
        "properties": {
          "amount": {
            "type": "string",
            "description": "The amount of the cost."
          },
          "unit": {
            "type": "string",
            "enum": [
              "CREDITS",
              "DOLLARS"
            ],
            "description": "The unit of the cost. Can be CREDITS or DOLLARS. Note: DOLLARS unit only supports PAYG plan."
          }
        }
      },
      "Cursor": {
        "type": "string",
        "title": "Cursor",
        "description": "An opaque cursor used for pagination"
      },
      "Blueprint": {
        "type": "object",
        "title": "Blueprint",
        "description": "A Blueprint object",
        "properties": {
          "akUUID": {
            "type": "string",
            "description": "Unique identifier for the Blueprint",
            "example": "c846413e-92ba-4302-84f8-47c667d4761f"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Creation timestamp",
            "example": "2025-10-29T21:31:47.999Z"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Last update timestamp",
            "example": "2025-12-19T02:34:44.740Z"
          },
          "name": {
            "type": "string",
            "description": "Name of the Blueprint",
            "example": "Golden Hour Relight"
          },
          "description": {
            "type": "string",
            "description": "Description of the Blueprint",
            "example": "Relight an image with warm, golden tones of late afternoon sunlight for a soft and radiant glow."
          },
          "thumbnails": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Thumbnail type name (e.g., thumbnailUrl, videoUrl, thumbnailUrlBanner, thumbnailUrlLandscape, thumbnailUrlExtremePortrait)",
                  "example": "thumbnailUrl"
                },
                "url": {
                  "type": "string",
                  "description": "URL of the thumbnail",
                  "example": "https://cdn.leonardo.ai/blueprint_assets/official/384ab5c8-55d8-47a1-be22-6a274913c324/thumbnails/goldenhour.jpg"
                }
              }
            }
          },
          "teamId": {
            "type": "string",
            "nullable": true,
            "description": "Team ID if Blueprint belongs to a team",
            "example": null
          },
          "official": {
            "type": "boolean",
            "description": "Whether this is an official Blueprint",
            "example": true
          }
        }
      },
      "BlueprintVersion": {
        "type": "object",
        "title": "BlueprintVersion",
        "description": "A Blueprint Version object",
        "properties": {
          "edges": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "cursor": {
                  "type": "string",
                  "example": "eyJjcmVhdGVkQXQiOiIyMDI1LTExLTI3VDA1OjEzOjIxLjg5NloiLCJha1VVSUQiOiI5NTZlOTU2NC0xOWY3LTQ5NjgtYjU2ZC0wNWMyYzU2NzcyNmYifQ=="
                },
                "node": {
                  "type": "object",
                  "properties": {
                    "akUUID": {
                      "type": "string",
                      "format": "uuid",
                      "example": "956e9564-19f7-4968-b56d-05c2c567726f"
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time",
                      "example": "2025-11-27T05:13:21.896Z"
                    },
                    "updatedAt": {
                      "type": "string",
                      "format": "date-time",
                      "example": "2025-11-27T05:13:21.896Z"
                    },
                    "cost": {
                      "type": "integer",
                      "example": 160
                    },
                    "uiMetadata": {
                      "type": "object",
                      "properties": {
                        "inputs": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "outputs": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      },
                      "additionalProperties": false
                    },
                    "uiMetadataSchemaVersion": {
                      "type": "string",
                      "example": "21"
                    },
                    "models": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "executability": {
                      "type": "object",
                      "properties": {
                        "isExecutable": {
                          "type": "boolean",
                          "example": true
                        },
                        "reasons": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                              "models": {
                                "type": "string",
                                "example": "gemini-2.5-flash-image"
                              }
                            }
                          }
                        }
                      },
                      "additionalProperties": false
                    }
                  },
                  "additionalProperties": false
                }
              },
              "additionalProperties": false
            }
          },
          "totalCount": {
            "type": "integer",
            "example": 2
          },
          "pageInfo": {
            "type": "object",
            "properties": {
              "hasNextPage": {
                "type": "boolean",
                "example": false
              },
              "hasPreviousPage": {
                "type": "boolean",
                "example": false
              },
              "startCursor": {
                "type": "string",
                "example": "eyJjcmVhdGVkQXQiOiIyMDI1LTExLTI3VDA1OjEzOjIxLjg5NloiLCJha1VVSUQiOiI5NTZlOTU2NC0xOWY3LTQ5NjgtYjU2ZC0wNWMyYzU2NzcyNmYifQ=="
              },
              "endCursor": {
                "type": "string",
                "example": "eyJjcmVhdGVkQXQiOiIyMDI1LTExLTI3VDA1OjEzOjIxLjg5NloiLCJha1VVSUQiOiI5NTZlOTU2NC0xOWY3LTQ5NjgtYjU2ZC0wNWMyYzU2NzcyNmYifQ=="
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "NodeInput": {
        "type": "object",
        "title": "NodeInput",
        "description": "A node input object for customizing a Blueprint Execution",
        "required": [
          "nodeId",
          "settingName",
          "value"
        ],
        "properties": {
          "nodeId": {
            "type": "string",
            "format": "uuid",
            "description": "The ID of the node in the Blueprint",
            "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          },
          "settingName": {
            "type": "string",
            "enum": [
              "text",
              "imageUrl",
              "textVariables"
            ],
            "description": "The type of setting to replace:\n- `text`: Direct text replacement (value is a string)\n- `imageUrl`: Image URL input (value is a URL string)\n- `textVariables`: Text with placeholder variables (value is an array of TextVariable)",
            "example": "text"
          },
          "value": {
            "oneOf": [
              {
                "type": "string",
                "description": "String value. Use for settingName='text' (direct text) or settingName='imageUrl' (image URL)"
              },
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/TextVariable"
                },
                "description": "Array of TextVariable objects. Use only for settingName='textVariables' to replace {{placeholders}} in the Blueprint"
              }
            ],
            "description": "The replacement value. Type depends on settingName:\n- `text`: string (the full text)\n- `imageUrl`: string (the image URL)\n- `textVariables`: array of TextVariable objects",
            "example": "A futuristic cityscape at sunset"
          }
        }
      },
      "TextVariable": {
        "type": "object",
        "title": "TextVariable",
        "description": "A text variable for replacing placeholders in Blueprint templates",
        "required": [
          "name",
          "value"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "The name of the placeholder variable (without curly braces)",
            "example": "characterName"
          },
          "value": {
            "type": "string",
            "description": "The value to replace the placeholder with",
            "example": "Luna"
          }
        }
      },
      "ApiError": {
        "type": "object",
        "title": "ApiError",
        "description": "API error response structure",
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message"
          },
          "path": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Path to the field that caused the error"
          },
          "locations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "column": {
                  "type": "integer"
                },
                "line": {
                  "type": "integer"
                }
              }
            },
            "description": "Location information for the error"
          },
          "extensions": {
            "type": "object",
            "description": "Additional error details and context"
          }
        }
      },
      "apiCreditCost": {
        "nullable": true,
        "title": "Int",
        "type": "integer",
        "description": "API credits cost, available for Production API users. Note: it will be deprecated. Please use the cost instead.",
        "deprecated": true
      },
      "isVariation": {
        "nullable": true,
        "title": "Boolean",
        "type": "boolean",
        "description": "If it is a variation image."
      },
      "isInitImage": {
        "nullable": true,
        "title": "Boolean",
        "type": "boolean",
        "description": "If it is an init image uploaded by the user. This image is uploaded from endpoint: Upload init image."
      },
      "imageToVideo": {
        "nullable": true,
        "title": "Boolean",
        "type": "boolean",
        "description": "If it is an image to video generation."
      },
      "sd_versions": {
        "type": "string",
        "nullable": false,
        "title": "sd_versions",
        "enum": [
          "v1_5",
          "v2",
          "v3",
          "SDXL_0_8",
          "SDXL_0_9",
          "SDXL_1_0",
          "SDXL_LIGHTNING",
          "PHOENIX",
          "FLUX",
          "FLUX_DEV",
          "KINO_2_0"
        ],
        "description": "The base version of stable diffusion to use if not using a custom model. v1_5 is 1.5, v2 is 2.1, if not specified it will default to v1_5. Also includes SDXL and SDXL Lightning models"
      },
      "lora": {
        "type": "object",
        "properties": {
          "akUUID": {
            "nullable": true,
            "type": "string",
            "description": "Unique identifier for the element. Elements can be found from the List Elements endpoint."
          },
          "creatorName": {
            "nullable": true,
            "type": "string",
            "description": "Name of the creator of the element"
          },
          "name": {
            "nullable": true,
            "type": "string",
            "description": "Name of the element"
          },
          "description": {
            "nullable": true,
            "type": "string",
            "description": "Description for the element"
          },
          "urlImage": {
            "nullable": true,
            "type": "string",
            "description": "URL of the element image"
          },
          "baseModel": {
            "nullable": true,
            "type": "string",
            "description": "Base model version for the element"
          },
          "weightDefault": {
            "nullable": true,
            "type": "integer",
            "description": "Default weight for the element"
          },
          "weightMin": {
            "nullable": true,
            "type": "integer",
            "description": "Minimum weight for the element"
          },
          "weightMax": {
            "nullable": true,
            "type": "integer",
            "description": "Maximum weight for the element"
          },
          "__typename": {
            "type": "string",
            "description": "Type name for introspection purposes"
          }
        }
      },
      "motion": {
        "nullable": true,
        "title": "Boolean",
        "type": "boolean",
        "description": "If generation is of motion type."
      },
      "motionModel": {
        "nullable": true,
        "title": "String",
        "type": "string",
        "description": "The name of the motion model."
      },
      "motionMP4URL": {
        "nullable": true,
        "title": "String",
        "type": "string",
        "description": "The URL of the motion MP4

# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/leonardo-ai/refs/heads/main/openapi/leonardo-ai-variation-openapi.json
Leonardo.AI Variation and Upscale API

Documentation

Specifications

Other Resources

OpenAPI Specification
