Text Examples

Each example is a complete POST /v1/renders body with a video background and a text overlay. Only fields that differ from their defaults are shown (font_family: "Inter", text_color: "#ffffff", text_align: "center" are all defaults). See the element field reference for every default.

duration is required on text elements. Omitting it produces a zero-length window — the text will not appear in the render. The API returns 422 if duration is missing.

Every text overlay sets three groups of fields:

Field	Purpose
`time`, `duration`	When the text appears and disappears (`time + duration` = hide)
`x`, `y`	Position on the frame — percentage strings (`"50%"`) or pixel values (`960`)
`width`	Optional wrap width (defaults to `"100%"`)

x and y refer to the center anchor of the text box.

Minimal text

The required fields on a text element are text and duration. Centered on frame; visible from 1 s to 5 s.

{
  "width": 1920,
  "height": 1080,
  "duration": 10,
  "elements": [
    {
      "type": "video",
      "id": "vid1",
      "source_url": "https://cdn.example.com/clip.mp4",
      "time": 0,
      "in_point": 0,
      "out_point": 10
    },
    {
      "type": "text",
      "id": "t1",
      "text": "Hello World",
      "font_size": 72,
      "time": 1,
      "duration": 4,
      "x": "50%",
      "y": "50%"
    }
  ]
}

Stroke (outline only, no fill)

Glyph outline with no fill — set stroke: true together with stroke_color and stroke_width. Top-center; visible from 0.5 s to 4.5 s. stroke_width is em-relative — a fraction of font_size, not pixels. 0.08 = 8% of the font size. Values above roughly 0.2 bury the glyph in its own outline.

{
  "width": 1920,
  "height": 1080,
  "duration": 10,
  "elements": [
    {
      "type": "video",
      "id": "vid1",
      "source_url": "https://cdn.example.com/clip.mp4",
      "time": 0,
      "in_point": 0,
      "out_point": 10
    },
    {
      "type": "text",
      "id": "t1",
      "text": "OUTLINE",
      "font_size": 96,
      "time": 0.5,
      "duration": 4,
      "x": "50%",
      "y": "15%",
      "stroke_color": "#0070f3",
      "stroke_width": 0.08,
      "stroke": true
    }
  ]
}

Fill + stroke

White text with a colored stroke and fill — set stroke_color and stroke_width without stroke: true. Lower-third; visible from 2 s to 7 s.

{
  "width": 1920,
  "height": 1080,
  "duration": 10,
  "elements": [
    {
      "type": "video",
      "id": "vid1",
      "source_url": "https://cdn.example.com/clip.mp4",
      "time": 0,
      "in_point": 0,
      "out_point": 10
    },
    {
      "type": "text",
      "id": "t1",
      "text": "FILL + STROKE",
      "font_size": 96,
      "time": 2,
      "duration": 5,
      "x": "50%",
      "y": "80%",
      "stroke_color": "#00ff41",
      "stroke_width": 0.08
    }
  ]
}

Background

Solid color box behind the full text block. Bottom-center; visible from 1 s to 5 s.

{
  "width": 1920,
  "height": 1080,
  "duration": 10,
  "elements": [
    {
      "type": "video",
      "id": "vid1",
      "source_url": "https://cdn.example.com/clip.mp4",
      "time": 0,
      "in_point": 0,
      "out_point": 10
    },
    {
      "type": "text",
      "id": "t1",
      "text": "BACKGROUND",
      "font_size": 72,
      "time": 1,
      "duration": 4,
      "x": "50%",
      "y": "75%",
      "background_color": "#0070f3",
      "background": true
    }
  ]
}

Drop shadow

Text with a built-in drop shadow. Upper-center; visible from 0.5 s to 5.5 s.

{
  "width": 1920,
  "height": 1080,
  "duration": 10,
  "elements": [
    {
      "type": "video",
      "id": "vid1",
      "source_url": "https://cdn.example.com/clip.mp4",
      "time": 0,
      "in_point": 0,
      "out_point": 10
    },
    {
      "type": "text",
      "id": "t1",
      "text": "SHADOW",
      "font_size": 96,
      "time": 0.5,
      "duration": 5,
      "x": "50%",
      "y": "40%",
      "shadow": true
    }
  ]
}

