Caption styles

Choose a preset

Preset	Appearance
`classic`	White Inter captions with a dark outline. The default preset.
`highlight`	Uppercase Rubik captions highlighting the active word.
`smash`	Outlined Paytone One captions that pop in one word at a time.
`box`	Inter captions with a purple box behind the active word.
`push`	Uppercase Rubik captions with a green highlight and scale animation.
`elegant`	Uppercase Inter captions that float into place with a soft shadow.
`ogre`	Green Caveat Brush captions popping into the center of the video.
`outline`	Warm Rubik captions with a thick orange outline.
`paper-ink`	Black Rubik captions on rounded white lines at the top.
`action`	Italic Bebas Neue captions with an outline, shadow and active-word color.
`prompter`	Centered Zilla Slab captions with a white outline and active-word opacity.
`storytelling`	Gold Instrument Serif captions with a red outline and offset shadow.
`karaoke`	Rounded Coiny lettering with a progressive purple fill.
`glow`	Rubik captions with a pink glow and fade-in animation.
`thin&bold`	Uppercase Inter captions with animated thin and bold weights.
`background`	Urbanist captions on a rounded black background.

Fetch the catalog from List presets, which is public and requires no API key. Each preset includes defaults, supported_style_fields, style_notes, and its read-only animation name.

Customize the style

All style fields are optional. Omitted fields inherit the preset, including individual fields inside background, outline, shadow, and offset. Sending shadow: { "color": "#FF0000" } changes only the color; it does not enable a disabled shadow. Use enabled: true to enable it. The API starts from the selected preset’s full default style, adapts it to the video’s dimensions, and applies only the properties supplied in style. Omitting style, sending {}, or sending empty nested objects produces the same preset defaults. For example, "preset": "glow" with "style": { "text_color": "#FFE600" } changes only the text color and retains Glow’s font, shadow, layout and animation.

{
  "video_url": "https://your-cdn.example/video.mp4",
  "preset": "box",
  "max_duration_seconds": 60,
  "style": {
    "position": "bottom",
    "font_family": "Rubik",
    "text_color": "#FFFFFF",
    "highlight_color": "#7651E8",
    "line_count": 2,
    "scale": 0.7,
    "background": { "type": "box-rounded", "color": "#111111", "opacity": 0.65 },
    "outline": { "color": "#000000", "thickness": 2 },
    "shadow": { "enabled": true, "color": "#000000", "blur": 8, "distance": 0 }
  }
}

Field	Accepted values	Behavior
`position`	`top`, `center`, `bottom`	Vertical placement.
`horizontal_position`	`left`, `center`, `right`	Placement of the whole caption block.
`text_alignment`	`left`, `center`, `right`	Alignment of lines within that block.
`text_color`	Six-digit hex color	Text fill.
`highlight_color`	Six-digit hex color	Preset-specific active-word effect; see below.
`font_family`	Bundled font name below	Font family.
`font_size`	Number, 12–240	Explicit font size on the 1080px caption canvas, before scaling. Overrides the size derived from `text_width`.
`font_weight`	`400`, `700`	Regular or bold. Thin&Bold animates its own weights.
`font_style`	`normal`, `italic`	Font style; browser synthesis is used when the font has no italic face.
`text_case`	`none`, `uppercase`, `lowercase`, `capitalize`	Visual casing. `capitalize` uppercases each word’s first character. Downloads preserve the source words.
`text_width`	`small`, `medium`, `large`	Text density: small uses larger type and fewer words per line. Ignored with explicit `font_size`.
`line_count`	`0`, `1`, `2`, `3`, `100`	Maximum lines per cue. `0` means one word at a time. `100` allows up to 100 lines; use cautiously on small videos.
`scale`	Number, 0.2–1	Base caption scale, multiplied by video width / 1080. Defaults to the preset’s scale for portrait/square and 0.55 for landscape.
`offset`	Object with optional `left`, `top`, `right`, `bottom`, each −1920–1920	Pixel offsets in output-video coordinates. Horizontal movement is left minus right; vertical movement is top minus bottom.
`background`	Object with optional `type`, `color`, `opacity`	Type: `none`, `line`, `line-rounded`, `box`, `box-rounded`. Color: hex. Opacity: 0–1. Set a type to enable.
`outline`	Object with optional `color`, `thickness`	Color: hex. Thickness: 0–20 caption-canvas pixels; 0 disables the outline.
`shadow`	Object with optional `enabled`, `color`, `blur`, `distance`, `angle`	Enabled: boolean. Color: hex. Blur: 0–40. Distance: 0–20. Angle: −180–180 degrees.

