Leonardo.AI
Leonardo.AI Elements API

Create and manage Custom Elements — LoRA-style style adapters trainable on user datasets and reusable across image generations to enforce visual identity, style, or character consistency.
Leonardo.AI Elements 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, Elements, LoRA, and Fine Tuning. 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 Elements API",
    "description": "Create and manage Custom Elements \u2014 LoRA-style style adapters trainable on user datasets and reusable across image generations.",
    "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": "Elements"
    }
  ],
  "paths": {
    "/elements/{id}": {
      "get": {
        "tags": [
          "Elements"
        ],
        "summary": "Get a Single Custom Element by ID",
        "description": "This endpoint gets the specific custom element.",
        "operationId": "getElementById",
        "parameters": [
          {
            "required": true,
            "description": "The ID of the custom element to return.",
            "in": "path",
            "name": "id",
            "schema": {
              "pattern": "[0-9]{*}",
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "user_loras_by_pk": {
                      "description": "columns and relationships of \"user_loras\".",
                      "nullable": true,
                      "properties": {
                        "createdAt": {
                          "$ref": "#/components/schemas/timestamp"
                        },
                        "description": {
                          "nullable": false,
                          "title": "String",
                          "type": "string"
                        },
                        "id": {
                          "nullable": false,
                          "title": "Int",
                          "type": "integer"
                        },
                        "instancePrompt": {
                          "nullable": true,
                          "title": "String",
                          "type": "string"
                        },
                        "resolution": {
                          "nullable": false,
                          "title": "Int",
                          "type": "integer"
                        },
                        "learningRate": {
                          "nullable": false,
                          "title": "Float",
                          "type": "number"
                        },
                        "trainingEpoch": {
                          "nullable": false,
                          "title": "Int",
                          "type": "integer"
                        },
                        "name": {
                          "nullable": false,
                          "title": "String",
                          "type": "string"
                        },
                        "trainTextEncoder": {
                          "nullable": false,
                          "title": "Boolean",
                          "type": "boolean"
                        },
                        "baseModel": {
                          "nullable": false,
                          "title": "String",
                          "type": "string"
                        },
                        "status": {
                          "$ref": "#/components/schemas/job_status"
                        },
                        "focus": {
                          "nullable": false,
                          "title": "String",
                          "type": "string"
                        },
                        "updatedAt": {
                          "$ref": "#/components/schemas/timestamp"
                        }
                      },
                      "title": "user_loras",
                      "type": "object"
                    }
                  }
                }
              }
            },
            "description": "Responses for GET /elements/{id}."
          }
        }
      },
      "delete": {
        "tags": [
          "Elements"
        ],
        "summary": "Delete a Single Custom Element by ID",
        "description": "This endpoint will delete a specific custom model.",
        "operationId": "deleteElementById",
        "parameters": [
          {
            "required": true,
            "description": "The ID of the element to delete.",
            "in": "path",
            "name": "id",
            "schema": {
              "pattern": "[0-9]{*}",
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "delete_user_loras_by_pk": {
                      "description": "columns and relationships of \"user_loras\".",
                      "nullable": true,
                      "properties": {
                        "id": {
                          "nullable": false,
                          "title": "Int",
                          "type": "integer"
                        }
                      },
                      "title": "user_loras",
                      "type": "object"
                    }
                  }
                }
              }
            },
            "description": "Responses for DELETE /models/{id}"
          }
        }
      }
    },
    "/elements/user/{userId}": {
      "get": {
        "tags": [
          "Elements"
        ],
        "summary": "Get a list of Custom Elements by User ID",
        "description": "This endpoint gets the list of custom elements belongs to the user.",
        "operationId": "getCustomElementsByUserId",
        "parameters": [
          {
            "required": true,
            "description": "The ID of the user to return.",
            "in": "path",
            "name": "userId",
            "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": {
                  "properties": {
                    "user_loras": {
                      "items": {
                        "description": "columns and relationships of \"user_loras\".",
                        "nullable": true,
                        "title": "user_loras",
                        "type": "object",
                        "properties": {
                          "createdAt": {
                            "$ref": "#/components/schemas/timestamp"
                          },
                          "description": {
                            "nullable": false,
                            "title": "String",
                            "type": "string"
                          },
                          "id": {
                            "nullable": false,
                            "title": "Int",
                            "type": "integer"
                          },
                          "instancePrompt": {
                            "nullable": true,
                            "title": "String",
                            "type": "string"
                          },
                          "resolution": {
                            "nullable": false,
                            "title": "Int",
                            "type": "integer"
                          },
                          "learningRate": {
                            "nullable": false,
                            "title": "Float",
                            "type": "number"
                          },
                          "trainingEpoch": {
                            "nullable": false,
                            "title": "Int",
                            "type": "integer"
                          },
                          "name": {
                            "nullable": false,
                            "title": "String",
                            "type": "string"
                          },
                          "trainTextEncoder": {
                            "nullable": false,
                            "title": "Boolean",
                            "type": "boolean"
                          },
                          "baseModel": {
                            "nullable": false,
                            "title": "String",
                            "type": "string"
                          },
                          "status": {
                            "$ref": "#/components/schemas/job_status"
                          },
                          "focus": {
                            "nullable": false,
                            "title": "String",
                            "type": "string"
                          },
                          "updatedAt": {
                            "$ref": "#/components/schemas/timestamp"
                          }
                        }
                      },
                      "nullable": true,
                      "type": "array"
                    }
                  }
                }
              }
            },
            "description": "Responses for GET /elements/user/{userId}."
          }
        }
      }
    },
    "/elements": {
      "post": {
        "tags": [
          "Elements"
        ],
        "summary": "Train a Custom Element",
        "description": "This endpoint will train a new custom element.",
        "operationId": "createElement",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "name": {
                    "default": "placeholder",
                    "nullable": false,
                    "title": "String",
                    "type": "string",
                    "description": "The name of the element."
                  },
                  "description": {
                    "default": "",
                    "nullable": true,
                    "title": "String",
                    "type": "string",
                    "description": "The description of the element."
                  },
                  "datasetId": {
                    "default": "",
                    "nullable": false,
                    "title": "String",
                    "type": "string",
                    "description": "The ID of the dataset to train the element on."
                  },
                  "instance_prompt": {
                    "default": "",
                    "nullable": true,
                    "title": "String",
                    "type": "string",
                    "description": "Use a word that is closely related to what you're training that isn't too common. For example, instead of 'dog,' try something unique like 'jackthedog' or 'magicdonut'. Required for all non-FLUX_DEV models and FLUX_DEV Character model training."
                  },
                  "lora_focus": {
                    "nullable": false,
                    "title": "String",
                    "type": "string",
                    "description": "The category determines how the element will be trained. Options are 'General' | 'Character' | 'Style' | 'Object'. FLUX_DEV doesn't support General category."
                  },
                  "train_text_encoder": {
                    "default": true,
                    "nullable": false,
                    "title": "Boolean",
                    "type": "boolean",
                    "description": "Whether or not encode the train text."
                  },
                  "resolution": {
                    "default": 1024,
                    "nullable": true,
                    "title": "Int",
                    "type": "integer",
                    "description": "The resolution for training. Must be 1024."
                  },
                  "sd_version": {
                    "nullable": false,
                    "default": "FLUX_DEV",
                    "title": "sd_versions",
                    "enum": [
                      "SDXL_0_9",
                      "SDXL_1_0",
                      "LEONARDO_DIFFUSION_XL",
                      "LEONARDO_LIGHTNING_XL",
                      "VISION_XL",
                      "KINO_XL",
                      "ALBEDO_XL",
                      "FLUX_DEV"
                    ],
                    "description": "The base version to use if not using a custom model."
                  },
                  "num_train_epochs": {
                    "nullable": false,
                    "title": "Int",
                    "type": "integer",
                    "description": "The number of times the entire training dataset is passed through the element.<br><br><table><tr><th>Model Type</th><th>Lora Focus</th><th>Min</th><th>Max</th><th>Default</th></tr><tr><td>Default</td><td>General | Style | Character | Object</td><td>1</td><td>250</td><td>100</td></tr><tr><td rowspan='3'>FLUX_DEV</td><td>Style</td><td>30</td><td>120</td><td>60</td></tr><tr><td>Object</td><td>120</td><td>220</td><td>140</td></tr><tr><td>Character</td><td>100</td><td>200</td><td>135</td></tr><tr><td>General</td><td colspan='3'>NA</td></tr></table>"
                  },
                  "learning_rate": {
                    "nullable": false,
                    "title": "Float",
                    "type": "number",
                    "description": "The speed at which the model learns during training.<br><br><table><tr><th>Model Type</th><th>Lora Focus</th><th>Min</th><th>Max</th><th>Default</th></tr><tr><td>Default</td><td>General | Style | Character | Object</td><td>0.00000001</td><td>0.00001</td><td>0.000001</td></tr><tr><td rowspan='3'>FLUX_DEV</td><td>Style</td><td>0.000001</td><td>0.00003</td><td>0.00001</td></tr><tr><td>Object</td><td>0.00001</td><td>0.001</td><td>0.0004</td></tr><tr><td>Character</td><td>0.00001</td><td>0.001</td><td>0.0005</td></tr><tr><td>General</td><td colspan='3'>NA</td></tr></table>"
                  }
                },
                "required": [
                  "name",
                  "datasetId",
                  "lora_focus",
                  "sd_version",
                  "learning_rate",
                  "num_train_epochs",
                  "train_text_encoder"
                ],
                "type": "object"
              }
            }
          },
          "description": "Query parameters to be provided in the request body as a JSON object.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sdTrainingJob": {
                      "nullable": true,
                      "properties": {
                        "userLoraId": {
                          "nullable": false,
                          "title": "Int",
                          "type": "integer"
                        },
                        "apiCreditCost": {
                          "nullable": true,
                          "type": "integer",
                          "description": "API Credits Cost for Model Training. Available for Production API Users. Note: it will be deprecated. Please use the cost instead.",
                          "deprecated": true
                        },
                        "cost": {
                          "$ref": "#/components/schemas/cost"
                        }
                      },
                      "title": "SDTrainingOutput",
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "sdTrainingJob": {
                    "userLoraId": 123456,
                    "apiCreditCost": null,
                    "cost": {
                      "amount": "0.0147",
                      "unit": "DOLLARS"
                    }
                  }
                }
              }
            },
            "description": "Responses for POST /elements."
          }
        }
      },
      "get": {
        "tags": [
          "Elements"
        ],
        "summary": "List Elements",
        "description": "Get a list of public Elements available for use with generations.",
        "operationId": "listElements",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "loras": {
                      "items": {
                        "description": "columns and relationships of \"elements\".",
                        "nullable": false,
                        "properties": {
                          "akUUID": {
                            "$ref": "#/components/schemas/lora/properties/akUUID"
                          },
                          "baseModel": {
                            "$ref": "#/components/schemas/sd_versions"
                          },
                          "creatorName": {
                            "$ref": "#/components/schemas/lora/properties/creatorName"
                          },
                          "description": {
                            "$ref": "#/components/schemas/lora/properties/description"
                          },
                          "name": {
                            "$ref": "#/components/schemas/lora/properties/name"
                          },
                          "urlImage": {
                            "$ref": "#/components/schemas/lora/properties/urlImage"
                          },
                          "weightDefault": {
                            "$ref": "#/components/schemas/lora/properties/weightDefault"
                          },
                          "weightMax": {
                            "$ref": "#/components/schemas/lora/properties/weightMax"
                          },
                          "weightMin": {
                            "$ref": "#/components/schemas/lora/properties/weightMin"
                          }
                        },
                        "title": "loras",
                        "type": "object"
                      },
                      "nullable": false,
                      "type": "array"
                    }
                  }
                }
              }
            },
            "description": "Responses for GET /api/rest/v1/elements."
          }
        }
      }
    }
  },
  "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 th

# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/leonardo-ai/refs/heads/main/openapi/leonardo-ai-elements-openapi.json
Leonardo.AI Elements API

Documentation

Specifications

Other Resources

OpenAPI Specification
