File Uploads, Image Optimization, Video Encoding and tus Delivery

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.

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 signing Instructions only guarantees their integrity, never their confidentiality: a browser can read everything it submits. Dynamic secrets must therefore never appear in browser-visible Instructions. Keep them in Template Credentials, or submit the Assembly server-to-server so the values never reach the browser. 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
Confirm the destination implements the tus protocol and define what it does after a completed upload.
2
Create HTTP Template Credentials for static destination headers and save separate upload, image, and video Templates.
3
Test authentication, interrupted transfer recovery, duplicate delivery, result URL behavior, and receiver-side persistence.
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.

File uploads, image optimization, and video encoding to a tus server