---
title: "Save a subtitle preset"
method: POST
path: "/v1/subtitle-presets"
tags: ["Videos"]
---

# Save a subtitle preset

`POST /v1/subtitle-presets`

Saves a subtitle look as a personal preset, like the editor's "Save as preset". Pass `videoId` to snapshot that video's current subtitles (style, font, weight, size, position, grouping and lines per block), `captionStyle` to build one from scratch on the style's defaults, or both — explicit caption fields override the video's. Omit `name` for the editor's default (the matching built-in's name, numbered). The preset then appears in GET /v1/subtitle-presets and in the editor's Subtitles panel, and can be applied to other videos with PUT /v1/videos/{id}/subtitle-preset.

## Request body

- SaveSubtitlePresetRequest — A subtitle look to save. Pass `videoId` to snapshot a video's current subtitles, `captionStyle` to build one from scratch, or both — explicit caption fields override the video's.
  - `captionFontFamily` string — Subtitle font family. On write, one of Tella's catalog font families (the list the editor's font picker offers, and the same one `fontFamily` accepts on text overlays), or the video's current family to keep an uploaded font. Reads report the family the subtitles render with, which on videos styled before the catalog can be a legacy bundled family such as `Arial`.
  - `captionFontSize` number — Exact subtitle text size, 40 to 200 — the editor's Size slider. `captionSize` is the same setting in buckets (small 40, medium 64, large 80), so a request passes one or the other, not both.
  - `captionFontWeight` number — Variable-font weight axis — 100 (thin) to 1000. Clamped to the range the family supports, so a read reports the weight that renders. Sent without `captionFontFamily`, it re-weights the video's current font.
  - `captionGrouping` 'chunked' | 'singleWord' — How subtitle text is grouped: sentence chunks or one word at a time. Defaults to the video's, or chunked.
  - `captionLinesPerBlock` integer — Lines a caption block may span when `captionGrouping` is `chunked`: 1, 2, or 3, or 0 for no limit, where blocks only break on pauses and sentence ends.
  - `captionPosition` CaptionPosition — Normalized subtitle position. Applies if subtitles are enabled on the video. Null uses automatic placement.
    - `x` number, required
    - `y` number, required
  - `captionSize` 'small' | 'medium' | 'large' — Subtitle text size. Defaults to the video's, or the style's default. Pass this or `captionFontSize`, not both.
  - `captionStyle` union — Subtitle style. Applies if subtitles are enabled on the video. Background, shadow, and outline colors and toggles are available on every style.
    - object
      - `activeWordTextColor` string — Text color of the spoken word when highlightMode is background. Defaults to textColor.
      - `backgroundColor` string, required — Caption background color in #RRGGBB or #RRGGBBAA form. Its alpha channel is rendered exactly; #RRGGBB is fully opaque. Responses use uppercase #RRGGBBAA and report the effective rendered color.
      - `backgroundEnabled` boolean
      - `highlightColor` string — Spoken-word color. Omit to retain the legacy text-opacity progression.
      - `highlightMode` 'text' | 'background' | 'fadeRest' — How the spoken word is emphasized. Defaults to text.
      - `name` 'backdrop', required
      - `outlineColor` string — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `outlineEnabled` boolean
      - `shadowColor` string — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `shadowEnabled` boolean
      - `textCase` 'original' | 'uppercase' | 'lowercase' — Letter case applied to every caption word. Defaults to original.
      - `textColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `wordLevelHighlights` boolean, required
    - object
      - `backgroundColor` string — Caption background color in #RRGGBB or #RRGGBBAA form. Its alpha channel is rendered exactly; #RRGGBB is fully opaque. Responses use uppercase #RRGGBBAA and report the effective rendered color.
      - `backgroundEnabled` boolean
      - `highlightColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `highlightMode` 'text' | 'background' | 'fadeRest' — How the spoken word is emphasized. Defaults to background.
      - `name` 'highlight', required
      - `outlineColor` string — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `outlineEnabled` boolean
      - `primaryTextColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `secondaryTextColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `shadowColor` string — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `shadowEnabled` boolean
      - `textCase` 'original' | 'uppercase' | 'lowercase' — Letter case applied to every caption word. Defaults to original.
      - `wordLevelHighlights` boolean — Highlight each word as it is spoken. Defaults to true.
    - object
      - `activeWordTextColor` string — Text color of the spoken word when highlightMode is background. Defaults to textColor.
      - `backgroundColor` string — Caption background color in #RRGGBB or #RRGGBBAA form. Its alpha channel is rendered exactly; #RRGGBB is fully opaque. Responses use uppercase #RRGGBBAA and report the effective rendered color.
      - `backgroundEnabled` boolean
      - `highlightColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `highlightMode` 'text' | 'background' | 'fadeRest' — How the spoken word is emphasized. Defaults to text.
      - `name` 'mono', required
      - `outlineColor` string — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `outlineEnabled` boolean
      - `shadowColor` string — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `shadowEnabled` boolean
      - `textCase` 'original' | 'uppercase' | 'lowercase' — Letter case applied to every caption word. Defaults to original.
      - `textColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `wordLevelHighlights` boolean — Highlight each word as it is spoken. Defaults to true.
    - object
      - `activeWordTextColor` string — Text color of the spoken word when highlightMode is background. Defaults to textColor.
      - `backgroundColor` string — Caption background color in #RRGGBB or #RRGGBBAA form. Its alpha channel is rendered exactly; #RRGGBB is fully opaque. Responses use uppercase #RRGGBBAA and report the effective rendered color.
      - `backgroundEnabled` boolean
      - `highlightColor` string — Spoken-word color. Defaults to textColor.
      - `highlightMode` 'text' | 'background' | 'fadeRest' — How the spoken word is emphasized. Defaults to text.
      - `name` 'cannes', required
      - `outlineColor` string — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `outlineEnabled` boolean
      - `shadowColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `shadowEnabled` boolean
      - `textCase` 'original' | 'uppercase' | 'lowercase' — Letter case applied to every caption word. Defaults to original.
      - `textColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `wordLevelHighlights` boolean — Highlight each word as it is spoken. Defaults to false.
    - object
      - `activeWordTextColor` string — Text color of the spoken word when highlightMode is background. Defaults to textColor.
      - `backgroundColor` string — Caption background color in #RRGGBB or #RRGGBBAA form. Its alpha channel is rendered exactly; #RRGGBB is fully opaque. Responses use uppercase #RRGGBBAA and report the effective rendered color.
      - `backgroundEnabled` boolean
      - `highlightColor` string — Spoken-word color. Defaults to textColor.
      - `highlightMode` 'text' | 'background' | 'fadeRest' — How the spoken word is emphasized. Defaults to text.
      - `name` 'classic', required
      - `outlineColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `outlineEnabled` boolean
      - `shadowColor` string — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `shadowEnabled` boolean
      - `textCase` 'original' | 'uppercase' | 'lowercase' — Letter case applied to every caption word. Defaults to original.
      - `textColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `wordLevelHighlights` boolean — Highlight each word as it is spoken. Defaults to false.
  - `name` string — Preset name, as shown in the editor. Defaults to the matching built-in's name, numbered past any saved preset already using it.
  - `videoId` string — Video whose current subtitle look to start from. Omit to build the preset from `captionStyle` and the style's defaults.

