> ## Documentation Index > Fetch the complete documentation index at: https://www.tella.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Update a text overlay > Update a text overlay's copy, font, color, timing, position, or dimensions. Only the fields you send are changed. ## OpenAPI ````yaml /openapi.json patch /v1/videos/{id}/clips/{clipId}/text-overlays/{textOverlayId} openapi: 3.0.3 info: description: >- The Tella Public API allows you to programmatically access your videos and playlists, including transcripts, chapters, and thumbnails. ## Authentication All requests require a Bearer token in the Authorization header: ``` Authorization: Bearer tella_pk_xxxxx... ``` API keys can be generated in your Tella workspace settings. ## Rate Limiting The API is rate-limited to 100 requests per minute per user within a workspace. Rate limit information is returned in response headers: - `RateLimit-Policy`: Named quota, request limit, and window in seconds - `RateLimit`: Remaining quota and seconds until reset - `X-RateLimit-Limit`: Maximum requests per window - `X-RateLimit-Remaining`: Remaining requests in current window - `X-RateLimit-Reset`: Unix timestamp in milliseconds when the window resets A `429 Too Many Requests` response also includes `Retry-After` in seconds. title: Tella Public API version: 1.0.0 servers: - description: Production url: https://api.tella.com security: [] tags: - description: Video operations name: Videos - description: Sections of a video name: Clips - description: Playlist operations name: Playlists - description: Sidebar groups for organizing playlists name: Playlist Groups - description: Tags for categorizing and filtering videos name: Tags - description: Personal, workspace, and default video backgrounds name: Backgrounds - description: >- Reusable media saved to a workspace, plus Tella's curated sound effect catalog — the same items the editor's media panels show name: Library - description: Webhook endpoint management name: Webhooks externalDocs: description: API versioning and deprecation policy url: https://www.tella.com/docs/versioning paths: /v1/videos/{id}/clips/{clipId}/text-overlays/{textOverlayId}: patch: tags: - Clips summary: Update a text overlay description: >- Update a text overlay's copy, font, color, timing, position, or dimensions. Only the fields you send are changed. operationId: updateClipTextOverlay parameters: - description: Video ID in: path name: id required: true schema: description: Video ID type: string - description: Clip ID in: path name: clipId required: true schema: description: Clip ID type: string - description: Text overlay ID in: path name: textOverlayId required: true schema: description: Text overlay ID type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateClipTextOverlayRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ClipTextOverlayResponse' description: OK headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '400': content: application/json: example: docsUrl: https://docs.tella.com/ error: bad_request message: The request was malformed or contained invalid parameters. schema: $ref: '#/components/schemas/ErrorResponse' description: The request was malformed or contained invalid parameters. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '401': content: application/json: example: docsUrl: https://docs.tella.com/ error: unauthorized message: Authentication is required. Provide a valid API key. schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication is required. Provide a valid API key. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '403': content: application/json: example: docsUrl: https://docs.tella.com/ error: forbidden message: You don't have permission to access this resource. schema: $ref: '#/components/schemas/ErrorResponse' description: You don't have permission to access this resource. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '404': content: application/json: example: docsUrl: https://docs.tella.com/ error: not_found message: The requested resource was not found. schema: $ref: '#/components/schemas/ErrorResponse' description: The requested resource was not found. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '429': content: application/json: example: docsUrl: https://docs.tella.com/ error: rate_limited message: You have exceeded the rate limit. Please slow down. schema: $ref: '#/components/schemas/ErrorResponse' description: You have exceeded the rate limit. Please slow down. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Retry-After: $ref: '#/components/headers/RetryAfter' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '500': content: application/json: example: docsUrl: https://docs.tella.com/ error: server_error message: An unexpected error occurred schema: $ref: '#/components/schemas/ErrorResponse' description: An unexpected error occurred headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '501': content: application/json: example: docsUrl: https://docs.tella.com/ error: not_implemented message: The requested operation is not implemented. schema: $ref: '#/components/schemas/ErrorResponse' description: The requested operation is not implemented. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' security: - BearerAuth: [] components: schemas: UpdateClipTextOverlayRequest: additionalProperties: false description: Update an existing text overlay minProperties: 1 properties: background: allOf: - $ref: '#/components/schemas/TextOverlayBackground' backgroundShape: allOf: - $ref: '#/components/schemas/TextOverlayBackgroundShape' color: description: >- Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA. example: '#FFFFFFFF' pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$ type: string dimensions: allOf: - $ref: '#/components/schemas/OverlayDimensions' durationMs: exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 type: integer fontFamily: allOf: - $ref: '#/components/schemas/TextOverlayFontFamily' fontSize: description: Font size in artboard pixels. exclusiveMinimum: true minimum: 0 type: number fontWeight: maximum: 1000 minimum: 1 type: number fontWidth: exclusiveMinimum: true minimum: 0 type: number point: allOf: - $ref: '#/components/schemas/OverlayPoint' startTimeMs: description: >- Start time. Milliseconds on the clip playback timeline (with cuts applied) — the same timeline as the cut transcript. maximum: 9007199254740991 minimum: 0 type: integer text: minLength: 1 type: string textAlign: allOf: - $ref: '#/components/schemas/TextOverlayTextAlign' transition: allOf: - $ref: '#/components/schemas/TransitionStyle' description: >- Intro/outro animation: `smooth` fades the text in at its start and out at its end, `hard_cut` pops it in and out. type: object ClipTextOverlayResponse: additionalProperties: false description: A text overlay on a clip properties: textOverlay: $ref: '#/components/schemas/ClipTextOverlay' required: - textOverlay type: object ErrorResponse: additionalProperties: false description: Standard error response format properties: docsUrl: description: Link to Tella API documentation example: https://docs.tella.com/ format: uri type: string error: description: Machine-readable error code enum: - bad_request - unauthorized - forbidden - not_found - rate_limited - server_error - not_implemented example: not_found type: string message: description: Human-readable error message example: Resource not found type: string required: - error - message - docsUrl type: object TextOverlayBackground: description: >- Background behind a text overlay, in the same object shape as a clip background. properties: color: description: >- Hex color string. Required when type = 'solid'. Transparent backgrounds use #00000000. example: '#5E51F8FF' pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$ type: string type: description: >- Background variant. Text overlays take a solid background; the other `ClipBackground` variants are not supported behind text. enum: - solid example: solid type: string required: - type - color type: object TextOverlayBackgroundShape: description: Shape of the solid background behind the text. enum: - none - regular - squircle example: squircle type: string OverlayDimensions: description: >- Overlay size in artboard pixels. Absolute (not a percentage) so the overlay shape never distorts when the artboard dimensions change. Both sides must be greater than 0 — the renderer lays the overlay out into this box, so a zero or negative side has no valid meaning. properties: height: example: 540 exclusiveMinimum: true minimum: 0 type: number width: example: 960 exclusiveMinimum: true minimum: 0 type: number required: - width - height type: object TextOverlayFontFamily: description: >- One of Tella's catalog font families — the same list the editor's font picker offers. enum: - 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 example: Inter type: string OverlayPoint: description: >- Top-left corner of the overlay, as a percentage of the video canvas (0-100). Relative so the anchor survives video aspect ratio changes. properties: xPct: example: 30 type: number yPct: example: 30 type: number required: - xPct - yPct type: object TextOverlayTextAlign: description: Horizontal alignment of the text inside its overlay box. enum: - left - center - right example: center type: string TransitionStyle: description: >- How one thing gives way to the next: `smooth` eases across the change, `hard_cut` swaps instantly. enum: - smooth - hard_cut example: smooth type: string ClipTextOverlay: additionalProperties: false description: >- A text overlay on a clip. Unlike image and video overlays it references no source — the copy and its font live on the overlay itself. properties: background: allOf: - $ref: '#/components/schemas/TextOverlayBackgroundOutput' description: >- Background behind the text. Overlays with no visible box report a solid #00000000. backgroundShape: $ref: '#/components/schemas/TextOverlayBackgroundShape' color: description: >- Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA. example: '#FFFFFFFF' pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$ type: string dimensions: $ref: '#/components/schemas/OverlayDimensionsOutput' durationMs: example: 5000 minimum: 0 type: number fontFamily: description: >- The overlay's font family. Normally one of the catalog families accepted on write, but overlays created before that catalog can report another bundled family, such as `Graphik`. example: Inter type: string fontSize: description: >- Font size in artboard pixels — absolute, like `dimensions`, so text keeps its size relative to the frame. Renderers scale it by their render scale factor. example: 81 exclusiveMinimum: true minimum: 0 type: number fontWeight: description: Variable-font weight axis — 100 (thin) to 900 (black). example: 500 type: number fontWidth: description: >- Variable-font width axis, as a percentage — 100 is normal, 50 ultra-condensed, 150 extra-expanded. example: 100 type: number id: description: Text overlay ID example: ly_abc123 type: string point: $ref: '#/components/schemas/OverlayPointOutput' startTimeMs: description: >- Start time. Milliseconds on the clip playback timeline (with cuts applied) — the same timeline as the cut transcript. example: 1000 minimum: 0 type: number text: example: Welcome back type: string textAlign: $ref: '#/components/schemas/TextOverlayTextAlign' transition: allOf: - $ref: '#/components/schemas/TransitionStyle' description: >- Intro/outro animation: `smooth` fades the text in at its start and out at its end, `hard_cut` pops it in and out. New text overlays start on `hard_cut`. example: hard_cut required: - id - text - fontFamily - fontSize - color - fontWeight - fontWidth - textAlign - background - backgroundShape - startTimeMs - durationMs - point - dimensions - transition type: object TextOverlayBackgroundOutput: additionalProperties: false description: >- Background behind a text overlay, in the same object shape as a clip background. properties: color: description: >- Hex color string. Required when type = 'solid'. Transparent backgrounds use #00000000. example: '#5E51F8FF' pattern: ^#(?:[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$ type: string type: description: >- Background variant. Text overlays take a solid background; the other `ClipBackground` variants are not supported behind text. enum: - solid example: solid type: string required: - type - color type: object OverlayDimensionsOutput: additionalProperties: false description: >- Overlay size in artboard pixels. Absolute (not a percentage) so the overlay shape never distorts when the artboard dimensions change. Both sides must be greater than 0 — the renderer lays the overlay out into this box, so a zero or negative side has no valid meaning. properties: height: example: 540 exclusiveMinimum: true minimum: 0 type: number width: example: 960 exclusiveMinimum: true minimum: 0 type: number required: - width - height type: object OverlayPointOutput: additionalProperties: false description: >- Top-left corner of the overlay, as a percentage of the video canvas (0-100). Relative so the anchor survives video aspect ratio changes. properties: xPct: example: 30 type: number yPct: example: 30 type: number required: - xPct - yPct type: object headers: Deprecation: description: Indicates that an API operation is deprecated, following RFC 9745 example: '@1767225600' schema: type: string RateLimit: description: >- Current quota with remaining requests (`r`) and seconds until reset (`t`) example: '"public-api";r=95;t=42' schema: type: string RateLimitPolicy: description: >- Named quota policy with the request limit (`q`) and window in seconds (`w`) example: '"public-api";q=100;w=60' schema: type: string Sunset: description: >- Indicates when a deprecated API operation will become unavailable, following RFC 8594 example: Tue, 30 Jun 2026 23:59:59 GMT schema: type: string XRateLimitLimit: description: Maximum requests allowed in the current window example: 100 schema: type: integer XRateLimitRemaining: description: Requests remaining in the current window example: 95 schema: type: integer XRateLimitReset: description: Unix timestamp in milliseconds when the window resets example: 1704067200000 schema: format: int64 type: integer RetryAfter: description: Seconds to wait before retrying a rate-limited request example: 45 schema: minimum: 1 type: integer securitySchemes: BearerAuth: description: API key obtained from your Tella account settings scheme: bearer type: http ```` ## Related topics - [Model Context Protocol (MCP)](/docs/mcp-server.md) - [Apply many video edits](/docs/api-reference/videos/apply-many-video-edits.md) - [Update an overlay](/docs/api-reference/clips/update-an-overlay.md) - [Remove a text overlay](/docs/api-reference/clips/remove-a-text-overlay.md) - [List text overlays on a clip](/docs/api-reference/clips/list-text-overlays-on-a-clip.md)