> ## Documentation Index
> Fetch the complete documentation index at: https://docs.captioncraft.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Caption styles

> All 16 caption presets, with typography, layout, background, outline and shadow controls.

## 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](/api-reference/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.

```json theme={"system"}
{
  "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.