YouTube Captions
Manage the caption (subtitle) tracks of videos that are already on the YouTube channel connected to a profile: list them, add a track, replace a track's file or publish a draft, download a track (optionally converted or machine-translated) and delete it.
To send subtitles with the upload, keep using the youtube_subtitle_* fields of Upload video; nothing changes there.
Caption calls are the most expensive YouTube operations. They use your daily allowance for YouTube management features:
| Endpoint | YouTube cost (units) |
|---|---|
GET /api/uploadposts/youtube/captions | 50 (+1 the first time for a video) |
POST /api/uploadposts/youtube/captions | 400 (+1 the first time for a video) |
PUT /api/uploadposts/youtube/captions/{caption_id} | 450 |
GET /api/uploadposts/youtube/captions/{caption_id}/download | 200 (repeating the same download within 10 minutes is free) |
DELETE /api/uploadposts/youtube/captions/{caption_id} | 50 |
On the free plan (200 units a day) uploading, replacing or downloading a track does not fit in the daily allowance: those calls answer 403 youtube_plan_daily_limit_too_low without spending anything. Subtitles sent with the upload are not affected.
Everything is checked before spending: the file format, encoding and time codes, the language, the track name, your remaining allowance, and that the video belongs to the connected channel. They follow the common rules of the YouTube endpoints.
Managing captions needs the full YouTube permission: connections made before it was requested answer 403 youtube_insufficient_scope (reconnect the channel) before any unit is spent.
Headers
| Name | Value | Description |
|---|---|---|
| Authorization | Apikey your-api-key-here | Your API key for authentication |
List tracks
GET /api/uploadposts/youtube/captions?user=my-profile&video_id=dQw4w9WgXcQ
| Name | Type | Required | Description |
|---|---|---|---|
user | String | Yes | Profile username with a YouTube channel connected. |
video_id | String | Yes | A video of the connected channel. |
ids | String | No | Only these caption IDs, comma separated. |
{
"success": true,
"video_id": "dQw4w9WgXcQ",
"items": [
{
"id": "AUieDaZ…",
"snippet": {
"videoId": "dQw4w9WgXcQ", "language": "es", "name": "", "trackKind": "standard",
"isDraft": false, "status": "serving", "audioTrackType": "unknown", "lastUpdated": "2026-11-14T10:00:00Z"
}
}
],
"next_page_token": null,
"page_info": null
}
Listing does not return the text of the track: use download. Automatic captions appear with trackKind: "ASR".
Add a track
POST /api/uploadposts/youtube/captions
multipart/form-data with the file, or JSON with file_url.
| Name | Type | Required | Description |
|---|---|---|---|
user | String | Yes | Profile username. |
video_id | String | Yes | A video of the connected channel. |
language | String | Yes | Language of the track (BCP-47, e.g. en, es, pt-BR). |
name | String | No | Track name shown in the player (a string), up to 150 characters. Not sent: the language code. Sent empty (""): the language's default track, the one YouTube Studio's subtitle editor opens. |
is_draft | Boolean | No | true uploads it as a draft (not visible to viewers). |
file | File | One of the two | The caption file, up to 10 MB (a caption file of several hours is a few hundred KB). |
file_url | String | One of the two | Public URL of the caption file. |
format | String | No | File format when the file name has no extension (e.g. srt). |
Accepted formats (YouTube's list): srt, sbv, sub, mpsub, lrc, smi/sami, rt, vtt, ttml, dfxp, scc, asc, and the binary broadcast formats cap, stl, tds, cin. Text files must be plain UTF-8 and carry time codes: YouTube no longer synchronises plain transcripts. An file_url must be a public http(s) URL of up to 2,048 characters, and the whole download has a time limit: a URL that is private, too slow or answers an error is refused with 400 download_failed (invalid_url for local or non-public addresses). Send either the file or the URL, not both (400 ambiguous_source).
curl -X POST https://api.upload-post.com/api/uploadposts/youtube/captions \
-H 'Authorization: Apikey your-api-key-here' \
-F 'user=my-profile' \
-F 'video_id=dQw4w9WgXcQ' \
-F 'language=es' \
-F 'name=Español' \
-F '[email protected]'
Answer 201 with {"success": true, "caption": {…}} (YouTube's caption resource; keep its id).
A video can have several tracks in the same language, each with a different name. If it already has a track with that language and name, the answer is 409 youtube_caption_exists: use another name or replace that track.
Replace a track or publish a draft
PUT /api/uploadposts/youtube/captions/{caption_id}
Send a new file (file or file_url, same rules as above) and/or is_draft (false publishes a draft). Replacing the file overwrites the current captions, so a new file needs confirm=true (400 confirmation_required otherwise; publishing a draft with is_draft alone does not). The language and name cannot change: delete the track and add a new one for that.
Use the caption_id returned when listing or adding tracks. For a track Upload-Post has not seen yet (for example one created in YouTube Studio), also send video_id: the tracks of that video are listed once (50 units) to confirm the track is on your channel.
Download a track
GET /api/uploadposts/youtube/captions/{caption_id}/download?user=my-profile&tfmt=srt
| Name | Type | Description |
|---|---|---|
tfmt | String | Convert to srt, vtt, sbv, scc or ttml. Without it, the original format. |
tlang | String | Machine translation into this language (ISO 639-1 two-letter code, e.g. fr). |
video_id | String | Only for a track Upload-Post has not seen yet (see above). |
The answer is the file itself (Content-Disposition: attachment). Only for videos of the connected channel (YouTube requires permission to edit the video).
Delete a track
DELETE /api/uploadposts/youtube/captions/{caption_id}?user=my-profile&confirm=true
Requires confirm=true. Answer: {"success": true, "deleted": true, "caption_id": "…", "video_id": "…"}.
When YouTube does not confirm an upload
If YouTube does not answer in time after the file was sent, the answer is 502 youtube_write_outcome_unknown: the track may or may not have been created. Upload-Post never retries it, and for a few minutes a new upload of the same video, language and name answers 409 youtube_caption_upload_in_progress. List the tracks before trying again.
Error responses
Same shape as every YouTube endpoint (see video details for the common ones). Specific to captions:
- 400 —
invalid_video_id,invalid_language,invalid_caption_id,youtube_caption_name_too_long,invalid_is_draft,invalid_caption_format,invalid_caption_encoding,invalid_caption_content(no time codes, or not a valid file of that format),empty_file,missing_file,ambiguous_source,invalid_url,download_failed,invalid_field(nameis not a string),invalid_json,invalid_tfmt,invalid_tlang,video_id_required,nothing_to_update,confirmation_required,youtube_caption_content_required,youtube_caption_invalid_metadata,youtube_caption_could_not_convert. - 403 —
youtube_plan_daily_limit_too_low(the operation costs more than the plan's daily allowance; the body hascostandlimit),youtube_forbidden(only the video's owner or an editor can manage its captions),youtube_insufficient_scope. - 404 —
youtube_video_not_found(not on the connected channel),youtube_caption_not_found. - 409 —
youtube_caption_exists,youtube_caption_upload_in_progress. - 413 —
file_too_large(more than 10 MB). - 429 —
youtube_daily_budget_exhausted: not enough allowance left today for this operation (the body hascost,limit,retry_afterandresets_at). - 502 —
youtube_write_outcome_unknown(see above). - 503 —
youtube_feature_disabled: YouTube management features are temporarily off on Upload-Post. Uploads keep working.