How to Add Captions and Set the Video Language on YouTube via API
Set a YouTube video's language and attach your own SRT or VTT captions (subtitles) when you schedule it with the PostFast API. Upload the caption file, then create the post with youtubeLanguage and youtubeCaptionKey.
Every YouTube video can carry a language and caption tracks. With the PostFast API you set both when you schedule the video: youtubeLanguage sets YouTube's "Video language" (the language spoken in the video) and its "Title and description language", and youtubeCaptionKey adds your own .srt or .vtt file as a caption track in that language right after the video uploads.
It takes two steps. First, upload the caption file: call POST /file/get-signed-upload-urls with contentType application/x-subrip (.srt) or text/vtt (.vtt) and count 1, then PUT the file to the returned signedUrl with the same Content-Type. Second, create the YouTube post with the video in mediaItems, the returned key in controls.youtubeCaptionKey, and the video's language as a BCP-47 code (en, en-GB, es, es-419, pt-BR) in controls.youtubeLanguage.
Viewers see your track named by its language, and YouTube's automatic captions stay available separately. The captions are added in their own step after the upload, so if adding them fails, the video still publishes.
API Parameters
| Parameter | Type | Description |
|---|---|---|
youtubeLanguage | string | The video's language as a BCP-47 code, e.g. en, en-GB, es, es-419, fr or pt-BR. Sets both YouTube's "Video language" (the spoken language) and its "Title and description language". PostFast normalizes the code before sending it (pt-br becomes pt-BR) and rejects an unknown code with a 400 (youtubeLanguage.invalid) that names it. Required when youtubeCaptionKey is set. Like every control, it applies to every post in the request. |
youtubeCaptionKey | string | Key of an uploaded .srt or .vtt caption file, "file/{uuid}.srt" or "file/{uuid}.vtt", from POST /file/get-signed-upload-urls (contentType application/x-subrip or text/vtt). Requires youtubeLanguage. Added to the video as a caption track in that language right after it uploads; viewers see the track named by its language, and YouTube's automatic captions stay available separately. The file must be timed SRT or WebVTT in plain UTF-8, max 10 MB, uploaded before the post is created. If adding the captions fails, the video still publishes. |
youtubeTitle | string | Video title (max 100 characters). Over-length titles are rejected with youtubeTitle.tooLong (400), never truncated. When omitted, the first line of content becomes the title, clamped to 100 characters. |
youtubeIsShort | boolean | Whether it's a YouTube Short |
youtubePrivacy | string | Video privacy setting PUBLICUNLISTEDPRIVATE |
Code Example
const response = await fetch('https://api.postfa.st/social-posts', {
method: 'POST',
headers: {
'pf-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"posts": [
{
"content": "Receta completa de tortilla de patatas, paso a paso.\n\nIngredientes: 6 huevos, 4 patatas, 1 cebolla, aceite de oliva y sal.",
"mediaItems": [
{
"key": "video/4f1d2c3b-5a6e-4b7c-8d9e-0f1a2b3c4d5e.mp4",
"type": "VIDEO",
"sortOrder": 0
}
],
"scheduledAt": "2026-11-03T17:00:00.000Z",
"socialMediaId": "880a1722-b5ce-64a7-d049-778988772004"
}
],
"controls": {
"youtubeLanguage": "es",
"youtubeCaptionKey": "file/3c9e5a71-2b4d-4f86-9a1e-7d2c5b8f0e64.srt",
"youtubeTitle": "Tortilla de patatas en 10 minutos",
"youtubeIsShort": false,
"youtubePrivacy": "PUBLIC"
}
})
});
const data = await response.json();
Did You Know?
Tips
Upload the caption file before you create the post: the create call checks that the file exists, is at most 10 MB, and is timed SRT or WebVTT in plain UTF-8.
Request the upload URL with contentType application/x-subrip for .srt or text/vtt for .vtt, and send the same Content-Type header when you PUT the file.
Put the caption key in controls.youtubeCaptionKey, never in mediaItems: mediaItems hold the video itself.
Write the title and description in the language you set: youtubeLanguage is also YouTube's "Title and description language".
Use a region subtag when the variant matters: es-419 for Latin American Spanish, pt-BR for Brazilian Portuguese, en-GB for British English.
Schedule YouTube videos with their language and captions already set
Common Pitfalls
youtubeCaptionKey needs youtubeLanguage. A YouTube post with a caption key but no language is rejected with youtubeCaptionKey.languageRequired (400).
Controls apply to every post in a request, so every video in it gets the same language and caption file. Send one request per language.
The create call checks that the caption file exists. If the PUT has not finished, or failed, the post is rejected with media.invalidMedia (400).
A plain transcript without timings is not a caption file. Creating the post rejects it with media.invalidMedia (400), naming the file as not a timed UTF-8 SRT or WebVTT file.
Frequently Asked Questions
How do I upload an SRT file to YouTube through the API?
Call POST /file/get-signed-upload-urls with contentType "application/x-subrip" and count 1. It returns a key such as "file/3c9e5a71-2b4d-4f86-9a1e-7d2c5b8f0e64.srt" and a signedUrl. PUT the file to the signedUrl with Content-Type application/x-subrip, then create the YouTube post with that key in controls.youtubeCaptionKey and the video's language in controls.youtubeLanguage. For WebVTT files, use "text/vtt".
Do my captions replace YouTube's automatic captions?
No. Your file is added as its own caption track, named by its language, and YouTube's automatic captions stay available separately.
Which language codes does youtubeLanguage accept?
BCP-47 codes such as en, en-GB, es, es-419, fr or pt-BR. PostFast normalizes the code before sending it (pt-br becomes pt-BR). An unknown code is rejected with a 400 (youtubeLanguage.invalid) that names it, so it never reaches YouTube.