Leonardo.AI Init Images API
Upload, retrieve, and delete init images used for image-to-image, image-prompt, canvas, and image-guidance workflows. Returns presigned upload URLs.
OpenAPI Specification
{
"openapi": "3.0.0",
"info": {
"title": "Leonardo.AI Init Images API",
"description": "Upload, retrieve, and delete init images used for image-to-image, canvas, and image-prompt workflows.",
"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": "Init Images"
}
],
"paths": {
"/init-image": {
"post": {
"tags": [
"Init Images"
],
"summary": "Upload init image",
"description": "This endpoint returns presigned details to upload an init image to S3",
"operationId": "uploadInitImage",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"extension": {
"nullable": false,
"title": "String",
"type": "string",
"description": "Has to be png, jpg, jpeg, or webp."
}
},
"required": [
"extension"
],
"type": "object"
}
}
},
"description": "Query parameters provided in the request body as a JSON object",
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"uploadInitImage": {
"nullable": true,
"properties": {
"fields": {
"nullable": true,
"title": "String",
"type": "string"
},
"id": {
"nullable": true,
"title": "String",
"type": "string"
},
"key": {
"nullable": true,
"title": "String",
"type": "string"
},
"url": {
"nullable": true,
"title": "String",
"type": "string"
}
},
"title": "InitImageUploadOutput",
"type": "object"
}
}
}
}
},
"description": "Responses for POST /init-image"
}
}
}
},
"/init-image/{id}": {
"get": {
"tags": [
"Init Images"
],
"summary": "Get single init image",
"description": "This endpoint will return a single init image",
"operationId": "getInitImageById",
"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": {
"init_images_by_pk": {
"description": "columns and relationships of \"init_images\"",
"nullable": true,
"properties": {
"createdAt": {
"$ref": "#/components/schemas/timestamp"
},
"id": {
"$ref": "#/components/schemas/uuid"
},
"url": {
"nullable": false,
"title": "String",
"type": "string"
}
},
"title": "init_images",
"type": "object"
}
}
}
}
},
"description": "Responses for GET /init-image/{id}"
}
}
},
"delete": {
"tags": [
"Init Images"
],
"summary": "Delete init image",
"description": "This endpoint deletes an init image",
"operationId": "deleteInitImageById",
"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": {
"delete_init_images_by_pk": {
"description": "columns and relationships of \"init_images\"",
"nullable": true,
"properties": {
"id": {
"$ref": "#/components/schemas/uuid"
}
},
"title": "init_images",
"type": "object"
}
}
}
}
},
"description": "Responses for DELETE /init-image/{id}"
}
}
}
},
"/canvas-init-image": {
"post": {
"tags": [
"Init Images"
],
"summary": "Upload Canvas Editor init and mask image",
"description": "This endpoint returns presigned details to upload an init image and a mask image to S3",
"operationId": "uploadCanvasInitImage",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"initExtension": {
"nullable": false,
"title": "String",
"type": "string",
"description": "Has to be png, jpg, jpeg, or webp."
},
"maskExtension": {
"nullable": false,
"title": "String",
"type": "string",
"description": "Has to be png, jpg, jpeg, or webp."
}
},
"required": [
"initExtension",
"maskExtension"
],
"type": "object"
}
}
},
"description": "Query parameters provided in the request body as a JSON object",
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"uploadCanvasInitImage": {
"nullable": true,
"properties": {
"initImageId": {
"nullable": true,
"title": "String",
"type": "string"
},
"initFields": {
"nullable": true,
"title": "String",
"type": "string"
},
"initKey": {
"nullable": true,
"title": "String",
"type": "string"
},
"initUrl": {
"nullable": true,
"title": "String",
"type": "string"
},
"maskImageId": {
"nullable": true,
"title": "String",
"type": "string"
},
"maskFields": {
"nullable": true,
"title": "String",
"type": "string"
},
"maskKey": {
"nullable": true,
"title": "String",
"type": "string"
},
"maskUrl": {
"nullable": true,
"title": "String",
"type": "string"
}
},
"title": "CanvasInitImageUploadOutput",
"type": "object"
}
}
}
}
},
"description": "Responses for POST /canvas-init-image"
}
}
}
}
},
"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."
},
"motionStrength": {
"nullable": true,
"title": "Int",
"type": "integer",
"description": "The motion strength."
},
"public": {
"nullable": true,
"title": "Boolean",
"type": "boolean",
"description": "Whether the generation is public or not"
},
"strength": {
"type": "string",
"nullable": false,
"title": "strength",
"enum": [
"VERY_LOW",
"LOW",
"MEDIUM",
"HIGH"
],
"description": "When training using the PIXEL_ART model type, this influences the training strength.",
"default": "MEDIUM"
},
"job_status": {
"type": "string",
"nullable": false,
"title": "job_status",
"enum": [
"PENDING",
"COMPLETE",
"FAILED"
],
"description": "The status of the current task."
},
"BlueprintExecutionStatus": {
"type": "string",
"nullable": false,
"title": "BlueprintExecutionStatus",
"enum": [
"PENDING",
"QUEUED",
"COMPLETED",
"FAILED"
],
"description": "The status of a Blueprint Execution."
},
"BlueprintExecution": {
"type": "object",
"nullable": false,
"title": "BlueprintExecution",
"description": "Represents the Execution of a Blueprint Version",
"properties": {
"akUUID": {
"allOf": [
{
"$ref": "#/components/schemas/uuid"
},
{
"nullable": false,
"description": "akUUID of the Blueprint Execution"
}
]
},
"status": {
"$ref": "#/components/schemas/BlueprintExecutionStatus",
"description": "Status of the Blueprint Execution"
},
"inputs": {
"type": "array",
"nullable": false,
"description": "Inputs of the Blueprint Execution",
"items": {
"$ref": "#/components/schemas/NodeInput"
}
},
"public": {
"allOf": [
{
"$ref": "#/components/schemas/public"
},
{
"nullable": false,
"description": "Whether the Blueprint Execution is public"
}
]
},
"createdAt": {
"$ref": "#/components/schemas/timestamp",
"description": "Created date of the Blueprint Execution"
}
},
"required": [
"akUUID",
"status",
"inputs",
"public",
"createdAt"
]
},
"BlueprintExecutionGenerationsConnection": {
"type": "object",
"nullable": false,
"title": "BlueprintExecutionGenerationsConnection",
"description": "A paginated connection of Blueprint Execution Generations",
"properties": {
"pageInfo": {
"$ref": "#/components/schemas/pageInfo"
},
"edges": {
"type": "array",
"description": "List of generation edges",
"items": {
"$ref": "#/components/schemas/BlueprintExecutionGenerationEdge"
}
}
},
"required": [
"pageInfo",
"edges"
]
},
"BlueprintExecutionGenerationEdge": {
"type": "object",
"nullable": false,
"title": "BlueprintExecutionGenerationEdge",
"description": "An edge containing a Blueprint Execution Generation node",
"properties": {
"cursor": {
"$ref": "#/components/schemas/Cursor",
"description": "Cursor for this edge, used for pagination"
},
"node": {
"$ref": "#/components/schemas/BlueprintExecutionGeneration"
}
},
"required": [
"cursor",
"node"
]
},
"BlueprintExecutionGeneration": {
"type": "object",
"nullable": false,
"title": "BlueprintExecutionGeneration",
"description": "Represents a single generation within a Blueprint Execution",
"properties": {
"akUUID": {
"allOf": [
{
"$ref": "#/components/schemas/uuid"
},
{
"nullable": false,
"description": "Unique identifier for the Blueprint Execution Generation"
}
]
},
"status": {
"$ref": "#/components/schemas/BlueprintExecutionGenerationStatus",
"description": "Status of the generation"
},
"generationId": {
"type": "string",
"nullable": false,
"description": "The generation ID associated with this execution generation",
"example": "1f0bba44-923a-69b0-b519-62a6710d46a9"
},
"failedReason": {
"$ref": "#/components/schemas/PromptModerationFailureReason",
"description": "Details about why the generation failed, specifically for prompt moderation failures"
}
},
"required": [
"akUUID",
"status",
"generationId"
]
},
"BlueprintExecutionGenerationStatus": {
"type": "string",
"nullable": false,
"title": "BlueprintExecutionGenerationStatus",
"enum": [
"PENDING",
"COMPLETED",
"FAILED"
],
"description": "The status of a Blueprint Execution Generation"
},
"PromptModerationFailureReason": {
"type": "object",
"nullable": true,
"title": "PromptModerationFailureReason",
"description": "Details about a generation failure due to prompt moderation",
"properties": {
"type": {
"type": "string",
"nullable": false,
"enum": [
"PROMPT_MODERATION_BLOCKED"
],
"description": "The type of failure - PROMPT_MODERATION_BLOCKED indicates the prompt was blocked by content moderation",
"example": "PROMPT_MODERATION_BLOCKED"
},
"message": {
"type": "string",
"nullable": false,
"description": "Human-readable message describing the failure",
"example": "Generation blocked due to prompt moderation"
},
"affectedOutputCount": {
"type": "integer",
"nullable": false,
"description": "Number of outputs affected by this failure",
"example": 1
}
},
"required": [
"type",
"message",
"affectedOutputCount"
]
},
"custom_model_type": {
"type": "string",
"default": "GENERAL",
"nullable": false,
"title": "custom_model_type",
"enum": [
"GENERAL",
"BUILDINGS",
"CHARACTERS",
"ENVIRONMENTS",
"FASHION",
"ILLUSTRATIONS",
"GAME_ITEMS",
"GRAPHICAL_ELEMENTS",
"PHOTOGRAPHY",
"PIXEL_ART",
"PRODUCT_DESIGN",
"TEXTURES",
"UI_ELEMENTS",
"VECTOR"
],
"description": "The category the most accurately reflects the model."
},
"sd_generation_schedulers": {
"type": "string",
"nullable": false,
"title": "sd_generation_schedulers",
"enum": [
"KLMS",
"EULER_ANCESTRAL_DISCRETE",
"EULER_DISCRETE",
"DDIM",
"DPM_SOLVER",
"PNDM",
"LEONARDO"
],
"description": "The scheduler to generate images with. Defaults to EULER_DISCRETE if not specified."
},
"VARIATION_TYPE": {
"type": "string",
"nullable": false,
"title": "VARIATION_TYPE",
"enum": [
"OUTPAINT",
"INPAINT",
"UPSCALE",
"UNZOOM",
"NOBG"
],
"description": "The type of variation."
},
"MOTION_VARIATION_TYPE": {
"type"
# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/leonardo-ai/refs/heads/main/openapi/leonardo-ai-init-images-openapi.json