Raw schema
{
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "The text to render. Newlines are honoured as hard line breaks."
},
"x": {
"type": "number",
"description": "Centre x in canvas px. Defaults to canvas centre."
},
"y": {
"type": "number",
"description": "Centre y in canvas px. Defaults to canvas centre."
},
"width": {
"type": "number",
"description": "Box width in px (> 0). Default 900."
},
"height": {
"type": "number",
"description": "Box height in px (> 0). Default 320."
},
"font_family": {
"type": "string",
"description": "Google Fonts family name, e.g. \"Anton\". Defaults to \"Hanken Grotesk\"."
},
"text_size": {
"type": "number",
"description": "Font size in px. Omit to derive from existing text layers (median) or the canvas height."
},
"text_color": {
"type": "string",
"description": "Text fill colour as #rrggbb. Defaults to white."
},
"font_weight": {
"type": "number",
"description": "Font weight 100..900 (400 regular, 700 bold, 800 black). Default 400."
},
"font_style": {
"type": "string",
"enum": [
"normal",
"italic"
],
"description": "Italic toggle. Default normal."
},
"text_transform": {
"type": "string",
"enum": [
"none",
"uppercase",
"lowercase"
],
"description": "Case transform applied before layout. Default none."
},
"letter_spacing": {
"type": "number",
"description": "Tracking between glyphs in px; may be negative. Default 0."
},
"curve": {
"type": "number",
"description": "Curve the text onto an arc, in degrees of total sweep. 0 = straight (default). POSITIVE = a SMILE (⌣, ends rise); NEGATIVE = an ARCH (⌒, rainbow). Clamped ±135. A tasteful smile is ~+60. Single line only (multi-line is joined while curved)."
},
"line_height": {
"type": "number",
"description": "Line height as a multiple of font size (1.2 = 120%)."
},
"text_align": {
"type": "string",
"enum": [
"left",
"center",
"right"
],
"description": "Horizontal alignment of each line. Default center."
},
"text_autofit": {
"type": "string",
"enum": [
"fit",
"shrink",
"wrap",
"hug"
],
"description": "How text fits its box. \"hug\" (default for new layers): hold text_size FIXED and DERIVE the box from the measured text plus padding, honouring the literal newlines you pass — the box shrink-wraps the exact content and grows/shrinks live as the text changes, so it can never re-wrap differently between the editor preview and the export (bake your own \"\\n\" breaks; pair with set_text_background for a rounded caption box). \"wrap\": hold text_size FIXED in a fixed-size box and only word-wrap (hard-breaking a single over-wide word), never resize. \"fit\": ignore text_size and auto-size the font BOTH ways (grow and shrink) to the largest size whose wrapped block fills the box — resizing the box resizes the text. \"shrink\" (legacy): word-wrap then auto-shrink the font from text_size until the block fits; never grows."
},
"text_valign": {
"type": "string",
"enum": [
"top",
"middle",
"bottom"
],
"description": "Vertical alignment of the text block within its box. \"middle\" (default) centres it; \"bottom\" pins it to the box floor so extra wrapped lines grow upward from a fixed baseline (captions use this so a wrapped line doesn't shift the others); \"top\" pins the ceiling."
},
"stroke_width": {
"type": "number",
"description": "Outline width in px (0 = no outline)."
},
"stroke_color": {
"type": "string",
"description": "Outline colour as #rrggbb. Defaults to white when a width is set."
},
"text_shadow": {
"type": [
"object",
"null"
],
"description": "Drop shadow { offsetX, offsetY, blur, color }; color is any CSS colour (rgba allowed). null clears it.",
"properties": {
"offsetX": {
"type": "number"
},
"offsetY": {
"type": "number"
},
"blur": {
"type": "number"
},
"color": {
"type": "string"
}
}
},
"decorations": {
"type": [
"object",
"null"
],
"description": "Per-character underline / strikethrough. { underline?: [{start,end}], strikethrough?: [{start,end}] } — half-open character ranges [start,end) (UTF-16 offsets) into `text`. E.g. underline the first word of \"Big news\": underline:[{start:0,end:3}]. Ranges are normalized (sorted + merged). Not rendered on curved text.",
"properties": {
"underline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"start": {
"type": "number"
},
"end": {
"type": "number"
}
}
}
},
"strikethrough": {
"type": "array",
"items": {
"type": "object",
"properties": {
"start": {
"type": "number"
},
"end": {
"type": "number"
}
}
}
}
}
},
"block": {
"type": "object",
"description": "OPTIONAL timeline window — {start, duration} in composition frames. OMIT IT (the default) and the layer is ALWAYS PRESENT: a persistent overlay that holds for the whole composition, which is what an agent-placed watermark / lower-third almost always wants. Pass it to place a bounded CLIP instead (what the editor's own add does: 5 s at the playhead). Keyframes on a blocked layer are sampled RELATIVE to `start`.",
"properties": {
"start": {
"type": "number",
"description": "First visible composition frame (≥ 0)."
},
"duration": {
"type": "number",
"description": "Length of the window in frames (≥ 1)."
}
},
"required": [
"start",
"duration"
]
},
"projectId": {
"type": "string",
"description": "Opaque project id (a v4 UUID, from list_projects/create_project). Selects which existing project this call mutates."
}
},
"required": [
"projectId"
]
}