--- title: "Create a text track" method: POST path: "/v2/sites/{site_id}/media/{media_id}/text_tracks/" tags: ["text tracks"] --- # Create a text track `POST /v2/sites/{site_id}/media/{media_id}/text_tracks/` ## Request - Base URL: `https://api.jwplayer.com` - URL: `https://api.jwplayer.com/v2/sites/{site_id}/media/{media_id}/text_tracks/` - Auth: API key in header `Authorization` Generate a text track for the associated media. Each media can have a maximum of 50 text tracks. ## Path parameters - `site_id` string, required: Unique identifier for a resource - `media_id` string, required: Unique identifier for a resource ## Request body - object - `upload` object - `file_format` 'srt' | 'vtt': Text track file format This is **required** for the `direct` upload method. For `fetch` uploads, it is required when the `download_url` file type is ambiguous. - `auto_publish` boolean: Whether the track is published after being uploaded If `false`, the track is set to `draft` status after being successfully uploaded. - `method` 'direct' | 'fetch', required: Upload process used to add a track to an account - `mime_type` 'text/vtt' | 'text/plain': Mime type of the uploaded asset If `mime_type` is defined, the `mime_type` value must be used as the `Content-Type` header on the upload request. If `mime_type` is excluded, no `Content-Type` header should be present on the upload request. - `download_url` unknown - `metadata` TextTrackWriteMetadata - `label` string: Label of the text track A maximum of 50 characters is permitted. For `captions` and `subtitles` tracks, this property is the display name in the JWX player settings menu. For `chapters`, `descriptions`, and `metadata` tracks, this property serves as a name for the track. **NOTE**: This label cannot be named `default`. - `position` integer: (Captions and subtitles only) Determines the location of a track in two contexts: - Location in a media’s list of tracks in the Delivery API. - Location in the captions settings menu of the JWX player. The value of `position` cannot exceed the highest index of all subtitles and captions associated to the media. - `source_type` string: (Captions and subtitles only) Source of text track. Possible values include: - `auto_generated` - Auto-generated captions from AI transcription service. - `extracted` - Text tracks extracted from the original VOD media or live-to-VOD conversion. - `manual` - Caption files uploaded via the dashboard or API, or captions created in the dashboard after ingest. source_type for all text tracks created before Mar 3, 2026 will appear as `manual` - `srclang` string: Language of the text track data A maximum of 32 characters is permitted. Primarily applicable for `captions` and `subtitles`, this value corresponds to the `srclang` attribute of the `` element. - `track_kind` 'captions' | 'chapters' | 'descriptions' | 'metadata' | 'subtitles', required: Kind of text track This corresponds with the HTML `` element `kind` attribute. ## Response `201` Resource successfully created - TextTrackResourceRead - `schema` string - `id` string: Unique identifier for a resource - `created` string: Date and time at which the resource was created - `last_modified` string: Date and time at which the resource was most recently modified - `type` string: Name of the type of resource. - `relationships` object: Ancilliary resources associated to the primary resource being read - `metadata` TextTrackMetadata - `label` string: Label of the text track A maximum of 50 characters is permitted. For `captions` and `subtitles` tracks, this property is the display name in the JWX player settings menu. For `chapters`, `descriptions`, and `metadata` tracks, this property serves as a name for the track. **NOTE**: This label cannot be named `default`. - `position` integer: (Captions and subtitles only) Determines the location of a track in two contexts: - Location in a media’s list of tracks in the Delivery API. - Location in the captions settings menu of the JWX player. The value of `position` cannot exceed the highest index of all subtitles and captions associated to the media. - `source_type` string: (Captions and subtitles only) Source of text track. Possible values include: - `auto_generated` - Auto-generated captions from AI transcription service. - `extracted` - Text tracks extracted from the original VOD media or live-to-VOD conversion. - `manual` - Caption files uploaded via the dashboard or API, or captions created in the dashboard after ingest. source_type for all text tracks created before Mar 3, 2026 will appear as `manual` - `srclang` string: Language of the text track data A maximum of 32 characters is permitted. Primarily applicable for `captions` and `subtitles`, this value corresponds to the `srclang` attribute of the `` element. - `delivery_url` string: URL to access the text track This URL is only returned when the text track status is `ready` or `draft`. - `error_message` string: A human-readable error message for describing upload failures - `track_kind` 'captions' | 'chapters' | 'descriptions' | 'metadata' | 'subtitles': Kind of text track This corresponds with the HTML `` element `kind` attribute. - `upload_link` string: Presigned S3 link for uploading a track ## Other responses - `400`: Invalid JSON request body - `404`: Resource with ID supplied does not exist in account and object namespace - `409`: Request cannot be created because media reached maximum limit of 50. ## Changes - **2026-11-03** `9fad6bd5872e`: 2 info - added the media type `application/json` for the response with the status `400` - added the media type `application/json` for the response with the status `404` [Operation history](https://skmtc.dev/jwplayer/apis/management-api-v2/changes/v2/sites/:site_id/media/:media_id/text_tracks/post.md) --- [API](https://skmtc.dev/jwplayer/apis/management-api-v2.md) - [All operations](https://skmtc.dev/jwplayer/apis/management-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/jwplayer/apis/management-api-v2/revisions/9fad6bd5872e?raw)