Transloadit

Python SDK

transloadit/python-sdk

Install

The SDK is published on PyPI as pytransloadit. Version 2 requires Python 3.12 or newer:

python -m pip install --upgrade 'pytransloadit>=2,<3'

That command fails on Python 3.9 to 3.11. There, a plain pip install pytransloadit installs 1.0.4, the latest 1.x release. To stay on 1.x explicitly, pin it below version 2:

python -m pip install 'pytransloadit<2'

Usage

import os

from transloadit import client

tl = client.Transloadit(os.environ['TRANSLOADIT_KEY'], os.environ['TRANSLOADIT_SECRET'])
assembly = tl.new_assembly()
assembly.add_step('resize', '/image/resize', {'width': 70, 'height': 70})
with open('PATH/TO/FILE.jpg', 'rb') as upload:
    assembly.add_file(upload)
    assembly_response = assembly.create(retries=5, wait=True)

if 'error' in assembly_response.data:
    raise RuntimeError(assembly_response.data['error'])
print(assembly_response.data['assembly_id'])

create(wait=True) returns once the Assembly has finished. API errors come back in the response instead of being raised, which is why the example checks for an error key before it uses the results.

Async usage

AsyncTransloadit is an asyncio client for apps built on FastAPI, aiohttp, or other async frameworks. It sends API requests through aiohttp and polls Assembly status with asyncio.sleep, so waiting for an Assembly doesn’t block the event loop:

import asyncio
import os

from transloadit.async_client import AsyncTransloadit


async def main():
    key = os.environ['TRANSLOADIT_KEY']
    secret = os.environ['TRANSLOADIT_SECRET']
    async with AsyncTransloadit(key, secret) as tl:
        assembly = tl.new_assembly()
        assembly.add_step('resize', '/image/resize', {'width': 70, 'height': 70})
        with open('PATH/TO/FILE.jpg', 'rb') as upload:
            assembly.add_file(upload)
            response = await assembly.create(wait=True, resumable=False)
    if 'error' in response.data:
        raise RuntimeError(response.data['error'])
    print(response.data['assembly_id'])


asyncio.run(main())

The async client mirrors the sync one: Assemblies, Templates, monthly billing, and Smart CDN URL signing. Await the methods that make network requests. new_assembly(), new_template(), and get_signed_smart_cdn_url() stay synchronous. Keep the file open until the awaited create() call returns.

Use the client with async with, or call await tl.aclose() when you’re done with it. You can pass your own aiohttp session with session=. Resumable uploads, the default for create(), go over tus in worker threads, so the event loop stays responsive while large files upload. Those transfers don’t use your aiohttp session, though: configure their proxy and TLS settings through the Requests environment instead.

Upgrade from 1.x

Synchronous code written for 1.x keeps working: from transloadit import client and its methods are unchanged in version 2. Before you upgrade, check:

  • Python 3.12 or newer. Upgrade your development, CI, and deployment interpreters first.
  • Dependency floors. Version 2 requires requests>=2.33,<3 and urllib3>=2.7,<3. Loosen older pins in your constraints and regenerate your lockfile.
  • Redirects. HTTP redirects are returned to you instead of followed.
  • Input validation. Invalid service URLs and empty Template IDs raise ValueError.
  • Templates. When you combine a template option with add_step(), pass the template value as a dict, not as a JSON string.
  • Responses. A non-JSON response puts text or bytes in Response.data, and an empty body gives an empty string.
  • Polling. With wait=True, running out of retries on rate-limited status checks raises AssemblyPollingError. The Assembly may still be running: use the error’s assembly_url to poll again or cancel it.
  • Assembly URLs. Status and cancel requests only go to trusted Assembly URLs, and the default client rejects other hosts.
  • Smart CDN. Boolean parameters are signed as true and false, matching our Node.js reference implementation. Workspace slugs must be DNS-safe, and auth_key, exp, and sig are reserved query keys.

The README and the changelog have the full upgrade notes.

Example

For fully working sync and async examples, take a look at examples/.

Documentation

See Read the Docs for the full API reference of both clients. The source code and issue tracker live on GitHub, and releases on PyPI.