Bundled fonts: Inter, Urbanist, Rubik, Bangers, Paytone One, Slackey, Permanent Marker, Caveat Brush, Zilla Slab, Young Serif, Instrument Serif, Bebas Neue, and Coiny. Fonts without a native bold face use browser synthesis. Unknown fields (including nested ones), shorthand colors, alpha hex values, named colors, and out-of-range numbers return 400 INVALID_REQUEST. Background transparency uses background.opacity.

Properties that depend on the preset

The style object is shared across presets. Discover applicable fields through each preset’s supported_style_fields, and read style_notes for special behavior. This lets clients display the appropriate controls without hardcoding preset rules or accepting arbitrary renderer properties.

Preset	Special behavior
`highlight`, `push`, `action`	`highlight_color` changes the active word’s text.
`box`	`highlight_color` changes the animated box behind the active word. `background` separately controls the background behind the whole caption or its lines.
`karaoke`	`highlight_color` changes the progressive fill. Text and outline default to the preset’s white; set `text_color` explicitly to change the unspoken text.
`smash`	Defaults to `line_count: 0`. Set 1, 2, or 3 to group words into lines.
`thin&bold`	The animation controls weights 200 and 700; `font_weight` has no effect.
`prompter`	Highlights with opacity, so `highlight_color` has no effect.

For compatibility, highlight_color remains accepted for every preset; it has no visual effect outside the five color-highlight presets. Other common controls remain available even when their effect is disabled by default. For example, any preset can enable a background or a shadow. The preset selects its animation. Arbitrary animation settings, custom font URLs, derived shadow coordinates, and watermark controls are not accepted. API renders have no watermark.

Sizing and defaults

Each preset defines its font, text-width, outline, shadow, background, scale and animation defaults. Portrait and square videos use the preset’s text width and base scale. Landscape videos initialize with text_width: "large" and base scale 0.55. Explicit text_width and scale overrides take precedence over those orientation defaults. The final scale is the base scale multiplied by video width / 1080, including for videos wider than 1080px. When font_size is omitted, the API derives it from the resolved font family and text width. Catalog defaults describe the preset before landscape adaptation or resolution scaling; defaults.font_size reports the derived size for that preset’s text width. Send only fields you want to override: copying an explicit size into a request will prevent a later text_width change from adjusting it. Top and bottom placement add an inset to the preset’s offset on the selected edge: 20% of video height for portrait/square and 14% for landscape. An explicit offset.top or offset.bottom replaces that edge’s complete resolved offset, including an explicit zero. Catalog defaults omit those two dimensions because they depend on the video. For shadows, angle 0 points down and angle 90 points right. Shadow position is derived automatically when distance or angle changes.

Set the spoken language

Omit language for automatic detection, or pass a lowercase two- or three-letter language code, such as en or fra, supported by the transcription service. The API transcribes speech in the source language; it does not translate.

Get started

Captions

Account

Guides

Resources

Choose a preset

Customize the style

Properties that depend on the preset

Sizing and defaults

Set the spoken language

​Choose a preset

​Customize the style

​Properties that depend on the preset

​Sizing and defaults

​Set the spoken language

Choose a preset

Customize the style

Properties that depend on the preset

Sizing and defaults

Set the spoken language