> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://fastpix.com/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://fastpix.com/docs/_mcp/server. # Generate subtitles and transcripts automatically FastPix generates subtitles from your video's audio using AI transcription, creating a synchronized WebVTT track that improves accessibility, SEO, and viewer engagement. You can enable auto-generation at upload time by including a `subtitles` object in the request, or generate subtitles for an existing video by calling the generate-subtitles endpoint with the audio `trackId`. \ ## Prerequisites * A FastPix account with an active workspace ([Activate your account](/getting-started/activate-your-account)) * Your **Access Token ID** and **Secret Key** from the [FastPix dashboard](https://dashboard.fastpix.com/) * A video uploaded or a ready video with a known audio `trackId` * Clear source audio in a [supported language](#supported-languages-for-auto-generated-subtitles) \ ## Key terms * `mediaId` is the unique identifier FastPix assigns to every uploaded asset. * `trackId` identifies a single audio, video, or subtitle track that belongs to a media asset. * `playbackId` is a separate, access-controlled identifier used to construct the HLS playback URL: `https://stream.fastpix.com/.m3u8`. * `accessPolicy` field controls whether a media is `public` or `private`. \ ## How auto-generated subtitles work FastPix transcribes your on-demand media using the [OpenAI Whisper model](https://openai.com/index/whisper/), converting spoken audio into synchronized subtitles. \ ### Key considerations **Audio quality:** Auto-generated captions perform best with clear audio. Results may vary on media with excessive non-speech audio, such as music, background noise, or long silences. **Language compatibility:** FastPix generates subtitles in the same language as the audio. The feature does not translate captions into other languages. Test this feature with your typical content to evaluate transcription quality before rolling it out in production. \ ## Generate subtitles during upload Enable auto-generated subtitles at upload time by including a `subtitles` object in your upload request. ### Prepare your video * Remove unwanted sounds, reduce background noise, and avoid overlapping audio. * Adjust volume levels so speech is clear and audible. \ ### Enable subtitle generation in the request The `subtitles` object takes three fields: * **languageName**: The language of the audio (for example, `"english"`). * **metadata**: Optional key-value pairs to tag the subtitle track. * **languageCode**: The [BCP 47](https://www.rfc-editor.org/info/bcp47) code for the spoken language (for example, `en`). \ ### Upload video using url request ```json { "inputs": [ { "type": "video", "url": "https://example.com/sample.mp4" } ], "subtitles": { "languageName": "english", "metadata": { "key1": "value1" }, "languageCode": "en" }, "accessPolicy": "public" } ``` \ ### Upload video from device request ```json { "corsOrigin": "*", "pushMediaSettings": { "accessPolicy": "public", "subtitles": { "languageName": "english", "metadata": { "key1": "value1" }, "languageCode": "en" }, "maxResolution": "1080p" } } ``` \ > **IMPORTANT**\ > Verify that `languageCode` matches the spoken language in your video. The transcription model follows this setting. \ ### Process the video After upload, FastPix transcribes the audio and attaches a synchronized WebVTT subtitle track to the asset. \ ## Supported languages for auto-generated subtitles FastPix supports the following languages and language codes for auto-generated subtitles on on-demand media: \ | Language | Language Code | Status | | ---------- | ------------- | --------- | | English | en | Supported | | Spanish | es | Supported | | Italian | it | Supported | | Portuguese | pt | Supported | | German | de | Supported | | French | fr | Supported | | Polish | pl | Beta | | Russian | ru | Beta | | Dutch | nl | Beta | | Catalan | ca | Beta | | Turkish | tr | Beta | | Swedish | sv | Beta | | Ukrainian | uk | Beta | | Norwegian | no | Beta | | Finnish | fi | Beta | | Slovak | sk | Beta | | Greek | el | Beta | | Czech | cs | Beta | | Croatian | hr | Beta | | Danish | da | Beta | | Romanian | ro | Beta | | Bulgarian | bg | Beta | \ > **NOTE**\ > Subtitles match the spoken language directly. FastPix does not generate translated captions from this endpoint. \ ## Generate subtitles for existing audio tracks Call the [generate track subtitles](/video-on-demand-api/manage-videos/generate-subtitle-track) API with the audio `trackId` to produce subtitles for an asset that is already ready. Provide the language name and code in the request body. \ **Endpoint**: `POST` `api.fastpix.com/v1/on-demand/{mediaId}/tracks/{trackId}/generate-subtitles` \ **Request headers:** Content-Type: application/json Authorization: Basic Auth YOUR\_ACCESS\_TOKEN YOUR\_SECRET\_KEY \ **`Request Body`** ```json Request Body { "languageCode": "en", "languageName": "English" } ``` \ > **NOTE** > > * Use the correct `trackId` for the audio track. > * Make sure the `languageCode` follows **BCP 47** standards. \ **`Response`** ```json Response { "success": true, "data": { "id": "0fd317c7-7237-413c-a252-8ad68b370166", "type": "subtitle", "languageCode": "en", "languageName": "English" } } ``` \ ## Retrieve a transcript If your media has an auto-generated subtitle track, you can extract a plain text transcript of the recognized speech. This is useful for content moderation, sentiment analysis, summarization, or downstream processing. To retrieve the transcript, use the `playbackId` of the media and the `trackId` of the generated subtitles. \ ### Plain text transcript (TXT format) A plain text transcript returns the raw, unformatted speech content without timestamps. This format suits natural language processing pipelines and search indexing. To fetch the transcript in plain text: ``` https://stream.fastpix.com/{PLAYBACK_ID}/text/{TRACK_ID}.txt ``` \ > **NOTE** > > The plain text transcript contains only spoken words, without timecodes or additional metadata. \ ### WebVTT subtitle file (VTT format) A WebVTT file provides subtitles in a structured format with timestamps for synchronization in HLS-compatible players. Use this format to edit, refine, or repurpose subtitles on other platforms. To fetch the WebVTT file, replace `.txt` with `.vtt`: \ ``` https://stream.fastpix.com/{PLAYBACK_ID}/text/{TRACK_ID}.vtt ``` \ > **NOTE** > > Most HLS-compatible players support WebVTT, and you can edit the file in any text or subtitle editor. \ ### Retrieve transcripts for signed media If your video uses signed playback, append a [JWT (JSON Web Token)](/video-security/generate-jwts-for-secure-media) as a query parameter on the transcript URL so only authorized viewers can fetch it. ``` https://stream.fastpix.com/{PLAYBACK_ID}/text/{TRACK_ID}.txt?token={JWT} ``` \ For WebVTT subtitles on signed media: ``` https://stream.fastpix.com/{PLAYBACK_ID}/text/{TRACK_ID}.vtt?token={JWT} ``` \ Transcripts extend accessibility, repurpose content, and integrate subtitles into external workflows. \ **Use cases for transcripts** * Automated content review- Run transcripts through AI tools to detect key topics or compliance issues. * SEO optimization- Transcripts make video content indexable and improve search coverage. * Podcast and blog conversion- Convert video speech into written formats for repurposing. * Educational materials - Provide readable transcripts alongside instructional videos. \ ## Edit or replace generated subtitles Auto-generated captions rely on AI transcription, which can misinterpret strong accents, background noise, or fast dialogue. To correct errors: 1. **Download** the existing **WebVTT file**: ``` https://stream.fastpix.com/{PLAYBACK_ID}/text/{TRACK_ID}.vtt ``` 2. **Edit the file** in a text editor or subtitle editor such as Aegisub or Subtitle Edit. 3. **Remove the auto-generated track** using the [Delete track API](/video-on-demand-api/manage-videos/delete-media-track). > You can also overwrite the edited subtitles in place using the [Update track API](/video-on-demand-api/manage-videos/update-media-track), or continue to the next step. 4. **Upload the edited subtitles** as a new track via the [Add track API](/video-on-demand-api/manage-videos/add-media-track). This workflow keeps subtitles accurate and improves the viewing experience. \ ## Best practices for accurate subtitles * **Audio quality:** Use clear, high-quality audio. Minimize background sounds, echo, and interruptions. * **Consistent speech:** Maintain a steady speaking pace and clear pronunciation. Avoid mixing languages inside a single segment, the transcription model may not differentiate between them accurately. * **Language consistency:** Keep the entire video in a single language where possible. For multilingual content, post-edit or author subtitles manually for the non-primary segments. \ #### Frequently asked questions Accuracy depends on audio clarity, speaking pace, and language. Transcription quality is highest on fully supported languages with clean speech audio; Beta languages and content with heavy background noise, accents, or overlapping speakers can lower accuracy. Test on a representative sample before rolling out. The auto-generate endpoint produces subtitles in the same language as the audio track, not translations. If a media asset has multiple audio tracks in different languages, you can call the generate-subtitles endpoint once per audio `trackId` to produce one subtitle track per language. Remove the generated track with the [Delete track API](/video-on-demand-api/manage-videos/delete-media-track) and call the [generate track subtitles](/video-on-demand-api/manage-videos/generate-subtitle-track) endpoint again after verifying the correct `trackId`, a supported `languageCode`, and clean audio. For manual corrections, edit the WebVTT file and re-upload it via the [Add track API](/video-on-demand-api/manage-videos/add-media-track). FastPix returns a WebVTT (`.vtt`) subtitle track for synchronized playback and a plain text (`.txt`) transcript for downstream processing. Both are served from `https://stream.fastpix.com/{PLAYBACK_ID}/text/{TRACK_ID}.{ext}`. \ ## What's next? * [Upload videos from a URL](/upload-videos/upload-videos-from-a-url) * [Add tracks to existing media](/video-on-demand-api/manage-videos/add-media-track) * [API Reference: generate subtitle track](/video-on-demand-api/manage-videos/generate-subtitle-track) * [Secure playback with JWTs](/video-security/generate-jwts-for-secure-media)