Kalpana Designer

Add motion to layers: presets (fade_in, slide_in_up, pop_in, spring_in, bounce_in, tilt_in, blur_in, wipe_in_right, draw_on, pulse, float, spin, shake, drift, count_up, count_down, orbit, ring_spin, peel, decoration_on and the outs) placed at a start time, raw keyframes per property (with springs), word or letter text reveals (typewriter, scramble), shape morphs between a vector layer's shapes, and stagger to cascade a motion over a layer's children. Motion adds to what a layer has unless replace is set; the timeline grows to fit. Returns the timeline. Saved as a new revision that undo reverts; if any part is refused, nothing changes. Use it to add or replace motion; to tune one keyframe use edit_keyframes, to remove motion clear_animation, and check the result with render_contact_sheet. Guide topic: motion. A template with motion can still fill batches as images. Each image shows one moment of the motion. The default moment is the last frame. An outro or a loop can make the last frame a bad image. Find the moment where all the content shows (render_contact_sheet, render_timeline), ask the user if you are not sure, and set that second with set_timeline still_time.

Evaluate arithmetic exactly instead of estimating: + - * / % ^, parentheses, pi, trigonometry in radians (rad() and deg() convert), sqrt, abs, min, max, round, floor, ceil, clamp, lerp, pow, hypot, atan2, ln, log10, exp. Give one expression (returns result), named expressions that can use earlier names (returns each by name), or an expression over a series of a variable (returns values as [x, y] pairs, up to 2000 steps). Answers are rounded to 6 decimal places, and a malformed expression is refused with the reason. Free, read-only, no design needed. Use it for sizes, positions and angles, and for colour contrast with the formula in design_guide; for positions of many items use place_items, for start times stagger_times.

Film a design with a camera: push in on a detail, pan across, roll, tilt in 3D, pull back. stops give each moment's time, zoom (1 = whole design), the focus point at the centre of the shot, and rotation or tilt. The layers move into a design-sized Camera frame at the back (their own positions do not change); kinetic type and transitions stay above the shot. Calling it again replaces the move, keeping the shot. Returns the camera_id, layers in the shot (count), the timeline. Saved as a new revision that undo reverts; if any part is refused, nothing changes. Use it for one continuous move over the whole design; for slides joined by transitions use set_choreography flow, and to move a single layer animate.

Find layout problems in a design after layout: text over other text, layers cut off by a clipping frame or running off the canvas, text too small for the size the design is seen at, and text with too little contrast on what is behind it. Returns every issue at once, each naming its layers with a severity (error, or info that is often on purpose), and ok when none is an error (cut text is one). Read-only. Run it before finishing a design (edits already report the issues they cause), and confirm an issue with render_design before changing anything; to size text before placing it use measure_text. craft: true adds opt-in craft checks; ignore, allow_bleed and display_width quiet what is intended. Guide topic: critique.

