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

# Save a text preset

`POST /v1/text-presets`

## Request

- Base URL: `https://api.tella.com`
- URL: `https://api.tella.com/v1/text-presets`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/withchima/apis/tella-public-api/docs/v1/text-presets/post.ts> (a function with typed inputs; its response is checked against the schema)

Saves a personal text preset, like the editor's "Save style" on a text overlay. The style starts from an existing text overlay when `videoId` and `textOverlayId` are given (keeping a custom font and reading the size relative to that video's canvas), else from the editor's default text look; every style field sent alongside overrides it. The preset then appears in GET /v1/text-presets and in the editor's Text panel.

## Request body

- SaveTextPresetRequest: Save a personal text preset. The style starts from the given text overlay, else from the editor's default text look; every style field sent alongside overrides it.
  - `background` TextOverlayBackground: Background behind a text overlay, in the same object shape as a clip background.
    - `color` string, required: Hex color string. Required when type = 'solid'. Transparent backgrounds use #00000000.
    - `type` 'solid', required: Background variant. Text overlays take a solid background; the other `ClipBackground` variants are not supported behind text.
  - `backgroundPadding` number: Extra room around the text inside its background, as a fraction of the font size added on every side (0.5 at an 80px font adds 40px). 0 is the standard padding. No effect without a visible background.
  - `backgroundShape` 'none' | 'regular' | 'squircle': Shape of the solid background behind the text.
  - `color` string: Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
  - `fontFamily` 'Inter' | 'Roboto Mono' | 'Archivo' | 'Barlow' | 'Caveat' | 'DM Sans' | 'Figtree' | 'Lora' | 'Merriweather' | 'Montserrat' | 'Nunito Sans' | 'Open Sans' | 'Oswald' | 'Playfair Display' | 'Poppins' | 'Raleway' | 'Roboto' | 'Roboto Flex' | 'Source Sans 3' | 'Space Grotesk': One of Tella's catalog font families — the same list the editor's font picker offers.
  - `fontSizeScale` number: Font size relative to the editor's default (7.5% of the canvas's shorter side): 1 is the default, 0.6 a caption, 1.4 a headline. Presets are video-independent, so this is a scale rather than pixels; adding an overlay resolves it for the video it lands on.
  - `fontWeight` number
  - `fontWidth` number
  - `letterSpacing` number: Tracking: space between letters, as a fraction of the font size (-0.05 at an 80px font pulls letters 4px closer; 0.1 spreads them 8px apart). Negative tightens; 0 is the font's own spacing.
  - `name` string, required
  - `outline` string, nullable: Color of the outline (stroke) drawn around the letters, or null for no outline.
  - `textAlign` 'left' | 'center' | 'right': Horizontal alignment of the text inside its overlay box.
  - `textOverlayId` string: Text overlay to copy the style from, keeping a custom font and reading its size relative to that video's canvas. Goes together with `videoId`.
  - `videoId` string: Video holding the text overlay to copy the style from. Goes together with `textOverlayId`.

## Response `200`

Preset saved

- object
  - `preset` TextPreset, required
    - `name` string, required
    - `presetId` string, required: Pass this ID as `presetId` when adding or updating a text overlay
    - `scope` 'default' | 'personal', required: `default` for Tella's built-in styles, `personal` for presets saved by the authenticated user
    - `style` TextPresetStyle, required: Everything about a text overlay except its text, timing and placement.
      - `background` TextOverlayBackgroundOutput, required: Background behind a text overlay, in the same object shape as a clip background.
        - `color` string, required: Hex color string. Required when type = 'solid'. Transparent backgrounds use #00000000.
        - `type` 'solid', required: Background variant. Text overlays take a solid background; the other `ClipBackground` variants are not supported behind text.
      - `backgroundPadding` number, required: Extra room around the text inside its background, as a fraction of the font size added on every side (0.5 at an 80px font adds 40px). 0 is the standard padding. No effect without a visible background.
      - `backgroundShape` 'none' | 'regular' | 'squircle', required: Shape of the solid background behind the text.
      - `color` string, required: Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
      - `fontFamily` string, required
      - `fontSizeScale` number, required: Font size relative to the editor's default (7.5% of the canvas's shorter side): 1 is the default, 0.6 a caption, 1.4 a headline. Presets are video-independent, so this is a scale rather than pixels; adding an overlay resolves it for the video it lands on.
      - `fontWeight` number, required
      - `fontWidth` number, required
      - `letterSpacing` number, required: Tracking: space between letters, as a fraction of the font size (-0.05 at an 80px font pulls letters 4px closer; 0.1 spreads them 8px apart). Negative tightens; 0 is the font's own spacing.
      - `outline` string, nullable, required: Color of the outline (stroke) drawn around the letters, or null for no outline.
      - `textAlign` 'left' | 'center' | 'right', required: Horizontal alignment of the text inside its overlay box.

## 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

> 72 revisions in range; 1 not diffed.

- **2026-11-07** `0cc3fcd307ad`: 2 info
  - added the new optional request property `letterSpacing`
  - added the required property `preset/style/letterSpacing` to the response with the `200` status
- **2026-10-30** `0b2b8234a7db`: 2 info
  - added the new optional request property `backgroundPadding`
  - added the required property `preset/style/backgroundPadding` to the response with the `200` status
- **2026-10-04** `b00a18d1655e`: 2 info
  - added the new optional request property `outline`
  - added the required property `preset/style/outline` to the response with the `200` status
- **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

[Operation history](https://skmtc.dev/withchima/apis/tella-public-api/changes/v1/text-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/ca74daaf9201?raw)