backgrounds

Browse the catalog of background structures. Optionally filter by a free-text query, tag or mood word. Returns name, one-line summary, mood, use cases and a preview URL for each.

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Free text, e.g. \"calm waves\" or \"geometric poster\".",
      "type": "string"
    },
    "mood": {
      "description": "A mood word, e.g. dark, playful, minimal, retro.",
      "type": "string"
    },
    "tag": {
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Rank structures for a natural-language brief ("dark aurora glow for an AI landing page"). Returns why each matched, matching built-in palettes, and a ready-to-run example request for generate_background.

{
  "type": "object",
  "properties": {
    "brief": {
      "type": "string",
      "minLength": 2
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    }
  },
  "required": [
    "brief"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Full style card for one structure: what it looks like, mood, where text can go, tips, and every parameter it honours with ranges, defaults and the visual effect of low/high values. Also returns the JSON Schema for a generate request.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Structure name from list_backgrounds, e.g. \"wave\"."
    },
    "format": {
      "description": "markdown (default) is best for reading; json includes the JSON Schema.",
      "type": "string",
      "enum": [
        "markdown",
        "json"
      ]
    }
  },
  "required": [
    "name"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Built-in curated colour palettes with their hex colours and derived mood tags (dark, pastel, vivid, warm, cool…). Pass the id as palette.palette to generate_background.

{
  "type": "object",
  "properties": {
    "mood": {
      "description": "Filter by a mood tag, e.g. \"dark\" or \"pastel\".",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Saved brand palettes on this account. Pass a kit's slug as `brand` to generate_background to render on-brand without repeating hex colours.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Render a background as SVG or PNG. Deterministic: the same structure, options and seed always give the same image, so store the returned seed. Returns a permanent, cacheable image URL you can use directly in <img>/CSS, plus an inline PNG preview. Call describe_background first to learn which shape options the structure honours.

{
  "type": "object",
  "properties": {
    "structure": {
      "type": "string",
      "description": "Structure name, e.g. \"wave\"."
    },
    "seed": {
      "description": "Any string. Omit for a fresh random seed (returned in the result).",
      "type": "string"
    },
    "width": {
      "type": "integer",
      "minimum": 1,
      "maximum": 8192
    },
    "height": {
      "type": "integer",
      "minimum": 1,
      "maximum": 8192
    },
    "palette": {
      "type": "object",
      "properties": {
        "colors": {
          "description": "Explicit hex colours to draw from (best for brand matching). Overrides palette/scheme.",
          "minItems": 1,
          "maxItems": 12,
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^#?([0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$"
          }
        },
        "palette": {
          "description": "Id of a built-in palette from list_palettes, e.g. \"underTheSea\".",
          "type": "string"
        },
        "primaryColor": {
          "type": "string",
          "pattern": "^#?([0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$"
        },
        "secondaryColor": {
          "type": "string",
          "pattern": "^#?([0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$"
        },
        "backgroundColor": {
          "type": "string",
          "pattern": "^#?([0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$"
        },
        "gradientColor": {
          "description": "Gradient fills instead of flat colour.",
          "type": "boolean"
        },
        "useMultiColor": {
          "description": "false = everything in primaryColor.",
          "type": "boolean"
        },
        "colorSchemeType": {
          "description": "Derive a palette from primaryColor.",
          "type": "string",
          "enum": [
            "Mono",
            "Tetrade",
            "Analogic"
          ]
        },
        "opaqueColors": {
          "type": "boolean"
        }
      },
      "additionalProperties": false
    },
    "shape": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": [
          "number",
          "boolean",
          "string"
        ]
      },
      "description": "Structure-specific options; call describe_background for the exact keys, ranges and what they do."
    },
    "format": {
      "description": "png (default) returns a viewable image; svg returns the vector source.",
      "type": "string",
      "enum": [
        "svg",
        "png"
      ]
    },
    "pngWidth": {
      "description": "Raster width for PNG output/preview. Defaults to the render width, capped for inline previews.",
      "type": "integer",
      "minimum": 16,
      "maximum": 8192
    },
    "brand": {
      "description": "Slug of a saved brand kit (see list_brand_kits); its colours become the palette baseline.",
      "type": "string"
    }
  },
  "required": [
    "structure"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}