Raw schema
{
"type": "object",
"properties": {
"project_id": {
"type": "string",
"description": "Project ID"
},
"elements": {
"type": "array",
"items": {
"type": "object",
"properties": {
"clip_index": {
"type": "integer",
"minimum": 0,
"description": "Zero-based clip index"
},
"element_type": {
"type": "string",
"enum": [
"text",
"callout",
"rectangle",
"arrow",
"blur",
"spotlight",
"zoom",
"image",
"video",
"animation"
],
"description": "One of: text, callout, rectangle, arrow, blur, spotlight, zoom, image, video, animation. Omit when using component_id."
},
"component_id": {
"type": "string",
"minLength": 1,
"description": "Insert a SAVED COMPONENT exactly as stored — no AI generation, no restyling. This is how you reuse a component from your workspace verbatim (find one with find(type='element_components')). Components are workspace-scoped — there is no community library for them. A component is a fragment of a clip — one or more elements, possibly grouped — so this inserts ALL of them and returns every new element_id plus the animation's parameter_schema. Customise afterwards with update_elements(type_data.parameter_values). Mutually exclusive with element_type/type_data. To instead GENERATE a new animation using a component as a style reference, use element_type='animation' with type_data.base_component_id."
},
"group": {
"type": "string",
"minLength": 1,
"description": "Put this element in a named group. The name is the handle: items in ONE call sharing the same name land in the SAME group, and a later call with that name adds to it. Use it to keep a unit together (a card and its label, a stat and its caption) so the user can move or hide it as one thing. Grouping never moves anything — coordinates stay absolute. Animations and AI-generated images are created in the background and cannot be grouped as they are added; add them first, then set `group` via update_elements."
},
"x": {
"type": "number",
"description": "X position in canvas pixels. ORIGIN is alignment-dependent: TEXT only — left-aligned uses top-left, center-aligned uses CENTER POINT, right-aligned uses top-right. All other element types (callout, rectangle, arrow, blur, spotlight, image, animation) use top-left. For zoom, use type_data.center_x instead."
},
"y": {
"type": "number",
"description": "Y position in canvas pixels. ORIGIN matches x: center-aligned text positions by its vertical center. All other types and alignments use the top edge."
},
"width": {
"type": "number",
"minimum": 0,
"description": "Width, pixels (0 allowed — e.g. a bar that draws in from 0)"
},
"height": {
"type": "number",
"minimum": 0,
"description": "Height, pixels (0 allowed)"
},
"start_time": {
"type": "number",
"minimum": 0,
"description": "Appear at (seconds)"
},
"end_time": {
"type": "number",
"minimum": 0,
"description": "Disappear at (seconds)"
},
"name": {
"type": "string",
"description": "Label"
},
"rotation": {
"type": "number",
"description": "Rotation in degrees"
},
"keyframes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"timestamp": {
"type": "number",
"minimum": 0,
"description": "Clip-relative time in seconds"
},
"positionX": {
"type": "number",
"description": "X position in canvas pixels (NOT `x`). Uses the SAME alignment-aware origin as the element's top-level x — left-aligned text uses top-left, center-aligned uses CENTER POINT, right-aligned uses top-right; all other types use top-left."
},
"positionY": {
"type": "number",
"description": "Y position in canvas pixels (NOT `y`). Origin matches positionX — center-aligned text positions by vertical center."
},
"width": {
"type": "number",
"minimum": 0,
"description": "Width in canvas pixels (0 allowed — e.g. a bar that draws in from 0)"
},
"height": {
"type": "number",
"minimum": 0,
"description": "Height in canvas pixels (0 allowed)"
},
"rotation": {
"type": "number",
"description": "Rotation in degrees"
},
"scaleX": {
"type": "number",
"description": "Horizontal scale multiplier (1 = 100%)"
},
"scaleY": {
"type": "number",
"description": "Vertical scale multiplier (1 = 100%)"
},
"rotateX": {
"type": "number",
"description": "rotateX (native unit)"
},
"rotateY": {
"type": "number",
"description": "rotateY (native unit)"
},
"opacity": {
"type": "number",
"minimum": 0,
"maximum": 100,
"description": "Opacity 0-100"
},
"blur": {
"type": "number",
"description": "Layer blur"
},
"backgroundBlur": {
"type": "number",
"description": "Backdrop blur behind the element"
},
"strokeWidth": {
"type": "number",
"description": "strokeWidth in canvas pixels"
},
"strokeDash": {
"type": "number",
"description": "strokeDash in canvas pixels"
},
"strokeGap": {
"type": "number",
"description": "strokeGap in canvas pixels"
},
"strokeTrimStart": {
"type": "number",
"description": "strokeTrimStart (native unit)"
},
"strokeTrimEnd": {
"type": "number",
"description": "strokeTrimEnd (native unit)"
},
"strokeTrimOffset": {
"type": "number",
"description": "strokeTrimOffset (native unit)"
},
"textStrokeWidth": {
"type": "number",
"description": "textStrokeWidth in canvas pixels"
},
"textStrokeDash": {
"type": "number",
"description": "textStrokeDash in canvas pixels"
},
"textStrokeGap": {
"type": "number",
"description": "textStrokeGap in canvas pixels"
},
"imageBorderWidth": {
"type": "number",
"description": "imageBorderWidth in canvas pixels"
},
"shadowOffsetX": {
"type": "number",
"description": "shadowOffsetX in canvas pixels"
},
"shadowOffsetY": {
"type": "number",
"description": "shadowOffsetY in canvas pixels"
},
"shadowBlur": {
"type": "number",
"description": "shadowBlur in canvas pixels"
},
"shadowSpread": {
"type": "number",
"description": "shadowSpread in canvas pixels"
},
"borderRadiusTopLeft": {
"type": "number",
"description": "borderRadiusTopLeft in canvas pixels"
},
"borderRadiusTopRight": {
"type": "number",
"description": "borderRadiusTopRight in canvas pixels"
},
"borderRadiusBottomRight": {
"type": "number",
"description": "borderRadiusBottomRight in canvas pixels"
},
"borderRadiusBottomLeft": {
"type": "number",
"description": "borderRadiusBottomLeft in canvas pixels"
},
"imageCornerRadiusTopLeft": {
"type": "number",
"description": "imageCornerRadiusTopLeft in canvas pixels"
},
"imageCornerRadiusTopRight": {
"type": "number",
"description": "imageCornerRadiusTopRight in canvas pixels"
},
"imageCornerRadiusBottomRight": {
"type": "number",
"description": "imageCornerRadiusBottomRight in canvas pixels"
},
"imageCornerRadiusBottomLeft": {
"type": "number",
"description": "imageCornerRadiusBottomLeft in canvas pixels"
},
"videoCornerRadiusTopLeft": {
"type": "number",
"description": "videoCornerRadiusTopLeft in canvas pixels"
},
"videoCornerRadiusTopRight": {
"type": "number",
"description": "videoCornerRadiusTopRight in canvas pixels"
},
"videoCornerRadiusBottomRight": {
"type": "number",
"description": "videoCornerRadiusBottomRight in canvas pixels"
},
"videoCornerRadiusBottomLeft": {
"type": "number",
"description": "videoCornerRadiusBottomLeft in canvas pixels"
},
"fontSize": {
"type": "number",
"description": "Font size in CANVAS PIXELS (same unit as the top-level fontSize — NOT a fraction)."
},
"lineHeight": {
"type": "number",
"description": "lineHeight (native unit)"
},
"letterSpacing": {
"type": "number",
"description": "Letter spacing in canvas pixels."
},
"paddingTop": {
"type": "number",
"description": "paddingTop in canvas pixels"
},
"paddingRight": {
"type": "number",
"description": "paddingRight in canvas pixels"
},
"paddingBottom": {
"type": "number",
"description": "paddingBottom in canvas pixels"
},
"paddingLeft": {
"type": "number",
"description": "paddingLeft in canvas pixels"
},
"textBgRadiusTopLeft": {
"type": "number",
"description": "textBgRadiusTopLeft in canvas pixels"
},
"textBgRadiusTopRight": {
"type": "number",
"description": "textBgRadiusTopRight in canvas pixels"
},
"textBgRadiusBottomRight": {
"type": "number",
"description": "textBgRadiusBottomRight in canvas pixels"
},
"textBgRadiusBottomLeft": {
"type": "number",
"description": "textBgRadiusBottomLeft in canvas pixels"
},
"strokeColor": {
"type": "string",
"pattern": "^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
"description": "strokeColor as #rrggbb or #rrggbbaa (alpha = opacity)"
},
"textStrokeColor": {
"$ref": "#/properties/elements/items/properties/keyframes/items/properties/strokeColor",
"description": "textStrokeColor as #rrggbb or #rrggbbaa (alpha = opacity)"
},
"imageBorderColor": {
"$ref": "#/properties/elements/items/properties/keyframes/items/properties/strokeColor",
"description": "imageBorderColor as #rrggbb or #rrggbbaa (alpha = opacity)"
},
"textColor": {
"$ref": "#/properties/elements/items/properties/keyframes/items/properties/strokeColor",
"description": "textColor as #rrggbb or #rrggbbaa (alpha = opacity)"
},
"textBackgroundColor": {
"$ref": "#/properties/elements/items/properties/keyframes/items/properties/strokeColor",
"description": "textBackgroundColor as #rrggbb or #rrggbbaa (alpha = opacity)"
},
"shadowColor": {
"$ref": "#/properties/elements/items/properties/keyframes/items/properties/strokeColor",
"description": "shadowColor as #rrggbb or #rrggbbaa (alpha = opacity)"
},
"interpolation": {
"type": "string",
"enum": [
"linear",
"easeInOut",
"easeIn",
"easeOut",
"sigmoid",
"smootherstep",
"smoothstep",
"hold",
"easeInBack",
"easeOutBack",
"easeInOutBack",
"custom"
],
"description": "Easing for THIS entry, applied to every property in it (default easeInOut). NOT `easing`."
},
"interpolation_overrides": {
"type": "object",
"additionalProperties": {
"$ref": "#/properties/elements/items/properties/keyframes/items/properties/interpolation"
},
"propertyNames": {
"enum": [
"positionX",
"positionY",
"width",
"height",
"rotation",
"scaleX",
"scaleY",
"rotateX",
"rotateY",
"opacity",
"blur",
"backgroundBlur",
"strokeWidth",
"strokeDash",
"strokeGap",
"strokeTrimStart",
"strokeTrimEnd",
"strokeTrimOffset",
"textStrokeWidth",
"textStrokeDash",
"textStrokeGap",
"imageBorderWidth",
"shadowOffsetX",
"shadowOffsetY",
"shadowBlur",
"shadowSpread",
"borderRadiusTopLeft",
"borderRadiusTopRight",
"borderRadiusBottomRight",
"borderRadiusBottomLeft",
"imageCornerRadiusTopLeft",
"imageCornerRadiusTopRight",
"imageCornerRadiusBottomRight",
"imageCornerRadiusBottomLeft",
"videoCornerRadiusTopLeft",
"videoCornerRadiusTopRight",
"videoCornerRadiusBottomRight",
"videoCornerRadiusBottomLeft",
"fontSize",
"lineHeight",
"letterSpacing",
"paddingTop",
"paddingRight",
"paddingBottom",
"paddingLeft",
"textBgRadiusTopLeft",
"textBgRadiusTopRight",
"textBgRadiusBottomRight",
"textBgRadiusBottomLeft",
"strokeColor",
"textStrokeColor",
"imageBorderColor",
"textColor",
"textBackgroundColor",
"shadowColor"
]
},
"description": "Per-property easing override, e.g. {\"opacity\":\"linear\"} while the rest use `interpolation`. Keys must be keyframable properties present in this entry."
},
"bezier": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 4,
"maxItems": 4,
"description": "Cubic-bezier [x1,y1,x2,y2]; used when interpolation is 'custom'."
},
"bezier_overrides": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 4,
"maxItems": 4
},
"propertyNames": {
"enum": [
"positionX",
"positionY",
"width",
"height",
"rotation",
"scaleX",
"scaleY",
"rotateX",
"rotateY",
"opacity",
"blur",
"backgroundBlur",
"strokeWidth",
"strokeDash",
"strokeGap",
"strokeTrimStart",
"strokeTrimEnd",
"strokeTrimOffset",
"textStrokeWidth",
"textStrokeDash",
"textStrokeGap",
"imageBorderWidth",
"shadowOffsetX",
"shadowOffsetY",
"shadowBlur",
"shadowSpread",
"borderRadiusTopLeft",
"borderRadiusTopRight",
"borderRadiusBottomRight",
"borderRadiusBottomLeft",
"imageCornerRadiusTopLeft",
"imageCornerRadiusTopRight",
"imageCornerRadiusBottomRight",
"imageCornerRadiusBottomLeft",
"videoCornerRadiusTopLeft",
"videoCornerRadiusTopRight",
"videoCornerRadiusBottomRight",
"videoCornerRadiusBottomLeft",
"fontSize",
"lineHeight",
"letterSpacing",
"paddingTop",
"paddingRight",
"paddingBottom",
"paddingLeft",
"textBgRadiusTopLeft",
"textBgRadiusTopRight",
"textBgRadiusBottomRight",
"textBgRadiusBottomLeft",
"strokeColor",
"textStrokeColor",
"imageBorderColor",
"textColor",
"textBackgroundColor",
"shadowColor"
]
},
"description": "Per-property cubic-bezier override, e.g. {\"opacity\":[.4,0,.6,1]}, when two `custom`-eased properties in this entry need DIFFERENT curves. Keys must be properties present in this entry."
}
},
"required": [
"timestamp"
],
"additionalProperties": false
},
"description": "Animation keyframes (≥2 entries). Each entry has a timestamp plus one or more keyframable properties (position/size in canvas pixels; rotation°, opacity 0-100, scale, colors as #rrggbb[aa], etc. in native units). Easing: per-entry `interpolation` + optional per-property `interpolation_overrides`. Call get_element_schema to see which properties this element_type can keyframe."
},
"clip_id": {
"type": "string",
"description": "Clip ID — accepted but unused; the clip is located by clip_index for all element types."
},
"type_data": {
"type": "object",
"additionalProperties": {},
"description": "Type-specific fields. Use the get_element_schema tool first to discover the shape for a given element_type. Omit when using component_id."
}
},
"required": [
"clip_index"
],
"additionalProperties": false
},
"minItems": 1,
"description": "Elements to add — at least one entry."
}
},
"required": [
"project_id",
"elements"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}