Skip to main content
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

With no key and no 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 a JobComplete 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:
A job whose status is newer than your SDK comes back as 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>:
Each 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 a RendobarError 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.
A refusal that lists what is wrong has 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:
The same key with different params raises 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:
Pass the raw body, never parsed JSON. 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:
Both reconnect with backoff and resume after the last event they yielded, so you never see one twice. The key travels in the Authorization header, never in the URL. On AsyncRendobar the same methods return async generators.

Pagination

A list comes back as a Page: 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

Last modified on November 22, 2026