# List presets
Source: https://captioncraft.mintlify.app/api-reference/list-presets
Discover caption presets, their default styles, and applicable controls.
## Request
`GET /v1/presets` is public and does not require an API key. Use the API endpoint provided with your account:
```bash theme={null}
curl --fail-with-body "$CAPTIONCRAFT_API_URL/v1/presets"
```
The response contains a `presets` array with all 16 presets. Use an entry's `id` as the `preset` in a `POST /v1/subtitles` request.
| Field | Meaning |
| ------------------------ | ------------------------------------------------------------------------------------------------ |
| `id` | Preset identifier accepted by the subtitles endpoint. |
| `name` | Display name. |
| `description` | Description of the caption's appearance. |
| `animation` | The preset's fixed animation. Read-only. |
| `defaults` | The preset's initial style, using the same property names and nested objects as request `style`. |
| `supported_style_fields` | Style fields that affect this preset. |
| `style_notes` | Explanations of preset-specific controls and exceptions. |
## Apply overrides
Start a request with the preset ID and send only the properties you want to change. You do not need to copy `defaults` into your request.
```json theme={null}
{
"video_url": "https://your-cdn.example/video.mp4",
"preset": "box",
"style": {
"highlight_color": "#FF8800"
}
}
```
This changes Box's animated active-word box color while preserving its other defaults. Omit `style`, send `{}`, or send empty nested objects to retain the resolved preset defaults. An omitted `preset` selects `classic`.
Partial nested objects override only supplied fields. For example, `outline: { "color": "#FF0000" }` retains the preset's outline thickness.
## Understand catalog defaults
Catalog values describe the preset before adaptation to the video's dimensions:
* Portrait and square videos use the preset's text width and base scale.
* Landscape videos start with `text_width: "large"` and base scale `0.55`.
* The final scale is the base scale multiplied by video width / 1080.
* `defaults.font_size` is derived from the preset's font family and text width. Omit `font_size` in requests to let it follow the resolved font and text width.
* The catalog omits `offset.top` and `offset.bottom` because their resolved defaults depend on video height and placement.
Explicit overrides take precedence over these defaults. See [Caption styles](/caption-styles) for all accepted values, edge offsets, and preset-specific behavior.
# Caption styles
Source: https://captioncraft.mintlify.app/caption-styles
Preset defaults, style overrides, and controls for all 16 caption templates.
## 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.
## Use the preset defaults
Send your request to `POST /v1/subtitles`. Omit `style` to use the selected preset's defaults:
```json theme={null}
{
"video_url": "https://your-cdn.example/video.mp4",
"preset": "glow",
"max_duration_seconds": 60
}
```
Omitting `preset` selects `classic`. Requests require a Bearer API key with the `subtitles:write` scope, an `Idempotency-Key` header, and `Content-Type: application/json`.
## 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.
For example, this request changes only the outline color. The preset's outline thickness and other properties are retained:
```json theme={null}
{
"video_url": "https://your-cdn.example/video.mp4",
"preset": "glow",
"style": {
"outline": { "color": "#FF0000" }
}
}
```
Explicit `0` and `false` values are overrides. For example, `outline.thickness: 0` disables an outline and `shadow.enabled: false` disables a shadow. `null` is not accepted; omit a field to inherit its default.
To customize several properties:
```json theme={null}
{
"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.
# Introduction
Source: https://captioncraft.mintlify.app/index
Welcome to your project
Write a short description of your product here. What it does, who it's for, and what they can accomplish with it.
Ready to make this your own? Start by editing this page. Update your `docs.json` file to customize your site. Then fill out the [Quickstart](/quickstart) page.
This card links to the quickstart page in your project.
Add cards, callouts, steps, tabs, and more to design and structure your pages.
Set your site name, branding, and navigation in the `docs.json` file.
# Quickstart
Source: https://captioncraft.mintlify.app/quickstart
Begin with a guide on the fastest path to a successful outcome
Describe how someone begins using your product. What is the first thing they need to do? Are there any prerequisites?
A quickstart should take someone from zero to using your product. They'll get a quick win and a sense of what they can accomplish.
## Prerequisites
Before you begin, you must have:
* Requirement one (for example, Node.js 18+, a free account, an API key)
* Requirement two (for example, a compatible device, a compatible browser, a compatible operating system)
## Get started
Describe how to install your product or sign up.
```bash theme={null}
npm install your-package
```
Describe any setup or configuration needed before first use.
```bash theme={null}
your-cli init
```
Show the first thing a user does to see it working.
```bash theme={null}
your-cli start
```
Give people a way to get help. This could be a link to a support page, a chat with a customer support agent, or a forum for your product.
Example: Need help? Reach out to us at [support@yourcompany.com](mailto:support@yourcompany.com).