Font controls

Bold italic with custom letter spacing and line height. Left-aligned block on the left edge; visible from 2 s to 8 s.

{
  "width": 1920,
  "height": 1080,
  "duration": 10,
  "elements": [
    {
      "type": "video",
      "id": "vid1",
      "source_url": "https://cdn.example.com/clip.mp4",
      "time": 0,
      "in_point": 0,
      "out_point": 10
    },
    {
      "type": "text",
      "id": "t1",
      "text": "Typography",
      "font_family": "Montserrat",
      "font_size": 64,
      "font_weight": 700,
      "font_style": "bolditalic",
      "tracking": 0.05,
      "leading": 1.4,
      "time": 2,
      "duration": 6,
      "x": "12%",
      "y": "50%",
      "width": "40%",
      "text_align": "left"
    }
  ]
}

Set "text_direction": "rtl" for right-to-left scripts.

Per-word styling

words[] gives one word its own color and weight for the element’s whole life. The style vocabulary is exactly {color, bold, italic, underline}. Unlike word_animation, it coexists with motion[]. start/end are a separate channel: they retime that word inside a word-group animation and are ignored without one. Bind one of: a word_animation block, or a custom_animations.text entry with "group": "word" referenced from either motion[].custom (as below) or animation_preset. In the example, "launch" rises on its own 1.2–2.0 s window while the other three words run on the group’s default schedule. Swap the motion entry for a block preset like fade and the two timings stop doing anything.

{
  "width": 1920,
  "height": 1080,
  "duration": 10,
  "elements": [
    {
      "type": "video",
      "id": "vid1",
      "source_url": "https://cdn.example.com/clip.mp4",
      "time": 0,
      "in_point": 0,
      "out_point": 10
    },
    {
      "type": "text",
      "id": "t1",
      "text": "we shipped launch day",
      "font_size": 90,
      "time": 1,
      "duration": 4,
      "x": "50%",
      "y": "78%",
      "words": [
        { "word": "launch", "start": 1.2, "end": 2.0, "style": { "color": "#e8734a", "bold": true } }
      ],
      "motion": [
        { "custom": "wordRise", "time": 1, "duration": 1.4 }
      ]
    }
  ],
  "custom_animations": {
    "text": [
      {
        "name": "wordRise",
        "group": "word",
        "keyframes": [
          { "time": 0, "translate": { "x": 0, "y": 0.06 }, "opacity": 0 },
          { "time": 1, "translate": { "x": 0, "y": 0 }, "opacity": 1, "easing": "expo_out" }
        ]
      }
    ]
  }
}

Animated counter

counter rewrites the text from an eased numeric sweep — the animated stat hero. easing accepts named curves only (no spring / back / elastic). start_time is seconds into the element, not timeline seconds.

{
  "width": 1920,
  "height": 1080,
  "duration": 10,
  "elements": [
    {
      "type": "video",
      "id": "vid1",
      "source_url": "https://cdn.example.com/clip.mp4",
      "time": 0,
      "in_point": 0,
      "out_point": 10
    },
    {
      "type": "text",
      "id": "t1",
      "text": "0",
      "font_size": 220,
      "time": 1,
      "duration": 3,
      "x": "50%",
      "y": "45%",
      "counter": {
        "from_value": 0,
        "to_value": 94,
        "decimals": 0,
        "suffix": "%",
        "easing": "expo_out",
        "start_time": 0.2,
        "length": 2
      }
    }
  ]
}

A counter element cannot also carry a per-glyph animation ("scope": "character", or a per-glyph animation_preset) — glyph timings are computed once against the placeholder text, so the later glyphs of a longer number never render. Use a block animation such as fade.

Glow

Soft glow around the glyphs. size is em-relative, like stroke_width.

{
  "width": 1920,
  "height": 1080,
  "duration": 10,
  "elements": [
    {
      "type": "video",
      "id": "vid1",
      "source_url": "https://cdn.example.com/clip.mp4",
      "time": 0,
      "in_point": 0,
      "out_point": 10
    },
    {
      "type": "text",
      "id": "t1",
      "text": "LAUNCH",
      "font_size": 160,
      "time": 1,
      "duration": 3,
      "x": "50%",
      "y": "50%",
      "glow": { "color": "#ff9d5c", "size": 0.22, "intensity": 1.4 }
    }
  ]
}