Remove motion from a design: every layer's (no node_ids) or the given layers', all their properties or only tracks (shape also removes a shape morph's outlines). Layers keep their static look and position. Returns the layers cleared. Saved as a new revision that undo reverts; if any part is refused, nothing changes. Use it to start a layer's motion over before animate; to change one keyframe use edit_keyframes, to redo one property clear its tracks, and to change the length set_timeline.

Start a new design: a blank page of the given size (1080x1080 post, 1080x1350 portrait post, 1080x1920 story, 1920x1080 slide or banner) with a background, white when omitted. Without template_id it starts a new template; with one it becomes that template's next page, sharing its inputs by layer name. Returns page_id, template_id and the size. Use it to start from nothing; to build on an existing design use search_templates, and to copy a page (a carousel slide, another size) use duplicate. Then build the content in one create_layers call.

Add a flow to a template: some of its pages in order, joined by transitions, as one video. Edits to the pages not yet saved are saved first. By default a page holds for its own duration, so give each page its motion before adding a flow, or update the flow after. Returns the flow with its flow_id and length. Choosing transitions: design_guide topic flows.

Add layers to a design in one call: frames, groups, text, rectangles, ellipses, lines, images (a workspace image key or an https URL) and vectors (SVG path data), nested with children. Frames with a flow arrange their children in a row or column, so build text stacks and button rows as flows instead of placing each line by hand. parent_id adds inside a frame, index sets the paint position, and replace swaps the layer with the same id in place. Returns the new layer ids and the layout_issues this call caused (overflow, overlap, text off the page). Saved as a new revision that undo reverts; if any part is refused, nothing changes. Use it for new layers; change existing ones with update_layers, bring in SVG artwork with import_svg, and copy whole pages with duplicate.

Delete a flow. Its pages stay in the template, and videos already rendered from it stay. This cannot be undone here, so ask the user first unless they told you to.

Delete layers from a design, with everything inside them and their motion. Returns the deleted layer ids (and any skipped with skip_missing). If one id is not on the design the call is refused and nothing is deleted. Saved as a new revision: undo brings the layers back, but only until the next change is undone past. Use it to remove layers the design no longer needs; to hide one for now set visible: false with update_layers, and to remove a whole page use delete_page.

Delete one or more pages of a template, with their layers and motion. Every page is checked before any is deleted: an unknown id, or a call that would delete every page of a template (a template keeps at least one), refuses the whole call and nothing is deleted. Deleted pages cannot be brought back, not even with undo; confirm with the user first. Returns the deleted page_ids and their template_ids. Use it to remove sizes or variants the user no longer wants; to remove layers inside a page use delete_layers.

Return the designer's guide as text. Without topics: the core (about 1,200 words): how templates, pages and flows fit together, the working loop, what calls cost, the rules for every design, and the list of topics with which jobs need which. With topics: those topics, such as brief, ad, structure, sizes, colour, type, imagery, effects, critique, motion or batch; ask for every topic the job needs in one call. Read-only and free. Read the core before the first design in a conversation and follow the guide over your own defaults; it is the source of truth for these tools.

Copy pages into the same or a new template. Each copy keeps its layers, layer ids, names, motion and input descriptions, and never replaces a page or a template. Returns the template_id and each copy's page_id and name. With template_id, the copies are added to that template (it can be the pages' own template). Without template_id, a new template is made and the first copy is its first page. To copy a whole template, give all its pages from list_pages. With width and height, each copy gets that page size, and the flows and constraints place its layers again: render the copy and adjust it for the new size. Use it for the slides of a carousel (then restyle them together with update_layers page_ids) and for other sizes of a finished design (plan each size first: design_guide topic sizes); to add an empty page use create_design with template_id.

Tune existing motion one keyframe at a time: add a keyframe, move one in time, change its value or easing (or hold), delete one, or shift a layer's whole motion earlier or later. Keyframes are found by track and time (read them with get_design timeline_detail); a delete that empties a track removes it. Returns what was edited. If one edit cannot apply, none do; saved as a new revision that undo reverts. Use it for small timing and value fixes; to replace a whole track use animate with tracks, and to remove motion clear_animation.

Change a design's layer tree with a list of ops, applied in order: move layers to another parent or position, duplicate, wrap siblings in a group or a flow frame, mask, combine shapes with a boolean (union, subtract, intersect, exclude), unwrap, scale with everything inside, reorder, align and distribute. Nothing is deleted here: removing layers is delete_layers. Returns the created and moved layer ids. If one op cannot apply the whole call is refused and nothing changes, unless skip_missing skips layers that are gone. Saved as a new revision that undo reverts. Use it for structure; for a layer's own properties use update_layers, and for new layers create_layers. Guide topic: structure.

Images in this workspace (photos, logos, product shots), newest first, or those whose file name contains search or that are in a collection, with a numbered preview sheet to see them. Without filters the reply also names the workspace's collections: when the user says where their images are ("the Diwali photos"), look in that collection. Each image comes with its image key, the key a design places it by, its asset_id, the id the same image has in batch rows, and its name and pixel size; a cut-out (transparent margins) also gets visible_box [x, y, w, h], where its subject sits in image px, to place and crop it by. The preview sheet is one numbered picture of the results; image bytes are not returned. It is a paid render: pass sheet: false for the list alone, free and without visible_box, to see what and which collections there are before you look. Read-only. Use it to find images already in the workspace; to bring in the user's own files use upload_images. Place one with create_layers type: "image" (or image in a fill) and name the layer by role ("Product photo"). Cutouts, scenes and people: design_guide topic imagery.

Read a design's layers after layout: id, type, name, box [x, y, w, h] in design px, text, colours, layout flow and each layer's etag, plus the fonts used. Read-only. Use it before changing a design, for the layer ids update_layers and edit_structure take; to see the design use render_design, and to find problems check_layout. compact shortens the reply, node_id with depth reads one branch, time gives positions at a moment of the motion, with_preview adds a small picture, and timeline: true adds what moves on each layer and when (with node_id, its keyframes).

