Platforms and integrations # File uploads, image optimization, and video encoding to a tus server Receive files, optimize images, or encode videos with Transloadit and hand the selected result to a tus-compatible server. Published September 1, 2026 ## Key takeaways * Use `/upload/handle` followed by `/tus/store` to relay an unchanged uploaded file to a tus-compatible endpoint. * Run `/image/optimize` before `/tus/store` when the receiving system should get an optimized image. * Run `/video/encode` with a tested preset before `/tus/store` when the destination should get a playback rendition. Tus is a resumable upload protocol, not an object-storage product. In these workflows, a client first uploads to a Transloadit Assembly, optional image or video Steps create the desired output, and \`/tus/store\` starts a separate outbound tus upload to the configured destination endpoint. That distinction matters for credentials, retries, result URLs, and application reconciliation. ## In this guide 1. [Model tus as a delivery boundary](#file-uploads-image-optimization-video-encoding-tus-server-section-1) 2. [Relay an uploaded file without transforming it](#file-uploads-image-optimization-video-encoding-tus-server-section-2) 3. [Optimize an image before tus delivery](#file-uploads-image-optimization-video-encoding-tus-server-section-3) 4. [Encode a video before tus delivery](#file-uploads-image-optimization-video-encoding-tus-server-section-4) 5. [Choose headers, metadata, and reported URLs deliberately](#file-uploads-image-optimization-video-encoding-tus-server-section-5) 6. [Test retries and reconcile both systems](#file-uploads-image-optimization-video-encoding-tus-server-section-6) ## What matters most * Store destination authorization headers in HTTP Template Credentials instead of browser-visible Instructions. * Reconcile the Assembly and the receiving application before marking an asset ready in product state. ## Model tus as a delivery boundary A Transloadit upload and a `/tus/store` export are two distinct transfers. The first brings client bytes into an Assembly. The Assembly may leave the file unchanged or create an image or video derivative. The second transfer sends the selected result from Transloadit to your tus endpoint. This architecture is useful when the receiving platform already exposes tus but you still want managed processing before delivery. The destination owns everything after protocol completion. Its application decides whether to move the upload into durable storage, create an asset record, scan it, publish it, or reject it later. Record both the Assembly ID and the receiver’s stable identity. Do not assume the tus upload URL is a permanent object identifier or a readable delivery URL unless the receiver explicitly promises that contract. ### Inbound transfer Client → Transloadit Assembly, using the upload method selected by the SDK or integration. ### Outbound transfer Assembly result → `/tus/store` → the configured tus-compatible destination endpoint. ### Durability boundary Receiver-side persistence and publication remain outside the tus protocol and Transloadit workflow. ## Relay an uploaded file without transforming it Use the upload-only Template when the destination should receive the original file accepted by the Assembly. `/upload/handle` exposes that input as `:original`, and `/tus/store` selects it through `use`. The required `endpoint` must be the destination URL that creates tus uploads, not the URL of an existing object or a browser download page. The sample references HTTP Template Credentials for static destination headers. Keep `allow_steps_override` false when clients must not replace the endpoint, remove authentication, or redirect a file. If the receiver needs tenant or asset context, prefer non-secret metadata with a server-authorized endpoint or scoped credential, and validate that context again on the receiving side. Relay an uploaded file to a tus endpoint ``` { "allow_steps_override": false, "steps": { ":original": { "robot": "/upload/handle" }, "delivered": { "use": ":original", "robot": "/tus/store", "endpoint": "https://uploads.example.com/files/", "credentials": "my_tus_http_credentials" } } } ``` ## Optimize an image before tus delivery For an image-only contract, connect `/image/optimize` to `:original` and deliver the `optimized` Step. The sample preserves metadata and uses lossless PNG optimization (`lossy: false`); that flag does not affect JPEG, GIF, WebP, or SVG optimization. Evaluate whether metadata removal or lossy PNG optimization is appropriate before changing those settings, because either can alter information that the receiving application expects. The sample’s non-default `priority: "compression-ratio"` favors a smaller output over processing speed; `conversion-speed`, the default, makes the opposite tradeoff. This recipe does not resize or change format. Add `/image/resize` before optimization when the receiver requires fixed dimensions or a specific format. Store or deliver the original separately when recovery and future reprocessing matter. An unsupported image type can pass through `/image/optimize` unchanged, so use explicit validation when the receiver requires a constrained format. Optimize an image and deliver it over tus ``` { "allow_steps_override": false, "steps": { ":original": { "robot": "/upload/handle" }, "optimized": { "use": ":original", "robot": "/image/optimize", "priority": "compression-ratio", "preserve_meta_data": true, "lossy": false }, "delivered": { "use": "optimized", "robot": "/tus/store", "endpoint": "https://uploads.example.com/files/", "credentials": "my_tus_http_credentials" } } } ``` ## Encode a video before tus delivery For a video-only contract, connect `/video/encode` to the upload and give `/tus/store` the encoded Step. `web/mp4/720p` is a concrete resolution-qualified MP4 starting point, not a universal preset recommendation. Test source dimensions, frame rate, audio, captions, playback compatibility, processing time, and cost against the receiver’s actual requirements. Video encoding and the outbound tus transfer may both outlive an application request. Use Assembly Status or a verified completion callback, then check the receiving application’s own completion state. Store or relay the source separately when it is needed for higher-quality re-encoding, audit, recovery, or migration. Encode an MP4 and deliver it over tus ``` { "allow_steps_override": false, "steps": { ":original": { "robot": "/upload/handle" }, "encoded": { "use": ":original", "robot": "/video/encode", "preset": "web/mp4/720p" }, "delivered": { "use": "encoded", "robot": "/tus/store", "endpoint": "https://uploads.example.com/files/", "credentials": "my_tus_http_credentials" } } } ``` ## Choose headers, metadata, and reported URLs deliberately Use HTTP Template Credentials for static authorization headers. The Robot also accepts dynamic `headers`, but any value supplied by a browser can be read or changed there, so dynamic secrets belong in server-created and signed Instructions only. Destination metadata is a separate map: the Robot replaces caller-supplied `filename`, `basename`, and `extension` values with information from the processed file, while other keys pass through as authored. Keep metadata small, non-secret, and aligned with fields the receiver actually validates rather than treating it as authorization. Without a `url_template`, the Robot reports the upload URL returned by the destination. An omitted `ssl_url_template` can reuse that URL only when it starts with HTTPS. Templates change result presentation; they do not change receiver permissions, transform an upload URL into a download endpoint, or guarantee long-term stability. Record the receiver’s canonical asset identifier after it processes the upload. ## Test retries and reconcile both systems Exercise expired authorization, endpoint rejection, interrupted transfers, retries, duplicate deliveries, receiver timeouts, and receiver-side processing failures. Make completion handling idempotent because an Assembly notification or downstream event can be delivered more than once. The receiving system should reject cross-tenant context even when a client managed to alter non-secret metadata. Log the Assembly ID, destination endpoint class, and receiver asset ID without logging authorization headers. The roughly 24-hour window applies only to Transloadit’s temporary Assembly result copy, so reconcile the receiving system before that copy expires. Treat the product asset as ready only after the expected Assembly result was delivered and the receiver confirms the intended durable or published state. That explicit reconciliation is what turns a successful protocol handoff into a reliable application workflow. ## Technical details worth knowing * `/tus/store` exports the files selected by `use` to the required URL in its `endpoint` parameter. * The Robot accepts HTTP Template Credentials so static authorization headers can be sent to the destination without appearing in Instructions. * Optional dynamic `headers` are sent to the destination, but browser-visible secrets would remain exposed and should be avoided. * The Robot always sets the `filename`, `basename`, and `extension` metadata keys from the processed file, overriding caller-supplied values for those keys; other `metadata` keys pass through as authored. * When `url_template` is absent, the result uses the upload URL supplied by the destination tus server. * When `ssl_url_template` is absent, the destination upload URL populates the result’s `ssl_url` field only when that URL begins with HTTPS. * `/image/optimize` passes unsupported image types through unchanged, so validate inputs when the destination requires an optimized result. * `/video/encode` accepts presets such as `web/mp4/720p`, and each preset must be tested against the destination’s playback requirements. * Transloadit normally deletes temporary Assembly result files around 24 hours after processing, while current storage keeps them for at least 24 hours regardless of custom retention settings; durable retention belongs to the receiving tus destination. ## A practical approach 1. 1\ Confirm the destination implements the tus protocol and define what it does after a completed upload. 2. 2\ Create HTTP Template Credentials for static destination headers and save separate upload, image, and video Templates. 3. 3\ Test authentication, interrupted transfer recovery, duplicate delivery, result URL behavior, and receiver-side persistence. 4. 4\ Record the Assembly ID with the receiving system’s stable asset identity and reconcile completion idempotently. A four-stage media workflow ## When Transloadit is useful Use `/tus/store` when an existing destination accepts tus uploads and a Transloadit Assembly should deliver an original or processed result to it. Use a provider-specific storage Robot when Transloadit should understand a bucket API and storage-specific access settings. ## Architecture boundary `/tus/store` hands a selected Assembly result to a tus-compatible endpoint. Tus defines the resumable transfer, not the destination’s durability, authorization model, retention, publication state, or final download URL; the receiving service and your application own those contracts. ## Frequently asked questions ### Does the browser upload directly to my tus endpoint? No. The browser uploads to a Transloadit Assembly in these recipes. After processing, `/tus/store` acts as a tus client and uploads the selected result to your configured endpoint. The two transfers have separate URLs, credentials, progress, and retry boundaries. ### Does a successful tus upload guarantee durable storage? No. Tus standardizes resumable transfer. The receiving server decides whether the completed upload is durable, how long it is retained, who can access it, and whether the upload URL is also a download URL. Reconcile a receiver-side asset record rather than inferring those properties from protocol completion. ### How should the destination authenticate Transloadit? Use the HTTP credential type for static authorization headers and reference the credential name from `/tus/store`. Dynamic `headers` are supported for cases that cannot use static credentials, but never place sensitive headers in browser-visible Assembly Instructions. ### Can one Template handle files, images, and videos? Use separate Templates when validation and failure policies differ. A deliberately mixed Template can filter and branch by observed media type, then give each `/tus/store` Step only the result that its branch creates. ### Which URL appears in the Assembly result? By default, the Robot uses the upload URL returned by the tus server. `url_template` and `ssl_url_template` can shape reported URLs, but they do not prove that the URL is publicly readable or remains stable. Verify the receiver’s URL contract independently. ## Build the workflow Move from the concept to a tested Assembly with Robot documentation and working demos. ### Relevant Robots * [/tus/store](/docs/robots/tus-store.md) * [Export files to a tus server](/docs/robots/tus-store.md) * [Receive Assembly uploads](/docs/robots/upload-handle.md) * [Optimize images](/docs/robots/image-optimize.md) * [Encode videos](/docs/robots/video-encode.md) * [Protect destination headers](/docs/topics/template-credentials.md) * [Read the API documentation](/docs.md) * [Explore working demos](/demos.md) * [Create a free workspace](/c/signup/) Platforms and integrations ## Continue with related guides * [File Upload API guide: architecture, security, and provider selection](/guides/file-upload-api-guide.md)\ Choose and implement a File Upload API by comparing architecture, resumability, direct-to-cloud transfer, security, storage boundaries, and providers. * [How to accept large uploads that survive a dropped connection](/guides/resumable-uploads-for-large-files.md)\ Accept multi-gigabyte uploads over tus, continue them after a dropped connection, and keep the Assembly alive long enough to finish. * [File uploads, image optimization, video encoding, and your own S3 bucket](/guides/file-uploads-image-optimization-s3.md)\ Combine resumable browser uploads, image optimization, video encoding, customer-owned Amazon S3 storage, and on-demand image delivery without operating separate media services. * [Choose external storage for a media workflow](/guides/external-storage-media-workflows.md)\ Choose an external storage destination for Transloadit workflows by comparing storage models, credentials, access controls, URL behavior, and bulk-import needs. * [Four pillars of digital transformation in retail](/guides/retail-digital-transformation-pillars.md)\ Connect customer experience, operations, data, and platform modernization through a practical retail media layer. * [Magento media optimization for technical SEO](/guides/magento-media-seo.md)\ Improve Magento media performance and image search hygiene as part of a broader technical SEO program.