Clueso

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "kind",
    "project_id"
  ],
  "properties": {
    "kind": {
      "enum": [
        "image",
        "gif"
      ],
      "type": "string",
      "description": "'image' or 'gif'."
    },
    "duration": {
      "type": "number",
      "description": "kind='gif' only: GIF duration in seconds.",
      "exclusiveMinimum": 0
    },
    "timestamp": {
      "type": "number",
      "minimum": 0,
      "description": "kind='image': capture frame at this timestamp (seconds). kind='gif': GIF start time."
    },
    "project_id": {
      "type": "string",
      "description": "Project ID."
    },
    "source_url": {
      "type": "string",
      "format": "uri",
      "description": "kind='image' only: an https image URL to download and attach."
    },
    "mcp_upload_id": {
      "type": "string",
      "description": "kind='image' only: attach an uploaded image (mcp_upload_id from upload_file, or a Clueso upload_id) instead of capturing from video."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "project_id",
    "type"
  ],
  "properties": {
    "src": {
      "type": "string",
      "description": "Audio source. For type='music' (required) or a stock type='sfx': the `src` from a find(type='music'|'sfx') result (may be an opaque Freesound handle — pass as-is), or an upload id (mcp_upload_id 'mup_…' or a Clueso upload_id). Not needed for legacy fixed-library sfx (use sfx_key)."
    },
    "loop": {
      "type": "boolean",
      "description": "Loop the track if project is longer than the source. Music only. (default: false)"
    },
    "name": {
      "type": "string",
      "description": "Track/effect name. From the find result; for an upload it defaults to the file name."
    },
    "type": {
      "enum": [
        "music",
        "sfx"
      ],
      "type": "string",
      "description": "Audio type: 'music' or 'sfx'"
    },
    "volume": {
      "type": "number",
      "maximum": 100,
      "minimum": 0,
      "description": "Volume as percent (0–100). Default: 20 for music (under narration), 80 for sfx."
    },
    "fade_in": {
      "type": "number",
      "minimum": 0,
      "description": "Fade-in duration in seconds. Music only. (default: 0.5)"
    },
    "sfx_key": {
      "type": "string",
      "description": "LEGACY fixed-library SFX key (e.g. 'whoosh', 'pop', 'click'). Optional alternative to src for type='sfx'. Prefer the src/name/source_duration from a find(type='sfx') result."
    },
    "fade_out": {
      "type": "number",
      "minimum": 0,
      "description": "Fade-out duration in seconds. Music only. (default: 0.5)"
    },
    "project_id": {
      "type": "string",
      "description": "The project ID"
    },
    "guide_end_time": {
      "type": "number",
      "description": "When to stop playing (seconds). Music only. Default = end of project AT CALL TIME — captured once at insert and NOT recomputed when clips are later added or resized. Pass an explicit value (e.g. the intended final project duration) when adding audio before clips are sized.",
      "exclusiveMinimum": 0
    },
    "music_end_time": {
      "type": "number",
      "description": "Out-point within the SOURCE track (seconds) — trims where playback ends in the music file. Music only. Default = source_duration.",
      "exclusiveMinimum": 0
    },
    "source_duration": {
      "type": "number",
      "description": "Source duration in seconds, from the find result. Uploads and other URLs are probed.",
      "exclusiveMinimum": 0
    },
    "guide_start_time": {
      "type": "number",
      "minimum": 0,
      "description": "When to start playing in the guide timeline (seconds). Required for type='sfx', optional for music (default 0)."
    },
    "music_start_time": {
      "type": "number",
      "minimum": 0,
      "description": "In-point within the SOURCE track (seconds) — trims where playback begins in the music file. Music only. Default 0 (start of source)."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "kind",
    "project_id"
  ],
  "properties": {
    "cuts": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "end_seconds",
          "start_seconds"
        ],
        "properties": {
          "heading": {
            "type": "string",
            "description": "Optional clip title for this cut."
          },
          "end_seconds": {
            "type": "number",
            "description": "Cut end in original-source seconds (exclusive).",
            "exclusiveMinimum": 0
          },
          "start_seconds": {
            "type": "number",
            "minimum": 0,
            "description": "Cut start in original-source seconds (inclusive)."
          }
        }
      },
      "description": "kind='video' only: per-clip cuts. Each entry becomes one inserted clip. Omit to insert the full upload as a single clip."
    },
    "kind": {
      "enum": [
        "blank",
        "pptx",
        "video",
        "template"
      ],
      "type": "string",
      "description": "Source for the new clips: 'blank' | 'pptx' | 'video' | 'template'."
    },
    "clips": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "Clip title shown in the timeline."
          },
          "duration": {
            "type": "number",
            "description": "Clip length in seconds. Defaults to a short blank-clip duration.",
            "exclusiveMinimum": 0
          },
          "background": {
            "type": "object",
            "description": "Background set at creation: an object from find(type='backgrounds'), or { src, media_type?, padding?, border_radius?, shadow?, volume? } as in update_clips.",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {}
          },
          "transition": {
            "type": "object",
            "required": [
              "duration",
              "type"
            ],
            "properties": {
              "type": {
                "enum": [
                  "circleWipe",
                  "rainbowWipe",
                  "cornerWipe",
                  "stack",
                  "colorWipe",
                  "dissolve",
                  "pushPull",
                  "fadeToColor",
                  "flip"
                ],
                "type": "string",
                "description": "Transition style. NOTE: a clip's transition plays at the END of that clip, into the next one — to put a transition between clips 2 and 3, set it on clip 2."
              },
              "color": {
                "type": "string",
                "description": "Hex color, honoured by fadeToColor (default #000000), colorWipe (default #073cad), rainbowWipe (default #D43F8C) and flip (the backdrop behind the turning card, default #000000)."
              },
              "bezier": {
                "type": "array",
                "items": {
                  "type": "number"
                },
                "maxItems": 4,
                "minItems": 4,
                "description": "Custom easing of the transition, CSS cubic-bezier [x1, y1, x2, y2], e.g. [0.34, 1.56, 0.64, 1] for a slight bounce. Honoured by flip; omit for its default ease-in-out."
              },
              "duration": {
                "type": "number",
                "description": "Transition length in seconds.",
                "exclusiveMinimum": 0
              },
              "direction": {
                "type": "string",
                "description": "Direction, honoured only by some types: rainbowWipe and cornerWipe take topLeft/topRight/bottomLeft/bottomRight (default topRight); colorWipe takes left or right (default right); stack and pushPull take left/right/top/bottom (default right); flip takes horizontalLeft/horizontalCenter/horizontalRight/verticalTop/verticalCenter/verticalBottom (default horizontalCenter) — the axis it turns about (horizontal = left↔right, vertical = up↔down) and the line it turns on (an edge, or the middle for a card flip). Ignored by dissolve, circleWipe and fadeToColor."
              }
            },
            "description": "Transition at the END of this clip, into the next one."
          },
          "background_color": {
            "type": "string",
            "description": "Hex background set at creation, e.g. '#0B0E1A'."
          }
        }
      },
      "description": "kind='blank' only: one entry per blank clip. Optionally set background_color/background + transition per clip at creation — no follow-up update_clips needed."
    },
    "title": {
      "type": "string",
      "description": "kind='video' only: clip title (default 'Video')."
    },
    "mime_type": {
      "type": "string",
      "description": "kind='video' only: MIME type (default 'video/mp4'). Audio MIME types insert the file as a sequential clip with auto-TTS; for background music, use add_audio instead."
    },
    "project_id": {
      "type": "string",
      "description": "Project (guide) ID."
    },
    "template_id": {
      "type": "string",
      "description": "kind='template' only: template_id from find(type='clip_templates')."
    },
    "after_clip_id": {
      "type": "string",
      "description": "Insert after this clip ID; appends at end if omitted. kind='video': '' inserts at the front."
    },
    "auto_elements": {
      "type": "boolean",
      "description": "kind='video' only: when true, run auto-element detection (zooms, spotlights, blurs). Default false. Only meaningful on cache miss; cache hits clone the originating run's auto-elements."
    },
    "mcp_upload_id": {
      "type": "string",
      "description": "kind='pptx' or 'video': mcp_upload_id from upload_file, or a Clueso upload_id (or its S3 key)."
    },
    "slide_indices": {
      "type": "array",
      "items": {
        "type": "integer",
        "maximum": 9007199254740991,
        "minimum": 0
      },
      "description": "kind='pptx' only: 0-based slide indices to insert. Omit to insert all slides."
    },
    "text_overrides": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "kind='template' only: text for the template's text elements, in document order."
    },
    "voiceover_text": {
      "type": "string",
      "description": "kind='video' only: post-AI voiceover script (saved as v2). Original audio is always retained as the base transcript. Bracketed emotion tags ([excited], [whispers]) are performed, not spoken; <pause:1.5s> is exact timed silence."
    },
    "source_end_clip_id": {
      "type": "string",
      "description": "kind='video' re-cut: last clip of the run (inclusive)."
    },
    "source_start_clip_id": {
      "type": "string",
      "description": "kind='video' re-cut: first clip of the run to re-cut (inclusive)."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "comment_text",
    "project_id"
  ],
  "properties": {
    "clip_id": {
      "type": "string",
      "description": "Optional clip ID to pin the comment to. Omit for a project-level comment."
    },
    "project_id": {
      "type": "string",
      "description": "The project (guide) ID"
    },
    "comment_text": {
      "type": "string",
      "minLength": 1,
      "description": "Comment text to post"
    },
    "clip_timestamp": {
      "type": "number",
      "minimum": 0,
      "description": "Optional timestamp within the clip (seconds). Only used when clip_id is provided."
    },
    "parent_comment_id": {
      "type": "string",
      "description": "Reply to this comment instead of starting a new thread. Take the id from get_comments. Replying is how you answer feedback you have acted on — the clip pin and timestamp come from the parent, so leave clip_id/clip_timestamp off."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "elements",
    "project_id"
  ],
  "properties": {
    "defaults": {
      "type": "object",
      "properties": {
        "x": {
          "type": "number"
        },
        "y": {
          "type": "number"
        },
        "cues": {
          "type": "array",
          "items": {},
          "description": "Animation elements only: the same list as type_data.cues, accepted here too (send it in one place). E.g. update_elements({updates:[{element_id, cues:[{op:'set', key, t}]}]})."
        },
        "name": {
          "type": "string"
        },
        "group": {
          "type": "string",
          "minLength": 1
        },
        "width": {
          "type": "number",
          "minimum": 0
        },
        "height": {
          "type": "number",
          "minimum": 0
        },
        "actions": {
          "type": "array",
          "items": {},
          "description": "Animation elements only: the same list as type_data.actions, accepted here too (send it in one place)."
        },
        "clip_id": {
          "type": "string"
        },
        "end_time": {
          "type": "number",
          "minimum": 0
        },
        "rotation": {
          "type": "number"
        },
        "y_anchor": {
          "enum": [
            "top",
            "center",
            "bottom"
          ],
          "type": "string"
        },
        "insert_at": {
          "anyOf": [
            {
              "enum": [
                "front",
                "back"
              ],
              "type": "string"
            },
            {
              "type": "object",
              "required": [
                "before"
              ],
              "properties": {
                "before": {
                  "type": "string",
                  "minLength": 1
                }
              },
              "additionalProperties": false
            },
            {
              "type": "object",
              "required": [
                "after"
              ],
              "properties": {
                "after": {
                  "type": "string",
                  "minLength": 1
                }
              },
              "additionalProperties": false
            },
            {
              "type": "string",
              "pattern": "^(before|after):.+$"
            }
          ]
        },
        "keyframes": {
          "anyOf": [
            {
              "type": "array",
              "items": {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {}
              }
            },
            {
              "type": "null"
            }
          ],
          "description": "Same entries as an item's keyframes."
        },
        "type_data": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        },
        "clip_index": {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": 0
        },
        "start_time": {
          "type": "number",
          "minimum": 0
        },
        "paramTracks": {
          "type": "array",
          "items": {},
          "description": "Same as param_tracks."
        },
        "element_type": {
          "enum": [
            "text",
            "callout",
            "rectangle",
            "arrow",
            "blur",
            "spotlight",
            "zoom",
            "image",
            "video",
            "animation",
            "avatar"
          ],
          "type": "string"
        },
        "param_tracks": {
          "type": "array",
          "items": {},
          "description": "Animation elements only: the same list as type_data.param_tracks, accepted here too (send it in one place)."
        },
        "keyframes_repeat": {
          "type": "object",
          "description": "Same as an item's keyframes_repeat.",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        }
      },
      "description": "Values shared by every item, sent once rather than repeated. Items win per key; type_data merges one level. E.g. defaults:{clip_index:1, element_type:'text', type_data:{font_setting:{font:'Inter',weight:'600'}, alignment:'center'}} then items carry only what differs.",
      "additionalProperties": false
    },
    "elements": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "x": {
            "type": "number",
            "description": "X position in canvas pixels. `x` is the left edge, except TEXT where alignment picks it: left→left, center→centre, right→right (callout, rectangle, arrow, blur, spotlight, image and animation all use the left edge). For zoom, use type_data.centerX instead."
          },
          "y": {
            "type": "number",
            "description": "Y position in canvas pixels — for TEXT `y` is the vertical CENTRE when centre-aligned and the TOP otherwise; every other type uses the top. Pair it with y_anchor (below), always."
          },
          "cues": {
            "type": "array",
            "items": {},
            "description": "Animation elements only: the same list as type_data.cues, accepted here too (send it in one place). E.g. update_elements({updates:[{element_id, cues:[{op:'set', key, t}]}]})."
          },
          "name": {
            "type": "string",
            "description": "Label"
          },
          "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 generated from a `prompt` and AI-generated images are made in the background and cannot be grouped as they are added; add them first, then set `group` via update_elements. A placed animation (`animation` + `entry`, or `code`) takes `group` and `insert_at` here like any element, and lands below later items of the same call."
          },
          "width": {
            "type": "number",
            "minimum": 0,
            "description": "Width, pixels (0 allowed — e.g. a bar that draws in from 0). For text this is the WRAP width and it is kept as sent: the text wraps to it and the box stays this wide. (Height differs — the box's height follows the measured text.)"
          },
          "height": {
            "type": "number",
            "minimum": 0,
            "description": "Height, pixels (0 allowed). For text the box's height always follows the measured text, so this reads as the space you are giving it: the text is centred in that space and layout.fits_height says whether it fit. Use type_data.fit to shrink the font into it."
          },
          "actions": {
            "type": "array",
            "items": {},
            "description": "Animation elements only: the same list as type_data.actions, accepted here too (send it in one place)."
          },
          "clip_id": {
            "type": "string",
            "description": "Clip ID — accepted but unused; the clip is located by clip_index for all element types."
          },
          "end_time": {
            "type": "number",
            "minimum": 0,
            "description": "Disappear at (seconds)"
          },
          "rotation": {
            "type": "number",
            "description": "Rotation in degrees"
          },
          "y_anchor": {
            "enum": [
              "top",
              "center",
              "bottom"
            ],
            "type": "string",
            "description": "TEXT only. ALWAYS send `y_anchor` ('top'|'center'|'bottom') when you set `y` on text, so the position states what you meant instead of inheriting the alignment origin. To centre in a row, pill, chip, card or button: pass the container's centre line as `y` with y_anchor:'center'. The server centres the MEASURED box — you cannot compute that height, since wrapping and `fit` change it. A write-time DIRECTIVE: never stored, never returned by a read, so send it on every call whose `y` means the same thing. (Also accepted inside type_data — older spelling; this one wins.)"
          },
          "insert_at": {
            "anyOf": [
              {
                "enum": [
                  "front",
                  "back"
                ],
                "type": "string"
              },
              {
                "type": "object",
                "required": [
                  "before"
                ],
                "properties": {
                  "before": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "additionalProperties": false
              },
              {
                "type": "object",
                "required": [
                  "after"
                ],
                "properties": {
                  "after": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "additionalProperties": false
              },
              {
                "type": "string",
                "pattern": "^(before|after):.+$"
              }
            ],
            "description": "Where the element lands in z-order, so you don't need a follow-up reorder_elements. `front` (default) puts it on top of what's already on the clip; `back` puts it behind everything — what a backdrop panel or a wash needs. `{before: element_id}` / `{after: element_id}` place it next to a specific element or group and put it in THAT node's group, which is the only way to position inside a group. Passing `group` as well changes what `front`/`back` address — see the Z-order notes in this tool's description. Placement is relative to the clip AS IT STANDS when the item is applied, so several `back` items in one call end up in REVERSE input order: send one backdrop per call, or list them back-to-front."
          },
          "keyframes": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "timestamp"
                  ],
                  "properties": {
                    "blur": {
                      "type": "number",
                      "description": "Layer blur"
                    },
                    "cropX": {
                      "type": "number",
                      "description": "cropX (native unit)"
                    },
                    "cropY": {
                      "type": "number",
                      "description": "cropY (native unit)"
                    },
                    "width": {
                      "type": "number",
                      "minimum": 0,
                      "description": "Width in canvas pixels (0 allowed — e.g. a bar that draws in from 0)"
                    },
                    "bezier": {
                      "type": "array",
                      "items": {
                        "type": "number"
                      },
                      "maxItems": 4,
                      "minItems": 4,
                      "description": "Cubic-bezier [x1,y1,x2,y2]; used when interpolation is 'custom'."
                    },
                    "height": {
                      "type": "number",
                      "minimum": 0,
                      "description": "Height in canvas pixels (0 al
… [server-provided details truncated]

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "project_id",
    "timestamp_seconds",
    "word"
  ],
  "properties": {
    "word": {
      "type": "string",
      "minLength": 1,
      "description": "Target word (case-insensitive; trailing punctuation is stripped)."
    },
    "clip_id": {
      "type": "string",
      "description": "Clip ID (preferred). If omitted, clip_index is used."
    },
    "clip_index": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Zero-based clip index. Ignored if clip_id is provided."
    },
    "occurrence": {
      "type": "integer",
      "default": 1,
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "1-indexed match number when the word repeats. Defaults to 1 (first occurrence)."
    },
    "project_id": {
      "type": "string",
      "description": "Project ID."
    },
    "sync_point_name": {
      "type": "string",
      "description": "Optional label (e.g. 'Click submit'). Defaults to 'Sync point N' using the next order number."
    },
    "timestamp_seconds": {
      "type": "number",
      "minimum": 0,
      "description": "Clip-relative timestamp in seconds. Auto-mapped to original-recording seconds when the clip has generated_timestamps."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "mode"
  ],
  "properties": {
    "mode": {
      "enum": [
        "transcript",
        "silences",
        "beats",
        "features",
        "energy",
        "sections",
        "describe"
      ],
      "type": "string",
      "description": "Which analysis to run."
    },
    "file_url": {
      "type": "string",
      "description": "Public http(s) URL to the audio. Use when the file is already accessible (e.g. find(type='music') result, Clueso CDN). Validated against private/loopback ranges."
    },
    "range_end_ms": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "End of analysis window in milliseconds. Default: whole file."
    },
    "mcp_upload_id": {
      "type": "string",
      "description": "mcp_upload_id from upload_file, or a Clueso upload_id. Use this OR file_url, not both."
    },
    "energy_options": {
      "type": "object",
      "properties": {
        "samples_per_second": {
          "type": "number",
          "maximum": 20,
          "minimum": 1,
          "description": "Loudness values per second. Default 4."
        }
      },
      "description": "Options for mode='energy'."
    },
    "range_start_ms": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Start of analysis window in milliseconds. Default 0 (beginning)."
    },
    "silences_options": {
      "type": "object",
      "properties": {
        "min_pause_ms": {
          "type": "integer",
          "maximum": 9007199254740991,
          "description": "Minimum pause length to report. Default 250ms.",
          "exclusiveMinimum": 0
        },
        "threshold_db": {
          "type": "number",
          "description": "Silence threshold in dBFS. Default -40."
        }
      },
      "description": "Options for mode='silences'."
    },
    "transcript_options": {
      "type": "object",
      "properties": {
        "language": {
          "type": "string",
          "description": "Language code hint (e.g. 'en', 'es'). Auto-detected if omitted."
        }
      },
      "description": "Options for mode='transcript'."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "clip_id",
    "project_id"
  ],
  "properties": {
    "clip_id": {
      "type": "string",
      "description": "Clip ID to auto-sync."
    },
    "project_id": {
      "type": "string",
      "description": "Project ID."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "action",
    "project_id"
  ],
  "properties": {
    "text": {
      "type": "string",
      "description": "edit / manual_add / manual_edit — the caption text."
    },
    "action": {
      "enum": [
        "list",
        "edit",
        "reset",
        "split",
        "merge",
        "timing",
        "timing_reset",
        "manual_add",
        "manual_edit",
        "manual_remove",
        "translate",
        "language"
      ],
      "type": "string",
      "description": "What to do — see the tool description"
    },
    "end_time": {
      "type": "number",
      "minimum": 0,
      "description": "timing / manual_add / manual_edit — seconds from the start of the clip."
    },
    "language": {
      "type": "string",
      "description": "translate — language id (\"fr\") or name (\"French\"). language — a translated id, or \"original\"."
    },
    "caption_id": {
      "type": "string",
      "description": "manual_edit / manual_remove — from list's manual_captions."
    },
    "clip_index": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "The clip. Required for every action except translate/language, where omitting it means every clip."
    },
    "project_id": {
      "type": "string",
      "description": "The project ID"
    },
    "start_time": {
      "type": "number",
      "minimum": 0,
      "description": "timing / manual_add / manual_edit — seconds from the start of the clip."
    },
    "split_word_index": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "split — the word that starts the new second caption."
    },
    "start_word_index": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "edit/reset/split/merge/timing/timing_reset — the caption, exactly as list returned it."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "upload_token"
  ],
  "properties": {
    "upload_token": {
      "type": "string",
      "description": "The upload_token returned by upload_file(request_hosted_upload: true)"
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "name",
    "visibility"
  ],
  "properties": {
    "name": {
      "type": "string",
      "description": "Name of the clueprint"
    },
    "visibility": {
      "enum": [
        "private",
        "workspace"
      ],
      "type": "string",
      "description": "'workspace' shares it with your workspace; 'private' is stored as 'workspace'."
    },
    "description": {
      "type": "string",
      "description": "Description of what this clueprint does"
    },
    "brand_locked": {
      "type": "boolean",
      "description": "true: projects in this workspace built from this clueprint keep its own colors, fonts and logos instead of their brand kit's. Default false (re-skinned to the project's kit)."
    },
    "source_guide_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "IDs of existing projects to extract template data from"
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1,
      "description": "Folder name"
    },
    "description": {
      "type": "string",
      "maxLength": 500,
      "description": "Optional folder description"
    },
    "parent_folder_id": {
      "type": "string",
      "description": "Create the folder inside this folder (use find(type='folders') for IDs). Omit for the workspace root."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "audio": {
      "type": "string",
      "description": "An audio upload (an mcp_upload_id or a Clueso upload_id) to use as the voiceover (original narration, transcribed). Not with `script`."
    },
    "title": {
      "type": "string",
      "description": "Project title"
    },
    "script": {
      "type": "string",
      "description": "Voiceover script; one blank clip per paragraph. Not with `audio`."
    },
    "folder_id": {
      "type": "string",
      "description": "Optional folder ID to nest the project under. Use find(type='folders') to discover IDs. Omit to create at workspace root."
    },
    "description": {
      "type": "string",
      "description": "Optional project description (max ~500 chars)"
    },
    "brand_kit_id": {
      "type": "string",
      "description": "Brand kit for this project: an id from find(type='brand_kits'), or 'default' (the same as omitting it: follow the workspace default kit, including when the default changes). Setting a kit needs an editor or admin."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "source_clip_id",
    "target_project_id"
  ],
  "properties": {
    "after_clip_id": {
      "type": "string",
      "description": "Insert after this clip ID in the target. Appends at end if omitted."
    },
    "source_clip_id": {
      "type": "string",
      "description": "ID of the clip to duplicate."
    },
    "source_project_id": {
      "type": "string",
      "description": "Cross-project mode: ID of the project the source clip lives in. Omit for same-project duplication."
    },
    "target_project_id": {
      "type": "string",
      "description": "Project (guide) ID to insert the duplicate into."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "source_project_id"
  ],
  "properties": {
    "folder_id": {
      "type": "string",
      "description": "Place the duplicate in this folder. Omit to keep the same folder as the source. Pass '' (empty string) to move to workspace root."
    },
    "new_title": {
      "type": "string",
      "description": "Override the title of the duplicate."
    },
    "source_project_id": {
      "type": "string",
      "description": "Project (guide) ID to duplicate."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "name": {
      "type": "string",
      "description": "Only with animation 'new': the display name."
    },
    "slug": {
      "type": "string",
      "description": "Only with animation 'new': lowercase letters, digits and dashes; becomes @org/<slug>. Slugs are workspace-wide: one an animation of another project (or the library) holds is saved as the next free <slug>-N (the reply's animation and note say which, nothing to resend); one this project already holds is refused, naming it and a free slug."
    },
    "edits": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "op",
          "path"
        ],
        "properties": {
          "op": {
            "enum": [
              "replace",
              "write",
              "delete",
              "move"
            ],
            "type": "string",
            "description": "replace: exact-match `old` → `new` in `path` (fails unless `old` occurs exactly once, or pass all: true). write: create or overwrite `path` with `content`. delete: remove `path`. move: rename `path` to `to`."
          },
          "to": {
            "type": "string",
            "description": "move: the new path."
          },
          "all": {
            "type": "boolean",
            "description": "replace: replace every occurrence instead of requiring one."
          },
          "new": {
            "type": "string",
            "description": "replace: the text to put in its place."
          },
          "old": {
            "type": "string",
            "description": "replace: the exact text to find, copied from read_animation."
          },
          "path": {
            "type": "string",
            "minLength": 1,
            "description": "File path inside the animation, e.g. 'entries/maya.js'."
          },
          "content": {
            "type": "string",
            "description": "write: the whole file."
          }
        }
      },
      "maxItems": 100,
      "minItems": 1,
      "description": "Operations, applied in order before `files`: delete and move (replace and write also work; files is the shorter way)."
    },
    "files": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "path"
        ],
        "properties": {
          "path": {
            "type": "string",
            "minLength": 1,
            "description": "File path inside the animation, e.g. 'entries/maya.js'."
          },
          "edits": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "new",
                "old"
              ],
              "properties": {
                "new": {
                  "type": "string",
                  "description": "The text to put in its place."
                },
                "old": {
                  "type": "string",
                  "minLength": 1,
                  "description": "The exact text to find, copied from read_animation without the 'N| ' line numbers. Must occur exactly once unless replace_all."
                },
                "replace_all": {
                  "type": "boolean",
                  "description": "Replace every occurrence instead of requiring exactly one."
                }
              }
            },
            "maxItems": 100,
            "minItems": 1,
            "description": "Search-and-replace edits for an existing file, applied in order (each sees the text the one before left). Prefer these over content for changes to existing files."
          },
          "patch": {
            "type": "string",
            "description": "A unified diff of this one file ('@@ -a,b +c,d @@' hunks). Context and removed lines must match exactly; a hunk may sit at other line numbers."
          },
          "content": {
            "type": "string",
            "description": "The whole file: a new file, or a full rewrite."
          },
          "upload_id": {
            "type": "string",
            "pattern": "^mup_",
            "description": "The mcp_upload_id (mup_…) of a text file sent with upload_file (file_name + its curl), used as the whole content, so a big file never goes inline. UTF-8 text, at most 256 KB."
          }
        }
      },
      "maxItems": 100,
      "minItems": 1,
      "description": "Per-file changes, each with exactly one of edits, content, patch or upload_id. Applied in order after `edits` and `patch`, all saved as ONE revision."
    },
    "patch": {
      "type": "string",
      "minLength": 1,
      "description": "For a client working from files on disk: a unified diff of any number of files against the saved revision (`git diff`, `diff -u` or `diff -ruN`), run from the folder holding manifest.json. The server holds the base. New files (--- /dev/null), deletes and renames apply too. A hunk whose context no longer matches is refused with the saved lines around it; nothing is saved."
    },
    "place": {
      "type": "object",
      "properties": {
        "x": {
          "type": "number",
          "description": "Left edge, canvas pixels (default: centred)."
        },
        "y": {
          "type": "number",
          "description": "Top edge, canvas pixels (default: centred)."
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "description": "The element's label."
        },
        "entry": {
          "type": "string",
          "minLength": 1,
          "description": "Which entry to place (default: the only one, else 'main', else the first). Any entry not yet on that clip is placed, also of an animation already on the canvas."
        },
        "width": {
          "type": "number",
          "description": "Box width, canvas pixels (default: the full canvas).",
          "exclusiveMinimum": 0
        },
        "height": {
          "type": "number",
          "description": "Box height, canvas pixels (default: the full canvas).",
          "exclusiveMinimum": 0
        },
        "end_time": {
          "type": "number",
          "description": "Seconds from the clip's start (default: the clip's end).",
          "exclusiveMinimum": 0
        },
        "clip_index": {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": 0,
          "description": "Zero-based clip the animation belongs to. With continue_from: the clip it continues into (default the next)."
        },
        "start_time": {
          "type": "number",
          "minimum": 0,
          "description": "Seconds from the clip's start (default 0)."
        },
        "continue_from": {
          "type": "string",
          "minLength": 1,
          "description": "An animation element on an earlier clip that this one carries on from across the cut: placed in its box. The same animation, or a fork of it, picks up at the second it reached (timing 'trim'); any other starts at its own 0 with its own settings."
        }
      },
      "description": "Put the animation on the canvas on the first passing save, as an animation element on this clip (the add_elements placement), and return its element_id: pass that on every later edit so each passing save updates the editor live. Needs project_id. Placing is per entry and clip: an entry already on that clip is not placed again (its element_id comes back); any other entry, or the same entry on another clip, is, and existing elements keep their own entries. Works for an existing animation too (animation: '@org/<slug>', or element_id + place.entry for another entry of the element's animation), and with no file changes at all it only places the latest revision. A failing save places nothing.",
      "additionalProperties": false
    },
    "scope": {
      "enum": [
        "element",
        "project",
        "library"
      ],
      "type": "string",
      "description": "Only with animation 'new': one element, this project (the default with project_id; every scene of the video can import it), or the workspace library, only when the user asks to reuse it in other videos."
    },
    "detail": {
      "enum": [
        "summary",
        "full"
      ],
      "type": "string",
      "description": "summary (default) returns the outcome and what changed; full adds the diff hunks and every probe thumbnail."
    },
    "folder": {
      "type": "string",
      "description": "Only with animation 'new' and scope 'library' (a save the user asked to keep for the workspace): the library folder, by path, e.g. 'Characters' or 'Characters/Presenters'. Missing folders are created (at most three levels)."
    },
    "target": {
      "enum": [
        "shared",
        "fork"
      ],
      "type": "string",
      "description": "Required when the animation is used outside this project: 'shared' changes it for everyone who updates, 'fork' copies it for this project first. Official and community animations always fork."
    },
    "dry_run": {
      "type": "boolean",
      "description": "Build and check the edits without saving. Returns a `preview` token; render it with get_clip(render: {preview})."
    },
    "preview": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "object",
          "properties": {
            "cues": {
              "type": "object",
              "description": "Cue times to try, key: seconds (element-local).",
              "propertyNames": {
                "type": "string"
              },
              "additionalProperties": {
                "type": "number"
              }
            },
            "entry": {
              "type": "string",
              "minLength": 1,
              "description": "Which entry to show (default: the element's, or the animation's first)."
            },
            "video": {
              "type": "boolean",
              "description": "For people: also a short low-resolution MP4 of the same window (the filmstrip's, or the animation's first 10 s), returned as video_url, a link valid for an hour. You can't watch it: judge motion from the filmstrip."
            },
            "actions": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "name",
                  "start"
                ],
                "properties": {
                  "args": {
                    "type": "object",
                    "propertyNames": {
                      "type": "string"
                    },
                    "additionalProperties": {}
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1
                  },
                  "start": {
                    "type": "number"
                  },
                  "duration": {
                    "type": "number"
                  }
                }
              },
              "description": "Action clips to try, [{name, start, duration?, args?}], element-local seconds; duration defaults to the action's default_duration. Replaces the element's clips for this render."
            },
            "duration": {
              "type": "number",
              "description": "How long the entry plays in the preview, in seconds.",
              "exclusiveMinimum": 0
            },
            "filmstrip": {
              "anyOf": [
                {
                  "type": "boolean",
                  "const": true
                },
                {
                  "type": "object",
                  "properties": {
                    "to": {
                      "type": "number",
                      "description": "Window end, element-local seconds, or clip seconds for a whole clip (default the end).",
                      "exclusiveMinimum": 0
    
… [server-provided details truncated]

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "project_id"
  ],
  "properties": {
    "fps": {
      "anyOf": [
        {
          "type": "number",
          "const": 24
        },
        {
          "type": "number",
          "const": 30
        },
        {
          "type": "number",
          "const": 60
        }
      ],
      "description": "Frames per second (default 30)"
    },
    "format": {
      "enum": [
        "mp4",
        "mp3"
      ],
      "type": "string",
      "description": "\"mp4\" (video, default) or \"mp3\" (the voiceover alone; download only)"
    },
    "captions": {
      "type": "boolean",
      "description": "Burn subtitles into the video (default false)"
    },
    "language": {
      "type": "string",
      "minLength": 2,
      "description": "Language code of the voiceover and captions to render, e.g. 'de' for a translated project (default 'en'). Downloads only."
    },
    "project_id": {
      "type": "string",
      "description": "The project ID to export"
    },
    "resolution": {
      "enum": [
        "720p",
        "1080p",
        "2k",
        "4k"
      ],
      "type": "string",
      "description": "Output resolution (default 1080p)"
    },
    "destination": {
      "enum": [
        "download",
        "embed"
      ],
      "type": "string",
      "description": "Where the render goes: \"download\" (mp4 file, default) or \"embed\" (publish/update the project's embeddable player; its URL never changes). Publishing an embed needs an editor or admin role."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "project_id"
  ],
  "properties": {
    "clip_id": {
      "type": "string",
      "description": "Clip ID (preferred over clip_index)."
    },
    "restore": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "enum": [
            "0",
            "1",
            "true",
            "false",
            "yes",
            "no"
          ],
          "type": "string"
        }
      ],
      "description": "true = undo: the clip plays its own audio again at 100%."
    },
    "clip_index": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Zero-based clip index. Ignored if clip_id is provided."
    },
    "project_id": {
      "type": "string",
      "description": "The project ID"
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "type"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Exact id — returns just that record."
    },
    "mood": {
      "type": "array",
      "items": {
        "enum": [
          "uplifting",
          "hopeful",
          "happy",
          "playful",
          "quirky",
          "confident",
          "inspiring",
          "epic",
          "energetic",
          "laid-back",
          "calm",
          "dreamy",
          "warm",
          "sentimental",
          "focused",
          "serious",
          "mysterious",
          "suspenseful",
          "dark",
          "sad"
        ],
        "type": "string"
      },
      "maxItems": 3,
      "description": "music/sfx: moods to rank first."
    },
    "page": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "Page (default 1) — projects/element_components/clueprints/animations."
    },
    "size": {
      "enum": [
        "large",
        "medium",
        "small"
      ],
      "type": "string",
      "description": "stock videos only: minimum resolution bucket."
    },
    "tags": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 40,
            "minLength": 1
          },
          "maxItems": 50
        },
        {
          "type": "string"
        }
      ],
      "description": "voices: descriptive words (a list or comma-separated), any one matches. projects: tag names; keeps projects carrying them (see tag_match)."
    },
    "tier": {
      "enum": [
        "org",
        "official",
        "community"
      ],
      "type": "string",
      "description": "animations only: 'org' (this workspace), 'official' (Clueso's) or 'community'. Default all three."
    },
    "type": {
      "enum": [
        "projects",
        "folders",
        "tags",
        "clueprints",
        "workspaces",
        "backgrounds",
        "voices",
        "fonts",
        "brand_kits",
        "icons",
        "image_gen_style_packs",
        "code_style_packs",
        "element_components",
        "animations",
        "avatars",
        "images",
        "videos",
        "music",
        "sfx",
        "clip_templates"
      ],
      "type": "string",
      "description": "Resource type to find."
    },
    "avoid": {
      "type": "array",
      "items": {
        "enum": [
          "uplifting",
          "hopeful",
          "happy",
          "playful",
          "quirky",
          "confident",
          "inspiring",
          "epic",
          "energetic",
          "laid-back",
          "calm",
          "dreamy",
          "warm",
          "sentimental",
          "focused",
          "serious",
          "mysterious",
          "suspenseful",
          "dark",
          "sad",
          "corporate",
          "electronic",
          "pop",
          "rock",
          "indie",
          "hip-hop",
          "lo-fi",
          "house",
          "funk",
          "rnb",
          "jazz",
          "acoustic-folk",
          "ambient",
          "cinematic",
          "classical",
          "world"
        ],
        "type": "string"
      },
      "maxItems": 6,
      "description": "music/sfx: moods or genres to exclude."
    },
    "color": {
      "type": "string",
      "description": "stock images only: color name or hex, e.g. 'blue'."
    },
    "genre": {
      "type": "array",
      "items": {
        "enum": [
          "corporate",
          "electronic",
          "pop",
          "rock",
          "indie",
          "hip-hop",
          "lo-fi",
          "house",
          "funk",
          "rnb",
          "jazz",
          "acoustic-folk",
          "ambient",
          "cinematic",
          "classical",
          "world"
        ],
        "type": "string"
      },
      "maxItems": 3,
      "description": "music: genres to rank first."
    },
    "limit": {
      "type": "integer",
      "maximum": 100,
      "minimum": 1,
      "description": "Page size, and a cap on every type, stock media included (default 8 for voices, music and sfx, every font for fonts, 50 otherwise; a '_more' item or a note says when more exist)."
    },
    "query": {
      "type": "string",
      "description": "Case-insensitive substring match on name."
    },
    "detail": {
      "enum": [
        "compact",
        "full"
      ],
      "type": "string",
      "description": "animations, voices, music, sfx, fonts, brand_kits, icons: 'compact' (default) — the essentials to choose and use one (animations: ref, title, entry names, scope, tier, rev; voices: id, name, gender, accent, engine, tags, a short description; music/sfx: id, name, src, duration, bpm, tags, a short description; fonts: id, name; brand_kits: id, name, is_default, accent, title_font, logo_count, icon_library; icons: names); 'full' — every field (preview urls, thumbnails, attribution, rhythm, full descriptions; for animations entry parts, uses, dependency_updates; for brand_kits every section of the kit; for icons each one's src)."
    },
    "energy": {
      "type": "integer",
      "maximum": 5,
      "minimum": 1,
      "description": "music: 1 still, 2 gentle, 3 steady, 4 driving, 5 intense; ranks."
    },
    "engine": {
      "type": "string",
      "description": "voices only: 'eleven' | 'cartesia' | 'google'."
    },
    "source": {
      "enum": [
        "org",
        "stock",
        "all",
        "defaults",
        "library"
      ],
      "type": "string",
      "description": "media types (images/videos/music/sfx) only: where to search — 'org' (your saved workspace media), 'stock' (stock library — images/videos via Pexels, music from Clueso's catalog), 'all' (both; default). sfx is stock-only. clip_templates: 'defaults' | 'org' | 'library' | 'all'."
    },
    "vocals": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "enum": [
            "0",
            "1",
            "true",
            "false",
            "yes",
            "no"
          ],
          "type": "string"
        }
      ],
      "description": "music: false = instrumental only, true = with vocals."
    },
    "bpm_max": {
      "type": "integer",
      "maximum": 400,
      "minimum": 1,
      "description": "music: tempo ceiling."
    },
    "bpm_min": {
      "type": "integer",
      "maximum": 400,
      "minimum": 1,
      "description": "music: tempo floor."
    },
    "library": {
      "type": "string",
      "description": "icons only: an icon set id ('lucide', 'ph', 'tabler', ...) other than the kit's. One set per video, so only for a video using no other."
    },
    "language": {
      "type": "string",
      "description": "voices only: e.g. 'en'."
    },
    "provider": {
      "enum": [
        "pexels",
        "pixabay",
        "clueso",
        "freesound"
      ],
      "type": "string",
      "description": "stock media: which library to search (exactly one). images/videos: 'pexels' (default — polished real-world photos & footage) | 'pixabay' (illustrations, vectors, clip-art, icons + more variety; pair with image_type/video_type). music/sfx: 'clueso' (default for music — our curated, brand-safe, well-described library, best semantic search) | 'freesound' (huge community library; best for niche music and sound effects — default for sfx). Offering the user music/sfx options → one call per library, both."
    },
    "sfx_type": {
      "enum": [
        "whoosh",
        "riser",
        "impact",
        "sub-drop",
        "click",
        "pop",
        "typing",
        "swipe",
        "notification",
        "success",
        "error",
        "glitch",
        "shimmer",
        "camera-shutter",
        "ambience"
      ],
      "type": "string",
      "description": "sfx: the kind of effect."
    },
    "folder_id": {
      "type": "string",
      "description": "projects/images/videos/music/clip_templates only: restrict to a folder."
    },
    "mine_only": {
      "type": "boolean",
      "description": "clueprints only: only ones I created."
    },
    "tag_match": {
      "enum": [
        "any",
        "all"
      ],
      "type": "string",
      "description": "projects only, with tags: 'any' (default) = at least one of the tags, 'all' = every one of them."
    },
    "clip_label": {
      "enum": [
        "intro",
        "outro",
        "chapter break",
        "others"
      ],
      "type": "string",
      "description": "clip_templates only: one kind of cover."
    },
    "creator_id": {
      "type": "string",
      "description": "clueprints only: filter by creator id."
    },
    "image_type": {
      "enum": [
        "photo",
        "illustration",
        "vector"
      ],
      "type": "string",
      "description": "stock images + provider='pixabay' only: 'photo' | 'illustration' | 'vector' (flat/drawn graphics, icons, clip-art). Use illustration/vector for graphic looks; photo (or Pexels) for realism."
    },
    "project_id": {
      "type": "string",
      "description": "animations: also list the animations saved to this project (they are hidden everywhere else). icons: search this project's brand kit's icon set."
    },
    "similar_to": {
      "type": "string",
      "description": "music/sfx: an earlier result's id (a Freesound src also works); returns sounds like it. No other filters with it."
    },
    "video_type": {
      "enum": [
        "film",
        "animation"
      ],
      "type": "string",
      "description": "stock videos + provider='pixabay' only: 'film' (live footage) | 'animation' (motion graphics)."
    },
    "orientation": {
      "enum": [
        "landscape",
        "portrait",
        "square"
      ],
      "type": "string",
      "description": "stock images/videos only: result orientation."
    },
    "brand_kit_id": {
      "type": "string",
      "description": "icons only: search this brand kit's icon set (an id from find(type='brand_kits')) instead of the project's."
    },
    "max_duration": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "stock videos + freesound audio: maximum clip length in seconds."
    },
    "min_duration": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "stock videos only: minimum clip length in seconds."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "clip_id",
    "height",
    "kind",
    "project_id",
    "prompt",
    "width",
    "x",
    "y"
  ],
  "properties": {
    "x": {
      "type": "number",
      "description": "Top-left X in canvas pixels."
    },
    "y": {
      "type": "number",
      "description": "Top-left Y in canvas pixels."
    },
    "kind": {
      "enum": [
        "image",
        "animation"
      ],
      "type": "string",
      "description": "'image' = AI text-to-image; 'animation' = canvas-code-based motion graphic."
    },
    "model": {
      "enum": [
        "gemini-3-pro-image",
        "gemini-3.1-flash-image",
        "gemini-nano-banana-2.1",
        "gemini-3.1-flash-lite-image",
        "gemini-2.5-flash-image",
        "gpt-image-2.5-flare",
        "gpt-image-2.5-sunburst",
        "gpt-image-2",
        "gpt-image-1.5",
        "gpt-image-1"
      ],
      "type": "string",
      "description": "Image only. Which image model renders it. Default `gemini-3-pro-image` (Nano Banana Pro), a strong general choice — leave it off unless you want one of the specifics below. `gemini-3.1-flash-image` (Nano Banana 2), `gemini-nano-banana-2.1` (Nano Banana 2.1, Google's newest), `gemini-3.1-flash-lite-image` (Nano Banana 2 Lite, the fastest and cheapest) and `gemini-2.5-flash-image` are faster and cheaper. `gpt-image-2.5-flare` is OpenAI's fast one, `gpt-image-2.5-sunburst` its most precise editor, and `gpt-image-2` is the one to reach for when the image must carry legible text or follow several reference images. `gpt-image-1` / `gpt-image-1.5` are the older pair and only accept square-ish framing — a wide box is snapped to 4:3 rather than honoured, so do not pick them for a banner. An unlisted value is rejected here rather than silently swapped for the default, which is what the backend does with one."
    },
    "width": {
      "type": "number",
      "description": "Width in pixels.",
      "exclusiveMinimum": 0
    },
    "height": {
      "type": "number",
      "description": "Height in pixels.",
      "exclusiveMinimum": 0
    },
    "prompt": {
      "type": "string",
      "minLength": 1,
      "description": "Generation prompt. For animations, be SPECIFIC: name the UI elements, interaction sequence, timing feel, and visual style. Vague prompts produce bad output."
    },
    "clip_id": {
      "type": "string",
      "description": "Clip ID to place the generated element into."
    },
    "end_time": {
      "type": "number",
      "minimum": 0,
      "description": "Disappear at (seconds)."
    },
    "style_id": {
      "type": "string",
      "description": "Image only. Style preset ID from find(type='image_gen_style_packs'). See resource clueso://docs/generation-styles."
    },
    "background": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "enum": [
            "0",
            "1",
            "true",
            "false",
            "yes",
            "no"
          ],
          "type": "string"
        }
      ],
      "description": "Image only, and only honoured by `gpt-image-2.5-flare`, `gpt-image-2.5-sunburst`, `gpt-image-1` and `gpt-image-1.5` — every other model is always opaque and ignores this. Pass `false` for a cut-out with no background: icons, logos, stickers, anything meant to sit ON the composition rather than behind it. You MUST set `model` to one of those four in the same call; `gpt-image-2.5-flare` is the one to default to, since the older pair cannot frame wide. Asking for transparency in the PROMPT instead does not work — the model paints a grey-and-white checkerboard as real pixels."
    },
    "project_id": {
      "type": "string",
      "description": "Project ID."
    },
    "start_time": {
      "type": "number",
      "minimum": 0,
      "description": "Appear at (seconds)."
    },
    "aspect_ratio": {
      "enum": [
        "1:1",
        "4:3",
        "3:4",
        "16:9",
        "9:16",
        "3:2",
        "2:3"
      ],
      "type": "string",
      "description": "Image only. Overrides the ratio inferred from width/height. Leave it off and the box decides, which is usually what you want — set it when the box is a placeholder and you know the shape you need. Still clamped to what the model accepts: gpt-image-1/1.5 only do 1:1, 4:3 and 3:4; the gpt-image-2.5 pair adds 16:9 and 9:16; gpt-image-2 has no 3:2 or 2:3, so those become 4:3 and 3:4. The response does not report the ratio used."
    },
    "mcp_upload_id": {
      "type": "string",
      "description": "mcp_upload_id from upload_file, or a Clueso upload_id. Resolved server-side to a presigned URL before generation."
    },
    "voiceover_text": {
      "type": "string",
      "description": "Animation only. Paces the motion to the spoken script — and as a side effect sets this clip's voiceover text and triggers speech generation for the clip. If the clip's current voiceover_text (get_clip) has <SYNC_MARKER N> tokens, this text must carry each of them once, in order, or the animation is refused."
    },
    "animation_setting": {
      "type": "object",
      "properties": {
        "exit": {
          "type": "object",
          "properties": {
            "preset": {
              "enum": [
                "slide",
                "fade",
                "pop",
                "scale",
                "masked_reveal",
                "typewriter",
                "none"
              ],
              "type": "string",
              "description": "Preset for this phase. 'typewriter' is char-only and has no direction."
            },
            "direction": {
              "enum": [
                "left",
                "right",
                "top",
                "bottom",
                "center_all",
                "center_vertically",
                "center_horizontally",
                "none"
              ],
              "type": "string",
              "description": "Slide direction for this phase. Ignored by fade/scale/pop/typewriter; pass 'none' when the preset has no direction."
            },
            "apply_to_unit": {
              "enum": [
                "char",
                "word",
                "line",
                "box"
              ],
              "type": "string",
              "description": "Granularity. 'typewriter' is restricted to 'char'."
            },
            "duration_per_unit_ms": {
              "type": "number",
              "minimum": 0,
              "description": "NAME IS MISLEADING — this is the TOTAL duration of the phase in ms (NOT per unit). The renderer splits it across all N units with ~50% overlap. For a perceptible per-unit rhythm scale UP with the unit count (e.g. typewriter on N chars ≈ N × 100–200 ms). For applyToUnit='box' it's just the phase duration. Omit it and you get 400ms, the same default the editor creates with."
            }
          },
          "description": "Exit (disappear) animation phase."
        },
        "entry": {
          "type": "object",
          "properties": {
            "preset": {
              "enum": [
                "slide",
                "fade",
                "pop",
                "scale",
                "masked_reveal",
                "typewriter",
                "none"
              ],
              "type": "string",
              "description": "Preset for this phase. 'typewriter' is char-only and has no direction."
            },
            "direction": {
              "enum": [
                "left",
                "right",
                "top",
                "bottom",
                "center_all",
                "center_vertically",
                "center_horizontally",
                "none"
              ],
              "type": "string",
              "description": "Slide direction for this phase. Ignored by fade/scale/pop/typewriter; pass 'none' when the preset has no direction."
            },
            "apply_to_unit": {
              "enum": [
                "char",
                "word",
                "line",
                "box"
              ],
              "type": "string",
              "description": "Granularity. 'typewriter' is restricted to 'char'."
            },
            "duration_per_unit_ms": {
              "type": "number",
              "minimum": 0,
              "description": "NAME IS MISLEADING — this is the TOTAL duration of the phase in ms (NOT per unit). The renderer splits it across all N units with ~50% overlap. For a perceptible per-unit rhythm scale UP with the unit count (e.g. typewriter on N chars ≈ N × 100–200 ms). For applyToUnit='box' it's just the phase duration. Omit it and you get 400ms, the same default the editor creates with."
            }
          },
          "description": "Entry (appear) animation phase."
        }
      },
      "description": "Image only. Entry/exit animation, same shape as add_elements' type_data.animation_setting. The design guide asks AI images to enter with `masked_reveal` or a slow fade, so set it here rather than following up with update_elements — that follow-up targets the element while it is still generating. Ignored for kind='animation', which animates through its generated code."
    },
    "base_component_id": {
      "type": "string",
      "description": "Animation only. Reuse a saved animation component as the starting point (from find(type='element_components')). To re-skin its tunable parameters, set parameter_values via update_elements after it renders."
    },
    "reference_image_url": {
      "type": "string",
      "description": "Public URL of a reference image. Mutually exclusive with mcp_upload_id."
    }
  },
  "additionalProperties": {}
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "project_id"
  ],
  "properties": {
    "project_id": {
      "type": "string",
      "description": "Project ID"
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "clip_index",
    "project_id"
  ],
  "properties": {
    "render": {
      "type": "object",
      "properties": {
        "rev": {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": 1,
          "description": "With animation: the revision to render."
        },
        "cues": {
          "type": "object",
          "description": "Cue times to try, key: seconds (element-local).",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "type": "number"
          }
        },
        "save": {
          "type": "boolean",
          "description": "Also upload the rendered image to S3 and return presigned_url, which you can pass as source_url to update_clueprint (files=[{path, source_url}]). Uploads ONE image, so it works with a single frame or a grid but not with layout:'separate' — there is one URL and several frames."
        },
        "entry": {
          "type": "string",
          "minLength": 1,
          "description": "With animation: the entry to render."
        },
        "video": {
          "type": "boolean",
          "description": "For people: also a short low-resolution MP4 of the same window (the filmstrip's, or the animation's first 10 s), returned as video_url, a link valid for an hour. You can't watch it: judge motion from the filmstrip."
        },
        "layout": {
          "enum": [
            "sheet",
            "separate"
          ],
          "type": "string",
          "description": "Only meaningful when `timestamps` holds several. 'sheet' (default) tiles them into one image; 'separate' returns them full-size, which costs ~4x more — use it only when a grid cell is too small to judge."
        },
        "actions": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "name",
              "start"
            ],
            "properties": {
              "args": {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {}
              },
              "name": {
                "type": "string",
                "minLength": 1
              },
              "start": {
                "type": "number"
              },
              "duration": {
                "type": "number"
              }
            }
          },
          "description": "Action clips to try, [{name, start, duration?, args?}], element-local seconds; duration defaults to the action's default_duration. Replaces the element's clips for this render."
        },
        "preview": {
          "type": "string",
          "minLength": 1,
          "description": "A preview token from edit_animation(dry_run: true): renders the unsaved code on its own as one sheet, cropped like element_id — the element the edit was about, or, for a dry run without an element, the entry alone on this clip. Nothing is saved."
        },
        "duration": {
          "type": "number",
          "description": "With animation, or a preview without an element: how long it plays, in seconds (default its default_duration).",
          "exclusiveMinimum": 0
        },
        "animation": {
          "type": "string",
          "minLength": 1,
          "description": "With entry: render that animation entry on its own on this clip at its latest revision (or rev), without placing or saving anything. Pair with parameter_values, duration and timestamps as needed."
        },
        "filmstrip": {
          "anyOf": [
            {
              "type": "boolean",
              "const": true
            },
            {
              "type": "object",
              "properties": {
                "to": {
                  "type": "number",
                  "description": "Window end, element-local seconds, or clip seconds for a whole clip (default the end).",
                  "exclusiveMinimum": 0
                },
                "fps": {
                  "type": "number",
                  "maximum": 60,
                  "description": "Frames per second instead of a count, e.g. 8 over 2 s is 17, capped at 16.",
                  "exclusiveMinimum": 0
                },
                "from": {
                  "type": "number",
                  "minimum": 0,
                  "description": "Window start, element-local seconds, or clip seconds for a whole clip (default 0)."
                },
                "seam": {
                  "type": "boolean",
                  "const": true,
                  "description": "get_clip of a whole clip only: the cut from this clip into the next, as the player shows it: this clip's last second, its transition, and the next clip's first second, in this clip's seconds; takes frames, no window. Every cut of the film at once: get_project({render: {seams: true}})."
                },
                "span": {
                  "type": "number",
                  "description": "With around: the window's length in seconds (default 2 around a cue; the clip plus 0.5 around an action).",
                  "exclusiveMinimum": 0
                },
                "around": {
                  "type": "string",
                  "pattern": "^(cue|action):.+",
                  "description": "Center the window on a cue ('cue:land') or an action clip ('action:hop', by name or id) instead of from/to. On a whole clip, a cue several animations share is 'cue:land@<element name>'."
                },
                "frames": {
                  "type": "integer",
                  "maximum": 16,
                  "minimum": 2,
                  "description": "How many frames across the window, first and last included (default 12, max 16)."
                }
              },
              "additionalProperties": false
            }
          ],
          "description": "See motion in ONE image instead of four moments: frames spaced evenly across a window (default 12 over the whole animation), in reading order, each labelled with its element-local time, with a thin timeline under each row marking the frames, cues (lines) and action clips (bars). Read pacing, easing and whether a beat lands on its cue from it. true for the defaults, or {from, to} / {around: 'cue:<key>' | 'action:<name>', span}, with frames or fps. Replaces timestamps. On get_clip without element_id, animation or preview it shows the whole clip, every element drawn, in clip seconds, and the timeline also ticks each element's start and end."
        },
        "max_width": {
          "type": "integer",
          "maximum": 1568,
          "minimum": 320,
          "description": "Width in px of the image you get back: default 960 for a single frame, 1280 for a grid (the whole grid; a cell is about a third). An image costs about (w×h)/750 tokens and nothing is gained above 1568. On a render of one animation it is the resolution drawn before the crop; sheet cells stay at most 360px wide."
        },
        "animations": {
          "type": "boolean",
          "description": "Whether entry/exit animations play at this timestamp. Default true — the frame as the video will show it, which is what you want to judge motion. Pass false to draw every element settled at its final position and full opacity: use that to check COMPOSITION, because with staggered starts and short windows there may be no single timestamp at which nothing is mid-flight, and an element part-way through a slide reads as mis-positioned when it is fine."
        },
        "element_id": {
          "type": "string",
          "minLength": 1,
          "description": "Render only this element over the clip's background, each moment cropped to its box, as one small sheet: the fast way to check one animation. Without timestamps it shows four moments across the element."
        },
        "timestamps": {
          "anyOf": [
            {
              "type": "number",
              "minimum": 0
            },
            {
              "type": "array",
              "items": {
                "type": "number",
                "minimum": 0
              },
              "maxItems": 15,
              "minItems": 1
            }
          ],
          "description": "Which moment(s) of the clip to render, in seconds (default 0). Pass several — [0.5, 2, 4] — and they come back as one labelled grid costing about a quarter of what those frames cost individually. Prefer several whenever you are checking rather than reading: entry animations mean no single moment shows everything, so one frame is usually the wrong question. A grid cell is a third of the width, so for small print pass a single number. Max 15; duplicates dropped, sorted into time order."
        },
        "param_tracks": {
          "type": "object",
          "description": "Keyframed settings to try, key: [{t, value, interpolation?}], t in element-local seconds. Replaces that key's track for this render.",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "t",
                "value"
              ],
              "properties": {
                "t": {
                  "type": "number"
                },
                "value": {},
                "interpolation": {
                  "type": "string"
                }
              }
            },
            "minItems": 1
          }
        },
        "parameter_values": {
          "type": "object",
          "description": "Settings to render with, merged over the element's own (key: value).",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        }
      },
      "description": "Render the clip as an image. Presence of this object IS the request to render — omit it and nothing is rendered. `{}` renders at t=0. Independent of `select`, which only shapes the JSON: pair `select: []` with `render: {}` for the PNG alone (smallest read). CHECKING YOUR WORK: pass `timestamps` with SEVERAL mid-clip moments, not the t=0 default — text and image elements have entry animations (a ~0.4s slide/fade by default), so at t=0 they have not arrived yet and a correct edit renders as an empty frame, while shapes have no entry animation and do show at t=0. That mix is what makes a single t=0 render actively misleading: some elements appear and others don't. A list comes back as one grid for about a quarter of the tokens of the same frames separately, so checking several moments is the cheap option, not the expensive one. `animations: false` draws everything settled if you would rather not pick moments at all.",
      "additionalProperties": false
    },
    "select": {
      "type": "array",
      "items": {
        "enum": [
          "elements",
          "voiceover_words",
          "groups",
          "busy",
          "geometry",
          "elements.name",
          "elements.element_type",
          "elements.x",
          "elements.y",
          "elements.width",
          "elements.height",
          "elements.start_time",
          "elements.end_time",
          "elements.rotation",
          "elements.keyframes",
          "elements.textdata",
          "elements.shapedata",
          "elements.imagedata",
          "elements.videodata",
          "elements.zoomdata",
          "elements.codedata",
          "elements.avatardata",
          "elements.parent_id",
          "elements.dropShadows",
          "elements.animation"
        ],
        "type": "string"
      },
      "description": "Ask for exactly the JSON you want, GraphQL-style. Omit for everything; pass [] for none.\n  Sections: 'elements' (whole elemen
… [server-provided details truncated]

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "clueprint_id"
  ],
  "properties": {
    "use": {
      "type": "boolean",
      "description": "true: you are building a project from this clueprint; counts the use. Once per build."
    },
    "include": {
      "enum": [
        "metadata",
        "tree",
        "files",
        "all"
      ],
      "type": "string",
      "default": "tree",
      "description": "What to return: 'metadata' | 'tree' | 'files' | 'all'. Defaults to 'tree'."
    },
    "file_paths": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "include='files' only: relative paths to read (e.g. ['design/colors.md', 'rules/voice.md']). Ignored for other modes."
    },
    "project_id": {
      "type": "string",
      "description": "use=true only: the project being built from it, when it exists."
    },
    "clueprint_id": {
      "type": "string",
      "description": "ID of the clueprint."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "project_id"
  ],
  "properties": {
    "clip_id": {
      "type": "string",
      "description": "Only comments pinned to this clip. Omit for every comment on the project, project-level ones included."
    },
    "project_id": {
      "type": "string",
      "description": "The project (guide) ID"
    },
    "include_resolved": {
      "type": "boolean",
      "description": "Include threads already marked resolved (default false). Turn it on to see history; leave it off to see the work outstanding."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "query": {
      "type": "string",
      "maxLength": 200,
      "description": "With topic 'stdlib': what to search for."
    },
    "topic": {
      "enum": [
        "design",
        "animation",
        "stdlib"
      ],
      "type": "string",
      "description": "Older form; select covers it. 'animation': the animation guide's gist. 'stdlib': search with query."
    },
    "select": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 120,
        "minLength": 1
      },
      "maxItems": 40,
      "minItems": 1,
      "description": "Everything to return, in one list: section paths and plain words, mixed. 'brand' and 'brand.<section>' read the brand kit."
    },
    "project_id": {
      "type": "string",
      "description": "The project you are designing: adds its brand kit (the project's own, else the workspace default) as the 'brand' section."
    },
    "brand_kit_id": {
      "type": "string",
      "description": "Read this brand kit (an id from find(type='brand_kits'), or 'default') instead of the project's: for a project on another kit, or a co-branded scene."
    },
    "clueprint_id": {
      "type": "string",
      "description": "The clueprint this project is built from: the brand section then says what it decides (format) and what the kit decides (identity), and whether it is brand_locked."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "element_type"
  ],
  "properties": {
    "mode": {
      "enum": [
        "add",
        "update"
      ],
      "type": "string",
      "default": "add",
      "description": "'add' returns required + optional fields; 'update' returns all-optional."
    },
    "query": {
      "type": "string",
      "maxLength": 80,
      "minLength": 2,
      "description": "Words describing the property you want ('pill background', 'corner radius', 'line height'): returns the best-matching fields (up to 5) as `fields` would."
    },
    "detail": {
      "enum": [
        "compact",
        "full"
      ],
      "type": "string",
      "description": "'compact' (default): names, types and one-line notes. 'full': every field's full notes, nested docs and the keyframe rules."
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Return only these fields, with their full notes, default and an example — text is 15KB whole, ~300 bytes for two."
    },
    "format": {
      "enum": [
        "declarations",
        "json"
      ],
      "type": "string",
      "description": "Defaults to 'declarations' — TypeScript-style, which is the better READ. Inside run_script it defaults to 'json' instead, because a script indexes into the structure and the declaration text would arrive newline-escaped. Set it explicitly to override either default."
    },
    "element_type": {
      "enum": [
        "text",
        "callout",
        "rectangle",
        "arrow",
        "blur",
        "spotlight",
        "zoom",
        "image",
        "video",
        "animation",
        "avatar",
        "group"
      ],
      "type": "string",
      "description": "One of: text, callout, rectangle, arrow, blur, spotlight, zoom, image, video, animation, avatar, group"
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "project_id"
  ],
  "properties": {
    "project_id": {
      "type": "string",
      "description": "The project ID whose embed to read"
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "export_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The export_id export_project returned. Omit when passing project_id."
    },
    "project_id": {
      "type": "string",
      "description": "Check this project's most recently requested export instead. Omit when passing export_id."
    },
    "wait_seconds": {
      "type": "integer",
      "maximum": 55,
      "minimum": 0,
      "description": "How long to wait for the export to complete or fail before answering, default 50s. Pass 0 for an immediate status check (always, inside run_script)."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "project_id"
  ],
  "properties": {
    "render": {
      "type": "object",
      "properties": {
        "at": {
          "type": "array",
          "items": {
            "type": "number",
            "minimum": 0
          },
          "maxItems": 15,
          "minItems": 1,
          "description": "Film seconds, at most 15."
        },
        "clips": {
          "anyOf": [
            {
              "type": "boolean",
              "const": true
            },
            {
              "type": "object",
              "properties": {
                "at": {
                  "anyOf": [
                    {
                      "enum": [
                        "start",
                        "middle",
                        "end"
                      ],
                      "type": "string"
                    },
                    {
                      "type": "number",
                      "minimum": 0
                    }
                  ],
                  "description": "Where in each clip (default 'middle'), or clip seconds."
                },
                "from_clip": {
                  "type": "integer",
                  "maximum": 9007199254740991,
                  "minimum": 0,
                  "description": "First clip shown (default 0)."
                }
              },
              "additionalProperties": false
            }
          ],
          "description": "One frame per clip. 15 clips a call."
        },
        "seams": {
          "anyOf": [
            {
              "type": "boolean",
              "const": true
            },
            {
              "type": "object",
              "properties": {
                "from_cut": {
                  "type": "integer",
                  "maximum": 9007199254740991,
                  "minimum": 0,
                  "description": "First cut shown (default 0)."
                }
              },
              "additionalProperties": false
            }
          ],
          "description": "Every cut: the last frame before it and the first after, labelled with its transition. 7 cuts a call."
        },
        "max_width": {
          "type": "integer",
          "maximum": 1568,
          "minimum": 320,
          "description": "Sheet width in px (default 1280)."
        },
        "animations": {
          "type": "boolean",
          "description": "false draws every element settled."
        }
      },
      "description": "The whole film as ONE labelled image instead of the summary: exactly one of seams, clips or at. A reply that leaves cuts or clips out names the next from_cut or from_clip.",
      "additionalProperties": false
    },
    "project_id": {
      "type": "string",
      "description": "The project ID"
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 50,
      "minimum": 1,
      "description": "Rows to return, default 20, max 50. `total` counts every matching row."
    },
    "state": {
      "enum": [
        "pending",
        "in_progress",
        "done",
        "failed"
      ],
      "type": "string",
      "description": "Only rows in this state."
    },
    "project_id": {
      "type": "string",
      "description": "Only this project's row."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "job_id"
  ],
  "properties": {
    "job_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "From the run_script reply."
    },
    "wait_seconds": {
      "type": "integer",
      "maximum": 55,
      "minimum": 0,
      "description": "How long to wait for completion before answering, default 50s. Pass 0 for an immediate status check."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "action"
  ],
  "properties": {
    "add": {
      "type": "array",
      "items": {
        "enum": [
          "logos",
          "reference_images"
        ],
        "type": "string"
      },
      "description": "fill: logos and/or reference_images to add beside the kit's own."
    },
    "url": {
      "type": "string",
      "description": "Website, e.g. 'cursor.com' (create, preview_fill, fill)."
    },
    "mode": {
      "enum": [
        "white",
        "recolor"
      ],
      "type": "string",
      "description": "dark_logo: how to make it."
    },
    "name": {
      "type": "string",
      "description": "Kit name (create)."
    },
    "action": {
      "enum": [
        "create",
        "preview_fill",
        "fill",
        "update",
        "set_default",
        "research",
        "dark_logo",
        "delete"
      ],
      "type": "string"
    },
    "kit_id": {
      "type": "string",
      "description": "The kit; every action but create."
    },
    "changes": {
      "type": "object",
      "description": "update: the fields to change.",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "logo_id": {
      "type": "string",
      "description": "dark_logo: the kit's light-background logo to make it from."
    },
    "replace": {
      "type": "array",
      "items": {
        "enum": [
          "company",
          "logos",
          "colors",
          "fonts",
          "icons",
          "reference_images",
          "guidelines",
          "palette"
        ],
        "type": "string"
      },
      "description": "fill: sections that take the site's version; 'palette' is the same as 'colors'."
    },
    "confirmed": {
      "type": "boolean",
      "description": "delete: true only after the user agreed to delete this kit."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "action"
  ],
  "properties": {
    "ipa": {
      "type": "string",
      "description": "set: IPA phonemes (slashes optional)."
    },
    "text": {
      "type": "string",
      "description": "to_ipa: text to convert."
    },
    "word": {
      "type": "string",
      "description": "set/remove: the word as written in the script."
    },
    "action": {
      "enum": [
        "list",
        "set",
        "remove",
        "to_ipa"
      ],
      "type": "string"
    },
    "replace": {
      "type": "boolean",
      "description": "set: overwrite an existing entry, only after the user confirmed."
    },
    "language": {
      "type": "string",
      "description": "Voice language code or name (default 'en'); an unknown one is an error."
    },
    "spelling": {
      "type": "string",
      "description": "set: the sound-alike respelling."
    },
    "project_id": {
      "type": "string",
      "description": "The project being worked on: its open editors pick up the change."
    },
    "case_sensitive": {
      "type": "boolean",
      "description": "set: match only this exact casing (default false)."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "all": {
      "type": "boolean",
      "description": "With pattern and no animation: search every animation in this workspace."
    },
    "path": {
      "type": "string",
      "description": "A file in the animation, e.g. 'entries/maya.js' or 'manifest.json'. Returns numbered lines."
    },
    "range": {
      "type": "array",
      "items": {
        "type": "integer",
        "maximum": 9007199254740991,
        "minimum": 1
      },
      "maxItems": 2,
      "minItems": 2,
      "description": "With path: first and last line to return, inclusive, e.g. [40, 80]."
    },
    "format": {
      "enum": [
        "numbered",
        "raw",
        "json"
      ],
      "type": "string",
      "description": "With path: 'numbered' (default) prefixes each line with 'N| ' for choosing edit text; 'raw' returns the exact file text; 'json' returns a .json file (manifest.json) parsed, as `json`."
    },
    "pattern": {
      "type": "string",
      "maxLength": 200,
      "description": "A regular expression, at most 200 characters. Returns matching lines with their path and line number, across the animation (or every workspace animation with all: true)."
    },
    "animation": {
      "type": "string",
      "minLength": 1,
      "description": "The animation: @org/<slug>, @official/<slug>, @community/<publisher>/<slug>, or its id (from find(type='animations'))."
    },
    "element_id": {
      "type": "string",
      "description": "An animation element: reads the animation it shows, at the revision it shows. Use this OR animation."
    },
    "project_id": {
      "type": "string",
      "description": "Project the element is in. Needed with element_id."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "chat_id",
    "guide_id",
    "preceding_clip_id",
    "scenes"
  ],
  "properties": {
    "scenes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "exit": {
            "type": "object",
            "required": [
              "mode"
            ],
            "properties": {
              "mode": {
                "enum": [
                  "hard",
                  "hold",
                  "freeze"
                ],
                "type": "string",
                "description": "'hard' (default), 'hold' or 'freeze' — how this scene ends. Consumed by AVS (contract: MULTI_VIDEO_MODE_CONTRACT.md in gigauser-backend-prod)."
              }
            },
            "description": "How this scene ends."
          },
          "pace": {
            "enum": [
              "quick",
              "normal",
              "hold"
            ],
            "type": "string",
            "description": "b-roll scenes ONLY — set to null on narrated scenes by the normalizer, so it has no effect there. Controls how long the scene dwells ('quick' | 'normal' | 'hold'); absent means unset, not 'normal'."
          },
          "type": {
            "enum": [
              "narrated",
              "b-roll"
            ],
            "type": "string",
            "description": "Scene kind. 'narrated' carries a voiceover and requires narration_script; 'b-roll' is silent footage with no narration or article."
          },
          "entry": {
            "type": "object",
            "required": [
              "mode"
            ],
            "properties": {
              "mode": {
                "enum": [
                  "fresh",
                  "continue"
                ],
                "type": "string",
                "description": "'fresh' (default) or 'continue' — how this scene begins relative to the previous one. Consumed by AVS (contract: MULTI_VIDEO_MODE_CONTRACT.md in gigauser-backend-prod)."
              }
            },
            "description": "How this scene begins relative to the preceding one."
          },
          "clip_name": {
            "type": "string",
            "description": "Title for the clip this scene produces."
          },
          "voice_name": {
            "type": "string",
            "description": "Voice to narrate this scene, from find(type='voices')."
          },
          "description": {
            "type": "string",
            "description": "What should happen on screen during this scene."
          },
          "voice_engine": {
            "type": "string",
            "description": "Speech engine used to render this scene's voice."
          },
          "article_script": {
            "type": "string",
            "description": "Article text written into the written guide for this scene."
          },
          "narration_script": {
            "type": "string",
            "description": "Voiceover text spoken over this scene. Required for a narrated scene, omitted for b-roll."
          },
          "video_script_mode": {
            "enum": [
              "rewrite",
              "near_exact",
              "exact"
            ],
            "type": "string",
            "description": "How the narration is treated for this scene. Overrides the top-level setting for this scene."
          },
          "exact_video_script": {
            "type": "boolean",
            "description": "Legacy flag — prefer video_script_mode instead. When true, narration_script for this scene is used verbatim and left unreworded. Overrides the top-level setting for this scene."
          },
          "article_script_mode": {
            "enum": [
              "rewrite",
              "exact"
            ],
            "type": "string",
            "description": "How the article is treated for this scene. Overrides the top-level setting for this scene."
          },
          "custom_instructions": {
            "type": "string",
            "description": "Extra guidance for recording this scene only, e.g. 'select project X' or 'scroll to the pricing table'."
          },
          "exact_article_script": {
            "type": "boolean",
            "description": "Legacy flag — prefer article_script_mode instead. When true, article_script for this scene is used verbatim and left unreworded. Overrides the top-level setting for this scene."
          }
        }
      },
      "minItems": 1,
      "description": "REQUIRED — the recording to make, as a list of scenes. This is the ONLY way to specify what to record. A normal single recording is exactly ONE scene; a code-wizard multi-scene / marketing video is N scenes (one clip per scene, and ALL cuts of one video go in a SINGLE record_screen call). A narrated scene REQUIRES a non-empty narration_script; a b-roll scene is silent (no narration, no article). A cut that starts somewhere disconnected is just a scene with entry.mode \"fresh\". Cleopatra orgs accept exactly ONE narrated scene. Do not set scene_id — it is assigned server-side."
    },
    "target": {
      "enum": [
        "code",
        "browser"
      ],
      "type": "string",
      "description": "Which recorder to use when the workspace has both Code record and Browser record: 'code' for a mock of the product, 'browser' for the real product — from the user's request, or their answer when it didn't say. Omit otherwise."
    },
    "chat_id": {
      "type": "string",
      "description": "Conversation context ID"
    },
    "guide_id": {
      "type": "string",
      "description": "Target guide ID"
    },
    "language": {
      "type": "string",
      "default": "en",
      "description": "Language code for the recording (default: en)"
    },
    "clueprint_id": {
      "type": "string",
      "description": "The clueprint this video is built from, if any (the id you passed to get_clueprint). Effects placed automatically on the recording follow that clueprint's effect rules; omit it and they follow the default rules."
    },
    "voice_version": {
      "enum": [
        "latest",
        "legacy"
      ],
      "type": "string",
      "description": "ElevenLabs voice generation for every scene's voice. Leave unset: a named voice uses latest, while a voice the workspace saved and the workspace default keep their own saved version. Use 'legacy' ONLY when the user explicitly asks for the legacy/older voice generation; never choose it yourself."
    },
    "edit_scene_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The clip id(s) this edit replaces. Only used when recording_session_id is set; scenes you do not name are not re-filmed. Set preceding_clip_id to the clip you are replacing — an edit naming a clip that is not in the guide is refused rather than appended to the end."
    },
    "video_intention": {
      "type": "string",
      "default": "",
      "description": "One-line intent shared across all scenes of a multi-scene recording (e.g. \"punchy 30s launch teaser for feature X\"). Ignored for single-scene recordings."
    },
    "preceding_clip_id": {
      "type": "string",
      "description": "Clip ID after which to insert the new clip"
    },
    "video_script_mode": {
      "enum": [
        "rewrite",
        "near_exact",
        "exact"
      ],
      "type": "string",
      "description": "How the narration is treated. 'exact': the user's narration is final and is read word for word; steps the script does not mention play silently. 'near_exact': keep the user's narration word for word, but briefly narrate steps the recording must take that the script does not mention (for example opening a settings dialog to reach something) — use this when the user gives a finished script and did not ask for strictly exact wording. 'rewrite': the narration is a draft and may be reworded to match what was recorded — use this when there is no user script or it is rough. Overrides exact_video_script when both are set."
    },
    "exact_video_script": {
      "type": "boolean",
      "default": false,
      "description": "Legacy flag — prefer video_script_mode instead. Set to true when the video narration must be used exactly as written — the agent that does the recording will not reword, rephrase, or rewrite video_script at all. Default false."
    },
    "article_script_mode": {
      "enum": [
        "rewrite",
        "exact"
      ],
      "type": "string",
      "description": "'exact': the article is used word for word. 'rewrite': the article may be reworded to match the recording. Overrides exact_article_script when both are set."
    },
    "custom_instructions": {
      "type": "string",
      "default": "",
      "description": "Optional per-recording instructions (e.g. \"select project X\", \"add rectangle 200x100\"). Not related to mocking."
    },
    "exact_article_script": {
      "type": "boolean",
      "default": false,
      "description": "Legacy flag — prefer article_script_mode instead. Set to true when the article must be used exactly as written — the agent that does the recording will not reword, rephrase, or rewrite article_script at all. Default false."
    },
    "recording_session_id": {
      "type": "string",
      "description": "EDIT an existing recording instead of shooting a new one. Pass the recording_session_id from the record_screen that made it, or read it off get_clip. The recorder restores that take's code, notes and click script and changes only what you ask for, which is far faster and cheaper than re-recording. Omit for a fresh recording. Only code-wizard recordings are editable; get_clip omits the field for any clip that is not."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "clip_index",
    "project_id"
  ],
  "properties": {
    "clip_index": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Zero-based clip index to remove"
    },
    "project_id": {
      "type": "string",
      "description": "The project ID"
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "project_id",
    "removals"
  ],
  "properties": {
    "removals": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "clip_index",
          "element_id"
        ],
        "properties": {
          "clip_index": {
            "type": "integer",
            "maximum": 9007199254740991,
            "minimum": 0,
            "description": "Zero-based clip index"
          },
          "element_id": {
            "type": "string",
            "description": "Element ID (from get_clip)"
          }
        },
        "additionalProperties": false
      },
      "minItems": 1,
      "description": "Elements to remove — at least one entry."
    },
    "project_id": {
      "type": "string",
      "description": "Project ID"
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "project_id",
    "target"
  ],
  "properties": {
    "target": {
      "enum": [
        "element",
        "group",
        "audio"
      ],
      "type": "string",
      "description": "What to remove: 'element', 'group' or 'audio'"
    },
    "group_id": {
      "type": "string",
      "description": "Group ID to remove (required for target='group')"
    },
    "music_id": {
      "type": "string",
      "description": "Music/SFX track ID to remove (required for target='audio')"
    },
    "clip_index": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Zero-based clip index. Required for target='group'; for target='element' an optional hint — the element is found by id either way"
    },
    "element_id": {
      "type": "string",
      "description": "Element ID to remove (target='element'; or use element_ids)"
    },
    "project_id": {
      "type": "string",
      "description": "The project ID"
    },
    "element_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Several element IDs to remove (target='element'). Removed one at a time, so a failure part-way leaves the earlier ones removed; retrying the same list is safe — ids already gone come back as already_absent. For a large batch prefer remove_elements, which lands in one save"
    },
    "keep_children": {
      "type": "boolean",
      "description": "target='group' only. Omit/true ungroups: children rise to the removed group's own parent. false deletes the whole subtree."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "clip_index",
    "ordered_element_ids",
    "project_id"
  ],
  "properties": {
    "clip_index": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Zero-based clip index."
    },
    "project_id": {
      "type": "string",
      "description": "Project ID."
    },
    "ordered_element_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "description": "All element IDs currently in the clip, in the new order. Position N = z-index N (later = on top)."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "code"
  ],
  "properties": {
    "code": {
      "type": "string",
      "maxLength": 200000,
      "minLength": 1,
      "description": "JavaScript. Tools are globals called synchronously — no async/await, no network or filesystem; `return` a value to hand it back."
    },
    "dry_run": {
      "type": "boolean",
      "description": "Read-only tools still run; anything that writes is recorded and skipped. Use it to check what a script would do before it does it."
    },
    "wait_seconds": {
      "type": "integer",
      "maximum": 55,
      "minimum": 1,
      "description": "How long to hold this call open waiting for the script, default 50s. If it finishes in time you get the result here; if not you get a job_id to poll with get_script_job, and the script keeps running either way."
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 200,
      "minLength": 8,
      "description": "Pass a unique string so a retry cannot run the same build twice. If a script with this key already ran in this workspace, its job is returned and nothing executes again — including when that run FAILED, because a script is not a transaction and the writes it made before failing are still there. To act after a failure, read the project, repair what landed, and use a NEW key. It is the only guard against a resend: without it, a resent call runs the whole script again. Worth setting for anything that builds."
    },
    "timeout_seconds": {
      "type": "integer",
      "maximum": 1800,
      "minimum": 5,
      "description": "Wall-clock budget for the SCRIPT — separate from wait_seconds, which is only how long this call stays open. By default a script gets 50s while you are waiting on it, and is raised to 15 minutes the moment it outlives the wait and becomes a job you poll with get_script_job. Set this only to override BOTH with one fixed budget. Watch the slow tools: analyze_audio in 'transcript' or 'beats' mode, export_project and auto_sync take tens of seconds each and will eat a budget fast. Never wait on an export in a script: start it with export_project and end the script (get_export holds for its wait_seconds; pass 0 if you read one). analyze_audio in 'features' mode is ~1s and is fine to loop over."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "project_id",
    "voice_engine",
    "voice_name"
  ],
  "properties": {
    "clip_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Clip ids to change the voice on. Omit to change EVERY clip in the project."
    },
    "project_id": {
      "type": "string",
      "description": "The project (guide) ID"
    },
    "voice_name": {
      "type": "string",
      "minLength": 1,
      "description": "Voice name exactly as find(type='voices') lists it (e.g. 'Alex')."
    },
    "voice_engine": {
      "type": "string",
      "minLength": 1,
      "description": "Voice engine — 'eleven', 'cartesia', 'google', etc."
    },
    "voice_version": {
      "enum": [
        "latest",
        "legacy"
      ],
      "type": "string",
      "description": "ElevenLabs voice generation. Leave unset: latest, except a voice the workspace saved keeps its saved version. Use 'legacy' ONLY when the user explicitly asks for the legacy/older voice generation; never choose it yourself. Ignored for non-ElevenLabs voices."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "clip_index",
    "project_id",
    "split_time"
  ],
  "properties": {
    "clip_index": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Index of the clip to split"
    },
    "project_id": {
      "type": "string",
      "description": "The project ID"
    },
    "split_time": {
      "type": "number",
      "description": "Time in seconds within the clip where to split (clip-relative, not timeline-relative). Must be > 0.1s and < clip_duration − 0.1s; values outside this range are rejected.",
      "exclusiveMinimum": 0.1
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "workspaceId": {
      "type": "string",
      "description": "Workspace ID to switch to"
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "markdown",
    "project_id"
  ],
  "properties": {
    "markdown": {
      "type": "string",
      "description": "Updated article content as markdown with <SCREENSHOT {id}> placeholders"
    },
    "project_id": {
      "type": "string",
      "description": "Project ID"
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "project_id",
    "screenshot_id"
  ],
  "properties": {
    "crop": {
      "type": "object",
      "description": "Crop data: { position: [x,y], size: [w,h] } in fractional coords.",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "render": {
      "type": "boolean",
      "description": "If true (and no other updates supplied), returns current details and a PNG preview without mutating."
    },
    "shapes": {
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      },
      "description": "Array of shape objects for annotations."
    },
    "project_id": {
      "type": "string",
      "description": "Project ID."
    },
    "zoom_factor": {
      "type": "number",
      "minimum": 1,
      "description": "Zoom magnification (1.0 = no zoom)."
    },
    "screenshot_id": {
      "type": "string",
      "description": "Screenshot ID (from get_article)."
    }
  }
}

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "music_id",
    "project_id"
  ],
  "properties": {
    "loop": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "enum": [
            "0",
            "1",
            "true",
            "false",
            "yes",
            "no"
          ],
          "type": "string"
        }
      ],
      "description": "Whether the track loops"
    },
    "volume": {
      "type": "number",
      "maximum": 100,
      "minimum": 0,
      "description": "New playback volume 0-100"
    },
    "fade_in": {
      "type": "number",
      "minimum": 0,
      "description": "Fade-in duration (seconds)"
    },
    "fade_out": {
      "type": "number",
      "minimum": 0,
      "description": "Fade-out duration (seconds)"
    },
    "music_id": {
      "type": "string",
      "description": "ID of the audio track (from get_project.audio_tracks[].id)"
    },
    "project_id": {
      "type": "string",
      "description": "The project ID"
    },
    "guide_end_time": {
      "type": "number",
      "minimum": 0,
      "description": "New end time on the project timeline (seconds)"
    },
    "music_end_time": {
      "type": "number",
      "minimum": 0,
      "description": "New end offset within the source file (seconds)"
    },
    "guide_start_time": {
      "type": "number",
      "minimum": 0,
      "description": "New start time on the project timeline (seconds)"
    },
    "music_start_time": {
      "type": "number",
      "minimum": 0,
      "description": "New start offset within the source file (seconds)"
    }
  }
}