Return the Kalpana workspace this connection designs in, chosen when the user connected: its id, name and slug, whether its organization has an active subscription, and allowed_image_domains, the hosts an image URL may come from (subdomains included). Read-only. Call it when you need the workspace's name for the user, when a tool says a subscription or credits are missing, or before placing an image from a URL: a URL on another host is refused, so tell the user to add the domain in Workspace Settings > Domain Whitelisting, or to upload the image with upload_images. Every other tool already works in this workspace and takes no workspace id; to design in another workspace the user reconnects and chooses it.

Add an SVG (icon, logo, illustration) as editable vector layers inside one new group, from its markup in svg: paths, rectangles, circles, lines and polygons with their fills, strokes, linear and radial gradients and transforms. Each becomes an unclipped frame; groups and shapes are named from id, data-name, inkscape:label or aria-label, so update_layers select and animate can find them. Text, images, masks, clips, filters and are skipped and listed in skipped: add text with create_layers and photos as image layers. Returns the group and every layer made. Saved as a new revision that undo reverts; if any part is refused, nothing changes. Use it for artwork drawn elsewhere; for exact geometric shapes use shape_path.

Add a phrase as kinetic type: words laid out one by one by the real text engine (wrapping at width, words sharing a baseline), with emphasis on chosen words (colour, style, size, tilt, a highlight pill) and motion that gives each word its own path: fly, drop, scatter, pop, wave, glitch, zoom, starting at start with stagger between words; exit_at sends them out. Seeded, so it varies by phrase but repeats exactly. Adds one new group each call and returns its group_id and the block's box and lines. Saved as a new revision that undo reverts; if any part is refused, nothing changes. Use it for animated headlines; for a plain typewriter or word reveal on an existing text layer use animate text_reveal.

List a template's flows. A flow joins some of its pages into one video with transitions, and a template can have any number, each with its own pages and order. Returns each flow's flow_id, name, description, length in seconds and steps. Give a flow_id to the batch connection's create_batch as flowIds to render it.

List the font families a design can use: Kalpana's global library plus the workspace's uploads. A design and its batches load fonts from Kalpana, so a font_family outside this list is refused. Without family it returns every family with its number of styles; with family it returns that family's styles (style name, weight, italic) when the name matches exactly, else the families whose name contains it, ignoring case, else close_matches from each word of the name. Read-only. Call it before setting font_family or font_style on text, to use a family and style that exist.

List the pages of a template: each page is a design of its own (a post, a story and a banner of one campaign, say). Returns the template's id, name and description, and each page's page_id, name, size and whether it is animated. Read-only. Use it after search_templates to get the page_id that get_design and the other design tools take; to copy pages use duplicate, and to add an empty page create_design with template_id.

List the shader fills a layer can use: procedural dot grids and halftone, grain and mesh gradients, god rays, noise, waves, dithering and more. Without name: every shader with its setting names and preset names. With name: that shader's settings with their defaults, its presets, and whether it needs an image. Read-only. Call it without name to choose a shader, then with name for the one you picked; plain colours, gradients and images need neither. Then set the fill with create_layers or update_layers as {shader, preset, params, speed} (speed: 0 keeps it still). Guide topic: effects.

Add an animated 3D card track inside one design: cards (image, title, subtitle) on a track that steps to the next card every step seconds; the centred card sits flat and its neighbours swing back in 3D (tilt), smaller and shaded. Adds one new group and returns its group_id, track_id and card_ids. Saved as a new revision that undo reverts; if any part is refused, nothing changes. Use it for a product or template showcase in motion; for an Instagram carousel post make one page per slide with duplicate instead.

Draw a chart from numbers as editable layers in a design: line, area, bar, horizontal bar, stacked bar, scatter, donut, pie, sparkline, progress ring, gauge or radar. Every point, bar, tick and label is computed exactly; pick a style, a palette and a font_size, and place it with x, y, width and height. Adds one new group each call and returns its chart_id and facts (ranges, labels dropped for lack of room). Saved as a new revision that undo reverts; if any part is refused, nothing changes. Use it for any chart instead of drawing bars or lines with shape_path or by hand; to change a chart, delete its group with edit_structure and draw it again.

Add an animated pointer to a design: an arrow, a named pill or a touch dot that glides through stops ({x, y, t, click}) with eased moves; each click presses it and spreads a ripple. Adds one new group on top of every layer each call and returns its group_id. Saved as a new revision that undo reverts; if any part is refused, nothing changes. Use it to walk through product UI in a demo, with make_list selections at the same times; to move other layers use animate, and to remove the cursor edit_structure delete.

