Skip to main content

Choose a preset

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.
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. 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. Font size is always derived from the resolved font_family and text_width. Use text_width and scale to adjust caption sizing. Horizontal caption placement follows the preset; text_alignment controls only the alignment of lines within that block. Direct font-size and horizontal-placement overrides (style.font_size and style.horizontal_position, corresponding to renderer fontSize and alignX) are not supported and return 400 INVALID_REQUEST. Renderer-only properties such as fontSizeOverride and alignX are also rejected. Catalog defaults describe supported controls before landscape adaptation or resolution scaling. 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. When you supply an SRT file, transcription is skipped and language is ignored.