Kalpana Docs

`create_design`

Start a new page: a canvas of the given size with a background. It is saved in the workspace at once.

Parameter	Type	Required	Default	Description
`width`	`number`	Yes	—	1 to 8192 px.
`height`	`number`	Yes	—	1 to 8192 px.
`intent`	`string`	Yes	—	What and why.
`name`	`string`	No	`"Untitled"`	The design's name.
`background`	fill	No	White	The canvas fill; `"none"` for transparent.
`template_id`	`string`	No	A new template	Add the page as the next page of this template.

Common sizes: 1080 × 1080 or 1080 × 1350 feed post, 1080 × 1920 story, 1920 × 1080 or 1200 × 628 landscape.

Returns: The new page's page_id and its template_id.

`create_layers`

Add layers to a page, nested with their children, in one call.

Parameter	Type	Required	Default	Description
`page_id`	`string`	Yes	—	The page.
`intent`	`string`	Yes	—	What and why.
`preview`	`boolean`	No	`false`	Also return a picture of the result.
`layers`	layer`[]`	No	—	The layers to add, each with `type` and optional `children`.
`parent_id`	`string`	No	The page	Frame or group to add into.
`index`	`integer`	No	End	Position among the parent's children (front-most last).
`replace`	`boolean`	No	`false`	A layer in `layers` whose `id` exists replaces that layer and its children in place, keeping the id.

Returns: The new layer ids.

Every text and image layer becomes an input of the template, labelled by its name. font_family must be one of the families list_fonts returns; any other is refused.

`update_layers`

Change existing layers. Only the fields given change; send every fix in one call.

Parameter	Type	Required	Default	Description
`page_id`	`string`	Yes	—	The page.
`intent`	`string`	Yes	—	What and why.
`page_ids`	`string[]`	No	—	Instead of `page_id`: 1 to 5 pages to make the same updates on, such as the slides of a carousel made with `duplicate`. Every layer an update names by id must be on every page with the same type, or no page changes. The reply lists each page under `pages`. Each page counts as one paid call.
`updates`	`object[]`	No	—	One per layer: its `id`, or `select` instead of `id` to pick many layers (`{name, within, type}`: `name` takes `*` and `?`, case-sensitive; `within` is a frame or group id; `type` is a layer type), and any layer fields except `type` and `children`. Also `coords` (`parent` or `page`) for how x and y are read.
`preview`	`boolean`	No	`false`	Also return a picture of the result.
`updates[].if_match`	`string`	No	—	The layer's etag from `get_design`. If the layer changed since, that update is refused with its current state. Not listed in the tool's schema.

To move, wrap or align layers, use edit_structure; to delete them, delete_layers.

`edit_structure`

Change the layer tree with a list of operations, applied in order. It does not delete layers; that is delete_layers.

Parameter	Type	Required	Default	Description
`page_id`	`string`	Yes	—	The page.
`intent`	`string`	Yes	—	What and why.
`ops`	`object[]`	Yes	—	The operations below, each with its `op`.
`skip_missing`	`boolean`	No	`false`	Skip ids that are not on the page in `move`, `unwrap` and `set_id` instead of failing the call; the result lists them in `skipped`.

`op`	Fields	Does
`move`	`ids` (required), `parent_id`, `index`	Move layers under another parent (the page when `parent_id` is omitted), at `index`. Their x/y stay relative to the new parent.
`duplicate`	`id` (required), `count` (1), `offset_x` (0), `offset_y` (0)	Copy a layer with its children and motion next to the original; each copy shifts by the offsets from the previous one.
`wrap`	`ids` (required), `name`, `id`, `flow`	Wrap siblings in a new group, or in a frame with a layout flow when `flow` is given. `id` gives the new layer its id.
`frame`	`ids` (required), `name`, `id`	Wrap siblings in a frame fitted around them, without a flow. `id` gives the frame its id.
`boolean`	`ids` (required), `operation` (required: `union`, `subtract`, `intersect`, `exclude`), `name`	Combine shapes into one boolean layer that takes the bottom shape's fills; the shapes stay inside it, editable. With one boolean layer in `ids`, only its operation changes.
`unwrap`	`id` (required)	Remove a group, frame or boolean, keeping its children in its place.
`mask`	`ids` (required), `name`	Wrap siblings in a "Mask group" whose bottom layer masks the ones above it.
`unmask`	`ids` (required)	Stop layers from masking.
`scale`	`ids` (required), `factor` (required), `about` (`origin` or `center`)	Scale layers and everything inside them: size, text, spacing, radii, strokes, effects and paths.
`align`	`ids` (required), `to` (required: `left`, `center`, `right`, `top`, `middle`, `bottom`), `relative_to` (`selection` or `parent`)	Line layers up with the box around them, or one layer with its parent. Layers a flow places cannot move.
`distribute`	`ids` (required, 3 or more), `axis` (required: `x` or `y`)	Even gaps between layers; the first and last stay.
`reorder`	`id` (required), `to` (required: `front`, `back`, `forward`, `backward`)	Change paint order among siblings.
`set_id`	`id` (required), `new_id` (required)	Give a layer a new unused id. After `duplicate`, give each page's own content its own id.

`delete_layers`

Delete layers and everything inside them, with their motion. undo brings them back.