Add rows of UI (a ranked list, inbox, settings, search results) with text and an optional value on the right; rows spring in one after another and a highlight slides from row to row at the select times. static: true builds a still list or table instead. Adds one new group each call and returns its group_id. Saved as a new revision that undo reverts; if any part is refused, nothing changes. Use it for list and table UI; pair it with make_cursor clicks at the same times, and for free text blocks use create_layers.

Add a particle field to a design: many small shapes (dots, rings, sparkles, stars, plus, cross, pills, squares, triangles, blobs) spread by a seed, with no clumps or grid, sizes leaning small, some out of focus, colours from a palette and a box kept clear behind text. Motion: float, twinkle, burst, rain, rise, pop, or still. Adds one new group behind the other layers (in front with front) each call and returns its group_id and count. Saved as a new revision that undo reverts; if any part is refused, nothing changes. Use it for texture, sparkle and celebration backgrounds; for a few placed shapes use create_layers, and for shapes in a pattern place_items.

Add a graphic transition: shapes that cover or reveal the whole design in one of four styles (circle, stripes, blades, burst). part: out ends fully covered at at + duration; part: in starts covered and uncovers. Adds one new group on top of every layer each call (it never replaces one) and returns its group_id. Saved as a new revision that undo reverts; if any part is refused, nothing changes. Use it to hide a cut between scenes of a multi-scene animation; to move between slides use set_choreography flow, and to fade one layer animate.

Measure text as the renderer lays it out: each line and its width, the height, and whether the last line is a widow; or, with width and fit_height, the largest font size that fits that box. With page_id and layer_id it measures that text layer as styled. texts measures many at once, and pack lays them out as chips in rows and returns each chip's box. Read-only; it changes nothing. Use it before placing or sizing text instead of guessing; for text already overflowing in a design use check_layout.

Compute where N items go: around a circle, along an arc, in a grid, evenly along a line or a path. Returns places in item order: each item's centre, its top-left x and y for an item of item_size, and the rotation in degrees that faces along the layout. Free and read-only; it places nothing itself. Use it for radial menus, timelines and grids, then pass the positions to create_layers; for a single value use calculate, and for the outline of a shape shape_path.

Rename one page of a template. Any edits to the design not yet saved are saved first; then the page takes the new name, which shows in Kalpana and in batches. Returns the page's page_id and new name; rename again to change it back. Use it to tell the pages of a template apart ("Story", "Banner"); to name the template itself use set_template_info.

Frames of the design's animation tiled into one PNG, left to right and top to bottom: evenly spaced frames from start to end, or exact times. One call checks a whole animation; a design without a timeline gives one frame. Returns the times shown. For one moment at full size use render_design with time. Previews are PNGs at most 800 px on the longest side, with a faint repeating "Kalpana preview" mark. The mark is only on previews; the design, its exports and batch renders do not have it, and sample_points read the design's own colours. Zoom with region or node_id to check small text or detail.

A PNG of the design, rendered as it will export. Check the work with it after each meaningful change. Zoom with region or node_id, read pixel colours with sample_points, or judge shapes with hide, only and mode; time shows one moment of an animation. For layout problems as data use check_layout; for many moments of an animation use render_contact_sheet. Previews are PNGs at most 800 px on the longest side, with a faint repeating "Kalpana preview" mark. The mark is only on previews; the design, its exports and batch renders do not have it, and sample_points read the design's own colours. Zoom with region or node_id to check small text or detail.

A PNG picture of the timeline as a diagram, not a frame of the design: a time ruler, a row per animated layer with a bar over its motion, and under it a row per property with keyframe diamonds; where the motion ends is marked. Check timing and overlap here, then get_design timeline with node_id for the keyframes to change. node_ids limits it to layers; properties: false shows layer rows only.

Find the workspace's templates to edit or reuse: newest first, or those matching query (an exact template id, or words of a name, description or campaign topic), limit per page. Each comes with its template_id, name, size, whether it is animated, a preview image URL and a link that opens it in Kalpana. Read-only. Use it when the user names an existing template or wants to start from one; to start fresh use create_design, and with a page's page_id already in hand go straight to get_design. To edit one, list_pages with its template_id gives each page's page_id for get_design and the other design tools.

Feedback for the people who build these tools, not for the user: a tool, its arguments or the design guide that was confusing, missing something, wrong, or that worked especially well, with what was tried, what happened and what would have helped. Send it when you hit a snag, and at the end of the work when you have anything to report or suggest; nothing needs sending when there is nothing to say. It holds no user content (their copy, names, image URLs or brand details). Free, and it changes nothing in the design; the reply only confirms it was received.

