Skip to main content

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:

EndpointYouTube cost (units)
GET /api/uploadposts/youtube/captions50 (+1 the first time for a video)
POST /api/uploadposts/youtube/captions400 (+1 the first time for a video)
PUT /api/uploadposts/youtube/captions/{caption_id}450
GET /api/uploadposts/youtube/captions/{caption_id}/download200 (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​

NameValueDescription
AuthorizationApikey your-api-key-hereYour API key for authentication

List tracks​

GET /api/uploadposts/youtube/captions?user=my-profile&video_id=dQw4w9WgXcQ
NameTypeRequiredDescription
userStringYesProfile username with a YouTube channel connected.
video_idStringYesA video of the connected channel.
idsStringNoOnly 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.

NameTypeRequiredDescription
userStringYesProfile username.
video_idStringYesA video of the connected channel.
languageStringYesLanguage of the track (BCP-47, e.g. en, es, pt-BR).
nameStringNoTrack 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_draftBooleanNotrue uploads it as a draft (not visible to viewers).
fileFileOne of the twoThe caption file, up to 10 MB (a caption file of several hours is a few hundred KB).
file_urlStringOne of the twoPublic URL of the caption file.
formatStringNoFile 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
NameTypeDescription
tfmtStringConvert to srt, vtt, sbv, scc or ttml. Without it, the original format.
tlangStringMachine translation into this language (ISO 639-1 two-letter code, e.g. fr).
video_idStringOnly 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 (name is 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 has cost and limit), 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 has cost, limit, retry_after and resets_at).
  • 502 — youtube_write_outcome_unknown (see above).
  • 503 — youtube_feature_disabled: YouTube management features are temporarily off on Upload-Post. Uploads keep working.