Parameter	Type	Required	Default	Description
`page_id`	`string`	Yes	—	The page.
`intent`	`string`	Yes	—	What and why.
`ids`	`string[]`	Yes	—	The layers to delete.
`skip_missing`	`boolean`	No	`false`	Skip ids that are not on the page instead of refusing the call; the result lists them in `skipped`.

Returns: The deleted layer ids. To hide a layer for now, set visible: false with update_layers.

`get_design`

An outline of a page's layers after layout. Read it before changing a design.

Parameter	Type	Required	Default	Description
`page_id`	`string`	Yes	—	The page.
`node_id`	`string`	No	The whole page	Describe only this layer and what is inside it.
`depth`	`integer`	No	All	Levels of children to include.
`compact`	`boolean`	No	`false`	A shorter reply, to look rather than edit.
`time`	`number`	No	`0`	The moment of an animation to describe.
`with_preview`	`boolean`	No	`false`	Also return a small picture of the page at `time`.
`timeline`	`boolean`	No	`false`	Also return the timeline: length, still time, choreography and what moves on each layer and when. With `node_id`, that layer's keyframes as `[time, value]`.
`timeline_detail`	`boolean`	No	`false`	Like `timeline`, with keyframes as `{t, value, easing, hold}`, to tune with `edit_keyframes`.

Returns: Each layer's id, type, name, box [x, y, w, h] in page px, text, colours, layout flow and etag, plus the fonts used.

Add an SVG (icon, logo, illustration, a drawing made elsewhere) as editable vector layers inside one group. Paths, rectangles, circles, lines and polygons keep their fills, strokes, linear and radial gradients and transforms. Each <g> becomes a group named from its id, data-name or inkscape:label, and each shape keeps its name, so update_layers and animate can find them.

Parameter	Type	Required	Default	Description
`page_id`	`string`	Yes	—	The page.
`intent`	`string`	Yes	—	What and why.
`svg`	`string`	Yes	—	The SVG markup.
`name`	`string`	No	`"SVG"`	Name of the group the shapes go into.
`parent_id`	`string`	No	The page	Frame or group to add into.
`width`	`number`	No	The SVG's own width	Width in px to scale to, keeping the aspect ratio. A larger SVG is shrunk to fit inside the parent.
`x`	`number`	No	Centred	Left edge in px, relative to the parent.
`y`	`number`	No	Centred	Top edge in px, relative to the parent.

Returns: The group's id as group_id, the number of shapes, the placed size, every layer made, and skipped: text, images, masks, clips, filters and <use> are not imported and are listed there.

`make_chart`

A chart drawn from numbers as editable layers. Every point, bar, tick and label is computed.

Parameter	Type	Required	Default	Description
`page_id`, `intent`	`string`	Yes	—	The page, and what and why.
`x`, `y`, `width`, `height`	`number`	Yes	—	Where the chart sits in its parent, and its size.
`series`	`{values, name?, color?}[]`	Yes	—	The data. Colours come from `palette` when left out.
`kind`	`string`	No	`"line"`	`line`, `bar`, `area`, `step`, `horizontal_bar`, `stacked_bar`, `scatter`, `donut`, `pie`, `sparkline`, `progress_ring`, `gauge` or `radar`.
`style`	`string`	No	`"clean"`	`clean`, `minimal`, `bold`, `editorial`, `glow` (for dark backgrounds), `blocks` or `outline`.
`labels`	`string[]`	No	—	A label per value along the x axis (per bar, segment or spoke).
`palette`	`string[]`	No	Built-in	Series colours in order, as hex.
`font_family`, `font_size`	`string`, `number`	No	Size: height ÷ 22, at least 24	Every chart label's font.
`text_color`, `grid_color`	`string`	No	—	Hex.
`axes`, `x_labels`, `y_labels`	`boolean`	No	Per style	Axis labels, both or each side.
`grid`, `ticks`	`boolean`, `integer`	No	`ticks`: 4	Grid lines; `ticks: 0` removes them and the y labels.
`legend`	`boolean`	No	With 2+ series	A key of series names.
`value_labels`	`boolean`	No	—	Label the last point, each bar's top or the ring's value.
`dots`, `smooth`	`boolean`	No	Per style	A dot on each point; curved lines.
`line_width`, `bar_width`, `corner`, `thickness`	`number`	No	Per style	Line width, bar share of its slot (0.1 to 1), bar corner radius, ring thickness.
`max`	`number`	No	`100`	Full scale for `progress_ring`, `gauge` and `radar`.
`y_min`, `y_max`	`number`	No	From the data	Fix the value range.
`x_values`, `sizes`	`number[]`	No	—	Scatter: each point's x, and sizes for a bubble chart.
`step_at`	`string`	No	`"start"`	Step charts: `start`, `middle` or `end`.
`decimals`	`integer` \| `"auto"`	No	0 or 1	Decimal places in value labels.
`prefix`, `suffix`	`string`	No	—	Around every value label.
`annotations`	`object[]`	No	—	`{kind: "callout", index, text, series?}`, `{kind: "target", value, text?}` (a dashed line) or `{kind: "range", from, to, text?}` (a shaded band).
`name`, `parent_id`	`string`	No	`"Chart"`, the page	The chart layer's name and parent.

Layers