Rotation

Tilted text using z_rotation — the only static rotation axis text has. x_rotation / y_rotation are a 422 on text. Offset to the lower-left; visible from 3 s to 8 s.

{
  "width": 1920,
  "height": 1080,
  "duration": 10,
  "elements": [
    {
      "type": "video",
      "id": "vid1",
      "source_url": "https://cdn.example.com/clip.mp4",
      "time": 0,
      "in_point": 0,
      "out_point": 10
    },
    {
      "type": "text",
      "id": "t1",
      "text": "TILTED",
      "font_size": 72,
      "time": 3,
      "duration": 5,
      "x": "30%",
      "y": "70%",
      "z_rotation": "-5°"
    }
  ]
}

Shorthand animation preset

Use the animation_preset string for renderer animation presets like typewriter. Bottom-center caption bar; visible from 0 s to 6 s.

{
  "width": 1920,
  "height": 1080,
  "duration": 10,
  "elements": [
    {
      "type": "video",
      "id": "vid1",
      "source_url": "https://cdn.example.com/clip.mp4",
      "time": 0,
      "in_point": 0,
      "out_point": 10
    },
    {
      "type": "text",
      "id": "t1",
      "text": "Lorem Ipsum",
      "font_family": "IBM Plex Mono",
      "font_size": 48,
      "time": 0,
      "duration": 6,
      "x": "50%",
      "y": "85%",
      "width": "80%",
      "text_color": "#00ff41",
      "stroke_color": "#00ff41",
      "stroke_width": 0.06,
      "animation_preset": "typewriter"
    }
  ]
}

What text rejects

Text is a different renderer path from video and image, and the API refuses what the engine parses but never draws. Each of these returns 422 with a message naming the workaround.

You wrote	Why it fails	Do this instead
`border_radius`	The renderer parses it but never draws a rounded text plate	Put the text over a rounded `shape` — a rectangular `path` plus `corner_radius`, with a flat hex or gradient `fill`
`text_decoration: "underline"`	Underline is read only from per-word style runs	`"words": [{ "word": "…", "start": 0, "end": 1, "style": { "underline": true } }]`
`text_decoration: "strikethrough"`	No renderer path at all	Draw a thin `shape` rectangle over the text
`x_rotation` / `y_rotation`	Text always draws face-on	Tilt via a `custom_animations.text` keyframe `rotation: {x, y, z}`
`x_anchor` / `y_anchor` other than `"50%"`	Text rotates about its box center	Pivot with a video / image / shape element instead
`blend_mode`, `mask`, `mask_shape`, `mask_keyframes`, `matte`, `backdrop_blur`	Not fields on `text` (`Extra inputs are not permitted`)	Use the `overlay` / `difference` motion presets for blends
`effects`	Not a field on `text`	Put the effect on the layer beneath
`animation_preset` and `motion[]` together	The engine reads the preset name only when the element emits no animations array	Pick one
`animation_preset` starting with `loop-`	Needs an explicit cycle length this route cannot express	`motion[]` with the matching `loop_*` type and `duration` = one cycle
`word_animation` and `motion[]` together	The word timings would re-time the motion entries	Pick one

Get Started

Renders

Render Examples

Recipes

Tasks

Webhooks

SDKs

Minimal text

Stroke (outline only, no fill)

Fill + stroke

Background

Drop shadow

Font controls

Per-word styling

Animated counter

Glow

Rotation

Shorthand animation preset

What text rejects

​Minimal text

​Stroke (outline only, no fill)

​Fill + stroke

​Background

​Drop shadow

​Font controls

​Per-word styling

​Animated counter

​Glow

​Rotation

​Shorthand animation preset

​What text rejects

Minimal text

Stroke (outline only, no fill)

Fill + stroke

Background

Drop shadow

Font controls

Per-word styling

Animated counter

Glow

Rotation

Shorthand animation preset

What text rejects