Replace the design's camera moves and morphs between layers with a value in the stored format (read the current one with get_design timeline); {} clears it. A flow alone (slides in order, joined by transitions) is compiled into the camera and morphs it plays. Validated before saving, and the timeline grows to fit. Returns the timeline. Saved as a new revision that undo reverts; if any part is refused, nothing changes. Use it to edit or clear choreography as a whole; for one camera move use camera, for a single layer's motion animate, for a wipe between scenes make_transition, and for the length set_timeline.

Save a template's name, description and what each input may hold; each field given replaces the old value, and fields left out keep theirs. Name: short and specific, e.g. "Ember Roasters autumn menu". Description: a sentence on what it is and where it is used. inputs: a description per text or image layer, by its id or name, saying what it holds and how long it can be, as characters and lines ("Headline: 10 to 45 characters, up to 2 lines"); batches show it to whoever fills the rows. Inputs merge by layer: one left out keeps its description, and "" clears it. Every text and image layer is an input until fixed marks it true: slide numbers, arrows and labels that never change per row (false makes it an input again). It also saves every change still waiting to be saved, so call it last: the template is then ready to fill with data. Returns the template's id, name, description, describedInputs (how many inputs now have a description) and fixedLayers, with a note when a change could not be saved. Use it once at the end of a design (measuring input limits: design_guide topic batch); to rename a single page use rename_page.

Set how the design plays: its length in seconds (at most 60), its frame rate, and still_time, the second a batch image shows (a negative value clears it, so images use the last frame). Fields left out keep their values. Returns the timeline. Saved as a new revision that undo reverts. Use it after animate when the motion needs more or less time, and always set still_time on a template with motion that will fill image batches; motion itself is set with animate and edit_keyframes, and camera moves with camera.

Compute exact SVG path data for a vector layer: a shape (arc, sector, ring, rounded polygon, star, spiral, wave, gear, arrow, blob, comic burst with jitter, seed and aspect, a smooth line through points, the graph of a function), a stroke's filled outline, a boolean of paths, or the gap between two shapes; layer_gap with page_id measures two placed layers. kind picks the shape and the schema lists the fields each kind takes. Returns paths, width and height (and x, y to place it). Read-only; it draws nothing. Pass the result to a vector layer in create_layers; to combine layers already in a design use edit_structure boolean, for charts make_chart, and for artwork import_svg.

Compute start times for N items that cascade in: step seconds apart, or spread over a total (give one of the two), evenly or with ease in or out, from start. Returns times, a list of seconds, one per item; count must be 1 to 5000, and a call with neither step nor total is refused. Free, read-only, no design needed. Use it to time a list, grid or word-by-word entrance, then pass the times to animate; for a cascade over one layer's children, animate's own stagger is simpler.

Revert the latest change to a design: the design goes back to how it was before that call (any tool that changed it: layers, structure, motion). Call it again to step back further; there is no redo, so an undone change has to be made again. Returns the revision the design is now at and the change it is back to; refused when there is nothing to undo. Free. Use it when an edit made things worse; to remove one property, change it with update_layers instead.

Change a flow's name, description, size or steps. steps replaces the whole list, so read it with list_flows first and send it back changed; fields left out keep their values. Returns the flow as it now is.

Change properties of existing layers: position and size, rotation, visibility, opacity, blend mode, masks, fills, strokes, radius, shadows, blur, image zoom and focus, vector paths, text and its style, flows and sizing in a flow. Only the fields given change. Each update names one layer by id, or many by select (a name pattern, a type, inside a frame); coords: "page" reads x and y in page coordinates, and page_ids makes the same updates on up to 5 pages. Returns the changed ids and the layout_issues this call caused. Saved as a new revision that undo reverts; if any part is refused, nothing changes. Use it to restyle or reposition layers in place; to put a layer in another parent, delete, wrap or align use edit_structure.

Bring the user's own images (PNG, JPEG or WebP, up to 5 MB each) into the workspace, optionally into a collection (made when it does not exist). Without files: a link to the workspace's Images page (the collection's page with collection) for the user to open and drop the images into; after they say they are done, find them with find_images and that collection. When you have the files yourself (a shell, files on disk): pass files with each one's SHA-256 hash, content type and size, PUT each file's bytes to its upload_url with that Content-Type header, then call again with done (each hash and file name) to record them; the reply gives each image's image key for create_layers and its asset_id for batch rows. Never send image data as base64. Files that did not arrive come back under failed and can be sent again; a file already stored is recognised by its hash and not stored twice. Use it for the user's own files; to use images already in the workspace use find_images, and images already on the web can be placed straight from their https URL.