Key takeaways
- Encode one reviewed MP4 output before the YouTube export instead of making the channel accept every source variation.
- Start exports as private so processing completion is not confused with editorial approval or public publication.
- Keep OAuth access in named Template Credentials and keep Transloadit account secrets out of browser code.
A direct upload to YouTube is convenient until every browser, mobile client, and internal tool implements its own validation, encoding assumptions, metadata rules, and retry behavior. A three-stage workflow creates one controlled handoff: accept the source, normalize the deliverable, then publish it to a channel under an explicit visibility policy.
What matters most
- Validate title, description, and keywords in the application before supplying them as Template fields, and keep category and visibility as fixed Template values rather than client input.
- Store the Assembly ID and returned platform identifier so retries cannot silently create duplicate videos.
- Test channel permissions and quotas with the real destination account before enabling unattended publishing.
Define publication as a state transition
Uploading bytes, finishing an encode, and making a video public are three different events. Model them separately. The application should know which user supplied the source, which metadata was approved, which workflow version ran, and whether a person or policy may expose the resulting channel record. A completed /youtube/store Step proves that YouTube accepted the export; it does not prove that the content should be public.
Begin with visibility set to private. Reconcile the returned destination identity with the application record, let editors inspect playback and metadata, and perform public or unlisted publication through an explicitly authorized action. This boundary prevents a successful technical workflow from bypassing moderation, scheduling, or rights review.
Transfer complete
The source reached the Assembly and is available to downstream Steps.
Processing complete
The controlled MP4 exists and passed the technical checks chosen by the Template.
Publication approved
The application has reconciled the destination and authorized its audience.
Build the locked YouTube Template
The baseline graph has one upload Step, one encode Step, and one YouTube export Step. /upload/handle is named :original and has no use value. /video/encode reads :original and produces a bounded MP4 rendition. /youtube/store reads only that rendition, so a raw camera upload cannot bypass the encoding policy.
Keep allow_steps_override false when browser or mobile clients create Assemblies from the Template. Supply only reviewed metadata fields from a trusted server. YouTube’s title, category, keywords, and visibility contract is stricter than free-form application input, so validate fields before signing or creating the Assembly instead of discovering policy errors after a large encode.
{
"allow_steps_override": false,
"auth": {
"max_number_of_files": 1,
"max_size": 2147483648
},
"steps": {
":original": {
"robot": "/upload/handle"
},
"youtube_ready": {
"use": ":original",
"robot": "/video/encode",
"preset": "web/mp4/1080p",
"width": 1920,
"height": 1080,
"resize_strategy": "fit",
"zoom": false
},
"youtube_private": {
"use": "youtube_ready",
"robot": "/youtube/store",
"credentials": "youtube-channel",
"title": "${fields.title}",
"description": "${fields.description}",
"category": "education",
"keywords": "${fields.keywords}",
"visibility": "private",
"result": true
}
}
}Protect channel credentials and metadata
Create YouTube Template Credentials through the OAuth flow and reference only their name in the Template. The browser should never receive the OAuth token or the Transloadit Auth Secret. The server should select the fixed Template, authorize the target channel, and constrain which users can supply publication metadata.
Do not interpolate arbitrary HTML, secrets, or internal record data into the public description. Apply an 80-character title limit, map categories to the supported list, bound keyword length and count in the application, and choose visibility from an application policy rather than accepting an unchecked client value.
Reconcile completion without duplicate publishing
Video encoding and a remote platform upload can outlast an interactive request. Persist a local publication operation before creating the Assembly, attach the Assembly ID as soon as it exists, and complete the record from a signature-verified webhook or a later Assembly Status lookup. Keep the returned YouTube identity with the operation rather than treating the result URL as the only record.
A timeout is not evidence that the export failed. Before retrying, check the stored operation and Assembly Status. A stable idempotency key based on the source version, channel, workflow version, and intended publication event prevents a lost response from creating a second private video that no one notices.
Test the destination contract
Use the real destination channel for a private fixture. Verify the encoded dimensions, audio, duration, title truncation behavior, category, keywords, and privacy. Test an expired OAuth grant, a user without channel permission, a title over the application limit, an unsupported source, and a repeated completion notification.
Monitor failures by phase: intake, encode, or YouTube export. Record queue time, processing duration, output bytes, export duration, destination identity, and terminal state. Keep raw provider errors in protected diagnostics and show editors a stable action such as reconnect credentials, correct metadata, or retry the existing operation.
Keep source retention separate from channel delivery
YouTube is a publishing destination, not necessarily the application’s source archive. Decide whether the uploaded master, the encoded delivery file, or both must remain in storage the application controls. Retaining a known source supports later re-encoding, rights review, provider migration, and recovery from accidental channel deletion.
Apply deletion only after the destination identity is reconciled and the product’s retention policy permits it. A private YouTube video can still be removed, blocked, or disconnected from the application account, so do not make platform presence the only evidence that the source workflow succeeded.
Technical details worth knowing
- /upload/handle must be named :original, must not define use, and can appear only once in a set of Assembly Instructions.
- The /youtube/store schema requires credentials, title, description, category, keywords, and visibility. The visibility value has no default and must be public, private, or unlisted, so omitting it fails validation. Set it to private for a review-first workflow.
- The /youtube/store schema caps titles at 80 characters and restricts category to a fixed enum. YouTube documents a 5,000-character description limit, which the application must enforce because the Robot schema accepts any string length.
- YouTube keywords are supplied as one comma-separated string rather than an array.
- A /youtube/store Step can receive a video and a custom thumbnail through named use inputs, but the three-stage baseline sends only the encoded video.
- Template Credentials hold the YouTube OAuth authorization. They do not decide which application user may publish to the connected channel.
A practical approach
- 1
Define the accepted source, output rendition, metadata limits, and approval state.
- 2
Create YouTube Template Credentials and save a locked upload–encode–export Template.
- 3
Submit one private fixture and reconcile the Assembly result with an application record.
- 4
Exercise duplicate submissions, expired OAuth access, rejected metadata, and manual publication.
When Transloadit is useful
Use /upload/handle for the incoming file, /video/encode for a bounded MP4 rendition, and /youtube/store for the channel upload. Keep the saved Template locked, obtain YouTube OAuth access through Template Credentials, validate runtime metadata in the application, and begin with private visibility.
Architecture boundary
Transloadit can receive, encode, and upload a video to YouTube, but the application still owns uploader authorization, editorial approval, metadata policy, channel governance, and the durable relationship between its record and the resulting YouTube video.
Frequently asked questions
Can the workflow publish directly as public?
Yes, /youtube/store supports public visibility, but private is safer when publication requires editorial, rights, or moderation approval. Make public publication a separate authorized transition.
Does YouTube still transcode the uploaded MP4?
The Transloadit encode controls the bounded deliverable uploaded to YouTube, while YouTube separately controls how that upload is prepared for playback on its platform.
Where should the YouTube OAuth token live?
In named Template Credentials. Browser code should receive neither the OAuth token nor the Transloadit Auth Secret.
How do we prevent duplicate videos after a timeout?
Persist the operation and Assembly ID before waiting. Check that state and the Assembly Status before creating another Assembly for the same source, channel, and publication event.
Can this workflow add a custom thumbnail?
Yes, /youtube/store can take named video and image inputs, but that adds another processing branch. The baseline guide intentionally covers the three-stage video-only workflow.