Skip to main content

Plan Image Generation

Immutable Catalog + Curated Guide

This lossless descriptor comes from the active Portal catalog and is enhanced with reviewed examples.

READleonardo-ai.leonardo_plan_image_generation
  • Contract tier: agent_ready
  • Risk: read
  • Catalog version: leonardo-ai-2026.07.12.1
  • Descriptor hash: 988b910e1be7886a6f2b6d84874dc5d29681fdcd710a585ea34180e65ef1a03a

Validate an image-generation plan and receive model, dimension, and execution guidance without creating media.

Request Body​

{
  "jsonrpc": "2.0",
  "id": "leonardo-ai-leonardo-plan-image-generation-example",
  "method": "tools/call",
  "params": {
    "name": "leonardo-ai.leonardo_plan_image_generation",
    "arguments": {
      "model": "",
      "prompt": "",
      "modelId": "",
      "private": false,
      "use_case": "use_case_example",
      "numImages": "",
      "model_name": "",
      "num_images": 1,
      "aspect_ratio": "1:1",
      "modern_model": "legacy_v1"
    }
  }
}

Arguments Schema​

{
  "type": "object",
  "properties": {
    "model": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional natural model name or provider model string. Examples: nano-banana-2, Nano Banana 2, Nano Banana Pro, gemini-image-2."
    },
    "prompt": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "User's desired image outcome."
    },
    "modelId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional v1 modelId or alias for model when agents use provider casing."
    },
    "private": {
      "type": "boolean",
      "default": true,
      "description": "When true, request private output by setting public=false."
    },
    "use_case": {
      "type": "string",
      "default": "general",
      "description": "Use case such as general, photorealistic, text, character, fast, product, logo, poster, or free-form."
    },
    "numImages": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "CamelCase alias for num_images; used by some agents."
    },
    "model_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional human-readable model name alias."
    },
    "num_images": {
      "type": "integer",
      "default": 4,
      "description": "Number of candidate images to request."
    },
    "aspect_ratio": {
      "enum": [
        "1:1",
        "16:9",
        "9:16",
        "4:3",
        "3:4"
      ],
      "type": "string",
      "default": "1:1",
      "description": "Target composition aspect ratio."
    },
    "modern_model": {
      "enum": [
        "legacy_v1",
        "flux_2_pro",
        "nano_banana_pro",
        "nano_banana_2",
        "gpt_image_1_5"
      ],
      "type": "string",
      "default": "legacy_v1",
      "description": "Use legacy_v1 for the broad v1 model catalog, or choose a modern v2 image model such as flux_2_pro, nano_banana_pro, nano_banana_2, or gpt_image_1_5."
    },
    "target_medium": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional planning context such as wallpaper, poster, or product shot."
    },
    "reference_plan": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional free-form reference handling notes; accepted for agents."
    },
    "reference_image_ids": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional Leonardo image IDs to use as references. Upload user-owned images with leonardo_upload_reference_image first, or use generated image IDs from completed generations."
    },
    "reference_image_type": {
      "enum": [
        "GENERATED",
        "UPLOADED"
      ],
      "type": "string",
      "default": "UPLOADED",
      "description": "Type of reference_image_ids when using modern v2 image models."
    }
  },
  "additionalProperties": false
}

Output Schema​

{
  "type": "object",
  "description": "Leonardo MCP result. ok=false, provider_ok=false, a failed status, or an error field represents a semantic failure even when transport delivery succeeded.",
  "additionalProperties": true
}

Code Examples​

curl -X POST 'https://portal.madpanda3d.com/api/mcp' \
  -H 'Authorization: Bearer mad_live_***' \
  -H 'Content-Type: application/json' \
  -d '{
  "jsonrpc": "2.0",
  "id": "leonardo-ai-leonardo-plan-image-generation-example",
  "method": "tools/call",
  "params": {
    "name": "leonardo-ai.leonardo_plan_image_generation",
    "arguments": {
      "model": "",
      "prompt": "",
      "modelId": "",
      "private": false,
      "use_case": "use_case_example",
      "numImages": "",
      "model_name": "",
      "num_images": 1,
      "aspect_ratio": "1:1",
      "modern_model": "legacy_v1"
    }
  }
}'

Example Responses​

{
  "ok": true,
  "data": {
    "ready": true,
    "nextAction": "price_before_submit"
  },
  "error": null
}