---
title: "Add a text track to a video"
method: POST
path: "/channels/{channel_id}/videos/{video_id}/texttracks"
tags: ["Videos\\Text tracks"]
---

# Add a text track to a video

`POST /channels/{channel_id}/videos/{video_id}/texttracks`

## Request

- Base URL: `https://api.vimeo.com`
- URL: `https://api.vimeo.com/channels/{channel_id}/videos/{video_id}/texttracks`
- Auth: OAuth 2
  - Authorization code: `/oauth/authorize`, token URL `/oauth/access_token`
  - Client credentials, token URL `/oauth/authorize/client`
  - Scopes: `upload`
- TypeScript: <https://skmtc.dev/vimeo/apis/vimeo-api/docs/channels/:channel_id/videos/:video_id/texttracks/post.ts> (a function with typed inputs; its response is checked against the schema)

This method adds a text track to the specified video. For more information, see [Working with Text Track Uploads](https://developer.vimeo.com/api/upload/texttracks).

## Path parameters

- `channel_id` number, required
- `video_id` number, required

## Request body

- object
  - `active` boolean: Whether the current text track is the *active text track*, or the one that appears in the player. Only one text track per language and type can be active.
  - `language` string, required: The language of the text track. For a full list of supported language, use the [`/languages?filter=texttracks`](https://developer.vimeo.com/api/reference/videos#get_languages) endpoint.
  - `name` string, required: The name of the text track.
  - `type` 'captions' | 'chapters' | 'descriptions' | 'metadata' | 'subtitles', required: The type of the text track.

## Response `201`

The text track was added.

- TextTrack
  - `active` boolean, required: Whether this text track is active.
  - `hls_link` string, required: The read-only URL of the text track file, intended for use with HLS playback.
  - `hls_link_expires_time` string, required: The time in ISO 8601 format when the read-only HLS playback text track file expires.
  - `language` string, nullable, required: The language code for this text track. To see a full list, request `/languages?filter=texttrack`.
  - `link` string, required: The read-only URL of the text track file. You can upload to this link when you create it for the first time.
  - `link_expires_time` string, required: The time in ISO 8601 format when the text track link expires.
  - `name` string, nullable, required: The descriptive name of this text track.
  - `type` 'captions' | 'subtitles', nullable, required: The type of the text track: Option descriptions: * `captions` - The text track is for captions. * `subtitles` - The text track is for subtitles.
  - `uri` string, required: The relative URI of the text track.

## Other responses

- `403`: * The authenticated user can't add the text track. * Error code 2204: The request contains errors.

## Changes

- **2019-04-12** `80428f626f3e`: 2 info
  - api tag `Videos\Text tracks` added
  - api tag `Videos\Text Tracks` removed
- **2018-12-05** `26f856a94041`: 2 info
  - api tag `Videos\Text Tracks` added
  - api tag `Videos\Text tracks` removed

[Operation history](https://skmtc.dev/vimeo/apis/vimeo-api/changes/channels/:channel_id/videos/:video_id/texttracks/post.md)

---

[API](https://skmtc.dev/vimeo/apis/vimeo-api.md) - [All operations](https://skmtc.dev/vimeo/apis/vimeo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vimeo/apis/vimeo-api/revisions/ea882e0224a4?raw)