Use Templates

Templates let you store Assembly Instructions on our side, encrypted at rest. You then reference a Template by template_id in your API request.

This is safer than sending full instructions on every request, especially if your instructions contain third-party credentials.

Using Templates also improves operability:

1. You can change processing behavior without redeploying your app.
2. You can combine Templates with Assembly Notifications and Assembly Replays.
3. You can still override specific values at runtime when needed.

Learn more:

• Templates
• Template Credentials

Prefer asynchronous processing

If users have to wait for full processing before continuing, queue time directly impacts UX.

A better pattern:

1. Upload/import first.
2. Let processing continue asynchronously.
3. Use Assembly Notifications to update your backend when the Assembly completes.

This keeps your UI responsive and avoids users waiting on conversions.

Learn more: Webhooks and Notifications

Leverage Smart CDN for delivery

If you deliver processed assets to end users, use the Transloadit Smart CDN.

Key advantages:

1. Lower latency with edge delivery.
2. Better reliability under load.
3. Lower repeated processing and origin traffic via caching.

Best practices:

1. Configure caching behavior on 🤖/file/serve.
2. Prefer URL-based transformations where appropriate.
3. Keep cache keys stable and explicit.

Learn more: Content Delivery

Set a bill limit

While integrating, accidental loops can happen and create unexpected usage spikes. A bill limit is a useful safety guardrail.

Set it high enough to allow normal growth, but low enough to cap unexpected runaway behavior.

Read each Robot’s documentation

Demos are a great starting point, but production behavior often depends on options, edge cases, and limits documented per Robot.

Before rollout, validate your exact flow against the relevant Robot docs.

Do not rely on result ordering

Result arrays are not guaranteed to align by position across Steps. If you need to map processed files back to originals, match by IDs:

1. uploads[*].id
2. results[*].original_id

Use ignore_errors intentionally

The ignore_errors Step parameter keeps an Assembly moving when certain per-file errors are acceptable, which is useful for batch jobs or optional metadata extraction. It also makes failures less visible, so apply it deliberately:

1. Prefer targeted arrays like ["meta"] over true, so only the phases you expect to tolerate are ignored.
2. Monitor ignored_errors and ignored_error_count on the Assembly Status so silent failures are still surfaced to your team.

Learn more: The ignore_errors parameter

Keep your encoding stack current

We keep older stacks available to preserve backwards compatibility, but you should periodically upgrade to newer stacks for fixes, performance improvements, and codec/tooling updates.

Review stack settings at least once per year and test before switching production traffic.

Secure requests in browser-facing integrations

If requests can be generated client-side, assume your auth key may become visible. Use Signature Authentication and HTTPS endpoints (https://api2.transloadit.com).

This protects request integrity and helps prevent unauthorized usage.

Follow least-privilege credentials

When granting storage access (for example S3), scope credentials to the minimal required actions and paths. For example, write-only export credentials are often sufficient for 🤖/s3/store.

Process more files in fewer Assemblies where possible

Assemblies are heavier than individual file operations. Batching files into fewer Assemblies can improve throughput and reduce overhead, especially for large imports.

For imports, keep total batch size practical for retries and operational safety.

Do not go overboard with input files per Assembly

Very large input sets in one Assembly can backfire:

1. You can exceed your available priority job slots.
2. You increase the risk of hitting the 8-hour maximum Assembly execution time.

As a practical guideline, keep uploaded and imported input files to around 500 to 1000 files per Assembly, depending on the amount of work each file goes through.