rendobar is the official Python client for Rendobar’s media processing and AI generation API: sync and asyncio clients, params typed per job type, retries that never create a second job, and responses already unwrapped from the { data } envelope. It runs on Python 3.10 to 3.13.
Overview and examples: Python SDK integration.
transcode.py
jobs.run submits the job and waits for it. It returns a JobComplete, and raises JobFailedError when the job fails or is cancelled. The with block closes the client’s connections when it ends. A client you keep for the life of your app can skip it and call rb.close() at shutdown.
Client options
RENDOBAR_API_KEY, jobs.types() and jobs.schema() still work, since they need no key. Every other call raises AuthenticationError with code MISSING_API_KEY before it sends anything.
asyncio
AsyncRendobar takes the same arguments and has the same methods as Rendobar, awaited. Every example below works on both.
Jobs
The first argument says what to run:
type, params and, for job types that read files, inputs. Each is per job type. Everything about how to run it is a keyword argument: idempotency_key, label, destinations, callback and force_async on create, and timeout, interval, max_interval, on_progress and throw_on_failure on wait. run takes all of them.
Typed params
The job dict is typed per job type. Pyright, mypy and your editor know each type’s params, so a misspelt or missing param, a wrong value type, or an unknown job type fails the type check before anything runs. Enum params are closed sets, so"compute": "tpu" fails too.
A dict built in a variable first needs the annotation, or the checker infers a plain dict:
UntypedJob(type, params) submits a job type newer than your installed SDK, and compose, whose nested timeline the SDK leaves untyped. The API validates it.
Wait
wait polls until the job is complete, failed, or cancelled. Polling starts at 2 s and backs off to 10 s. Past the timeout it raises WaitTimeoutError with the job id and the last status seen. The job may still finish.
With no timeout, the wait allows 5 minutes. Once the job reports its own budget (your plan’s per-job limit), the wait extends to that budget plus 2 minutes, so a long job is never reported as timed out while it runs. wait returns a failed job unless you pass throw_on_failure=True.
Read the output
A job is one class per status. Only aJobComplete has output, and only a JobFailed has error, so check which one you have:
output.file is the headline file (the single file, or the HLS or DASH manifest) and is None for data-only jobs. The output shape is the same for every job type. A job type with a typed result reads it with output_data. Today that is ffprobe:
UnknownJob with id, status and raw, rather than raising.
Uploads and assets
uploads.create sends a local file (a path, or bytes with a filename) to storage on presigned URLs and returns the ready Asset. A large file goes up in parts, in parallel, and a file on disk is streamed, never read into memory whole. A job reads the asset as asset://<id>:
inputs key is the filename staged in the working directory, and the command refers to it by that bare name. An upload expires after 24 hours unless you pass persist=True. assets.list, assets.get, assets.delete and assets.download manage what the workspace holds.
To deliver outputs to a connected bucket, pass destinations=["storage://<id>/<folder>"] to jobs.create or jobs.run.
Errors
Everything the SDK raises is aRendobarError with a code. API refusals raise a subclass per status: BadRequestError (400), AuthenticationError (401), InsufficientCreditsError (402), PermissionDeniedError (403), NotFoundError (404), ConflictError (409), RateLimitError (429) and InternalServerError (5xx). Each carries status_code and request_id.
problems, each with a path, a message and, on a plan refusal, upgrade_to. APIConnectionError and APITimeoutError mean no response arrived. JobFailedError, WaitTimeoutError and WebhookSignatureError come from run, wait and webhook parsing. Compare code with strings, since a newer API can send a code your SDK does not list. The codes are in the error catalogue.
Retries and idempotency
429, 500, 502, 503, 504 and a connection that could not be made are retried twice by default (max_retries). A 5xx is retried only for a request that is safe to repeat: a read, a job submit, a cancel. A write such as webhooks.create() raises at once, since it may have taken effect. The client honours Retry-After up to 60 seconds, and otherwise backs off from half a second with jitter.
A retried submit never creates a second job. With no idempotency_key, jobs.create generates one for that call and sends it on every retry. Pass your own key, such as an order id, to make separate calls safe to repeat:
ConflictError (409). When a submit fails in a way that may still have created the job, the error’s idempotency_key holds the key that was sent. Submit again with it to get that job, not a second one. generate_idempotency_key() makes keys of the same kind.
Webhooks
webhooks.create(name=..., url=..., subscribed_events=[...]) registers an endpoint and returns its signing_secret, in plaintext only there and in rotate_secret(). test, list_deliveries and retry_delivery operate it.
Verify and read every delivery with rendobar.webhooks.parse:
parse checks the HMAC over {timestamp}.{body}, rejects deliveries more than 5 minutes old, and accepts the previous secret during a rotation. It returns the event typed by name, and an event newer than your SDK as UnknownWebhookEvent, never as an exception. verify() is the signature check alone, as a bool. Event payloads are in the webhooks guide.
Realtime
realtime.subscribe_job streams one job over a WebSocket and stops after its final status. realtime.connect streams every event in the org. Both need the realtime extra:
Authorization header, never in the URL. On AsyncRendobar the same methods return async generators.
Pagination
A list comes back as aPage: iterate it, or read data and meta.total. jobs.list_all fetches every page as you iterate, 100 jobs at a time:
Examples
The examples folder has small projects that run end to end: a quickstart, an upload trimmed by ffmpeg and streamed back to disk, a batch worker with idempotency keys and error handling, a webhook receiver, an account admin script, and a job followed live over the event stream. It also has a FastAPI app and Django views that submit a job and verify a webhook.Versioning
The package follows semantic versioning. While it is at 0.x, a minor release may tighten types, and the changelog says so. Deprecations are announced before anything is removed. See versioning and deprecations and the changelog.See also
- Job types: the type, inputs, and params for every job
- How a job works: statuses and the output shape
- Webhooks: event payloads and delivery retries
- Error codes: every code a request or job returns