## Response `200`

Preset saved

- object
  - `preset` SubtitlePreset, required
    - `captionStyle` union, required — Subtitle style. Applies if subtitles are enabled on the video. Background, shadow, and outline colors and toggles are available on every style.
      - object
        - `activeWordTextColor` string — Text color of the spoken word when highlightMode is background. Defaults to textColor.
        - `backgroundColor` string, required — Caption background color in #RRGGBB or #RRGGBBAA form. Its alpha channel is rendered exactly; #RRGGBB is fully opaque. Responses use uppercase #RRGGBBAA and report the effective rendered color.
        - `backgroundEnabled` boolean
        - `highlightColor` string — Spoken-word color. Omit to retain the legacy text-opacity progression.
        - `highlightMode` 'text' | 'background' | 'fadeRest' — How the spoken word is emphasized. Defaults to text.
        - `name` 'backdrop', required
        - `outlineColor` string — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
        - `outlineEnabled` boolean
        - `shadowColor` string — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
        - `shadowEnabled` boolean
        - `textCase` 'original' | 'uppercase' | 'lowercase' — Letter case applied to every caption word. Defaults to original.
        - `textColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
        - `wordLevelHighlights` boolean, required
      - object
        - `backgroundColor` string — Caption background color in #RRGGBB or #RRGGBBAA form. Its alpha channel is rendered exactly; #RRGGBB is fully opaque. Responses use uppercase #RRGGBBAA and report the effective rendered color.
        - `backgroundEnabled` boolean
        - `highlightColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
        - `highlightMode` 'text' | 'background' | 'fadeRest' — How the spoken word is emphasized. Defaults to background.
        - `name` 'highlight', required
        - `outlineColor` string — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
        - `outlineEnabled` boolean
        - `primaryTextColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
        - `secondaryTextColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
        - `shadowColor` string — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
        - `shadowEnabled` boolean
        - `textCase` 'original' | 'uppercase' | 'lowercase' — Letter case applied to every caption word. Defaults to original.
        - `wordLevelHighlights` boolean — Highlight each word as it is spoken. Defaults to true.
      - object
        - `activeWordTextColor` string — Text color of the spoken word when highlightMode is background. Defaults to textColor.
        - `backgroundColor` string — Caption background color in #RRGGBB or #RRGGBBAA form. Its alpha channel is rendered exactly; #RRGGBB is fully opaque. Responses use uppercase #RRGGBBAA and report the effective rendered color.
        - `backgroundEnabled` boolean
        - `highlightColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
        - `highlightMode` 'text' | 'background' | 'fadeRest' — How the spoken word is emphasized. Defaults to text.
        - `name` 'mono', required
        - `outlineColor` string — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
        - `outlineEnabled` boolean
        - `shadowColor` string — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
        - `shadowEnabled` boolean
        - `textCase` 'original' | 'uppercase' | 'lowercase' — Letter case applied to every caption word. Defaults to original.
        - `textColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
        - `wordLevelHighlights` boolean — Highlight each word as it is spoken. Defaults to true.
      - object
        - `activeWordTextColor` string — Text color of the spoken word when highlightMode is background. Defaults to textColor.
        - `backgroundColor` string — Caption background color in #RRGGBB or #RRGGBBAA form. Its alpha channel is rendered exactly; #RRGGBB is fully opaque. Responses use uppercase #RRGGBBAA and report the effective rendered color.
        - `backgroundEnabled` boolean
        - `highlightColor` string — Spoken-word color. Defaults to textColor.
        - `highlightMode` 'text' | 'background' | 'fadeRest' — How the spoken word is emphasized. Defaults to text.
        - `name` 'cannes', required
        - `outlineColor` string — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
        - `outlineEnabled` boolean
        - `shadowColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
        - `shadowEnabled` boolean
        - `textCase` 'original' | 'uppercase' | 'lowercase' — Letter case applied to every caption word. Defaults to original.
        - `textColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
        - `wordLevelHighlights` boolean — Highlight each word as it is spoken. Defaults to false.
      - object
        - `activeWordTextColor` string — Text color of the spoken word when highlightMode is background. Defaults to textColor.
        - `backgroundColor` string — Caption background color in #RRGGBB or #RRGGBBAA form. Its alpha channel is rendered exactly; #RRGGBB is fully opaque. Responses use uppercase #RRGGBBAA and report the effective rendered color.
        - `backgroundEnabled` boolean
        - `highlightColor` string — Spoken-word color. Defaults to textColor.
        - `highlightMode` 'text' | 'background' | 'fadeRest' — How the spoken word is emphasized. Defaults to text.
        - `name` 'classic', required
        - `outlineColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
        - `outlineEnabled` boolean
        - `shadowColor` string — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
        - `shadowEnabled` boolean
        - `textCase` 'original' | 'uppercase' | 'lowercase' — Letter case applied to every caption word. Defaults to original.
        - `textColor` string, required — Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
        - `wordLevelHighlights` boolean — Highlight each word as it is spoken. Defaults to false.
    - `name` string, required
    - `presetId` string, required — Pass this ID to PUT /v1/videos/{id}/subtitle-preset
    - `scope` 'default' | 'personal', required

## Other responses

- `400` — The request was malformed or contained invalid parameters.
- `401` — Authentication is required. Provide a valid API key.
- `403` — You don't have permission to access this resource.
- `404` — The requested resource was not found.
- `409` — The request conflicts with the resource's current state, e.g. an Idempotency-Key whose first request is still in progress. Retry once it settles.
- `429` — You have exceeded the rate limit. Please slow down.
- `500` — An unexpected error occurred
- `501` — The requested operation is not implemented.
- `503` — A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay.

## Changes

> 18 revisions in range; 1 not diffed.

- **2026-09-28** `ac47c99c144f` — 9 warning
  - added the new `edit_conflict` enum value to the `error` response property for the response status `400`
  - added the new `edit_conflict` enum value to the `error` response property for the response status `401`
  - added the new `edit_conflict` enum value to the `error` response property for the response status `403`
  - added the new `edit_conflict` enum value to the `error` response property for the response status `404`
  - …5 more
- **2026-09-21** `e70780c11bde` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/withchima/apis/tella-public-api/changes/v1/subtitle-presets/post.md)

---

[API](https://skmtc.dev/withchima/apis/tella-public-api.md) · [All operations](https://skmtc.dev/withchima/apis/tella-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/withchima/apis/tella-public-api/revisions/704d6fc3bc60?raw)