Video Captions

Style fields

The cue background fits the wrapped text plus padding and border. Raise max_width_pct to keep a long line together; the plate stays as wide as that line.

Font size and spacing are measured against the actual video frame. A size of 64 therefore looks proportionally smaller on a 4K frame than on a 1080p frame.

Position

x_pct and y_pct are absolute coordinates from 0 to 100. anchor selects which point on the caption box attaches to that coordinate.

Available anchors: top-left, top, top-right, left, center, right, bottom-left, bottom, bottom-right.

Animation

Both animation.enter and animation.exit accept:

If enter plus exit is longer than the cue, both durations shrink to fit.

Slide animations travel one resolved line height.

Scale animations transform the entire caption around position.anchor. Enter animations move from from_scale to normal size (1); exit animations move from normal size to to_scale. Scaling is uniform, linear, and includes every line, text span, stroke, shadow, background, and border.

{
  "animation": {
    "enter": { "type": "scale", "from_scale": 0.6, "duration_ms": 220 },
    "exit": { "type": "scale", "to_scale": 0.8, "duration_ms": 180 }
  }
}

Highlight individual words

Instead of a string, set text to an array of spans. Each span inherits the cue's text styling and can override font, color, opacity, letter spacing, underline, strike-through, stroke, or shadow. A span can also draw its own background.

{
  "start": 0,
  "end": 2.2,
  "text": [
    { "text": "Open the " },
    {
      "text": "SETTINGS",
      "style": {
        "font": { "size": 84 },
        "text": { "color": "#111111" },
        "background": { "color": "#FFE66D", "opacity": 1, "padding": 8, "radius": 4 }
      }
    }
  ]
}

Span styles accept font, text.color, text.opacity, text.letter_spacing, text.underline, text.strike, stroke, shadow, and background. A span background accepts the same color, opacity, padding, radius, and border fields as a cue background. It is independent of the cue background and does not change text spacing or wrapping. The box is the visible glyphs plus padding, border, and stroke, so an outline stays inside the chip. Leading and trailing whitespace still advances the text but is excluded from the visible background. If the span wraps, each line receives its own box.

A span's text opacity overrides the cue opacity rather than multiplying it. Letter spacing is measured in video pixels and applies after each character, including the final character's positioning advance and styled-span boundaries. Keep position, animation, line height, case, and max width on the cue or in defaults.

{
  "caption_render_id": "22222222-2222-4222-8222-222222222222",
  "status": "completed",
  "source_media_id": "11111111-1111-4111-8111-111111111111",
  "output_media_id": "33333333-3333-4333-8333-333333333333",
  "error": null,
  "created_at": "2026-08-21T10:00:00Z",
  "updated_at": "2026-08-21T10:02:00Z",
  "video": {
    "media_id": "33333333-3333-4333-8333-333333333333",
    "url": "https://signed-storage-url.example/output.mp4",
    "thumbnail_url": "https://signed-storage-url.example/output-thumb.jpg",
    "file_name": "source-captions-2026-08-21T10-02-00Z.mp4",
    "file_size": 12345,
    "mime_type": "video/mp4",
    "width": 1080,
    "height": 1920,
    "duration": 5,
    "created_at": "2026-08-21T10:02:00Z"
  }
}

The returned url is signed and temporary. Store the durable video.media_id and request a fresh media URL when needed. source_media_id can be null if the original video was deleted after the job was created.