Python SDK | Bannerify Docs

bannerify is the Bannerify client for Python 3.8 and later. It returns errors as values, so a failed request does not raise an exception.

Install

Examples

Open only what you need

pip

pip install bannerify

uv add bannerify

Create a client

You need an API key. Create one on the API Keys page of the dashboard and keep it on the server.

import os

from bannerify import BannerifyClient

client = BannerifyClient(os.environ["BANNERIFY_API_KEY"])

The client holds an HTTP connection pool. Call client.close() when you finish, or use the client as a context manager:

with BannerifyClient(os.environ["BANNERIFY_API_KEY"]) as client:
    result = client.create_image("tpl_xxx")

Generate an image

result = client.create_image(
    "tpl_xxx",
    modifications=[{"name": "headline", "text": "Summer sale"}],
)

if "error" in result:
    raise RuntimeError(result["error"]["message"])

with open("banner.png", "wb") as file:
    file.write(result["result"])

result["result"] holds the image bytes.

Methods

Method	Result	Use it to
`create_image`	`bytes`	Get the image bytes
`create_pdf`	`bytes`	Get a PDF
`create_stored_image`	URL string	Get a hosted image URL
`render_video` (Beta)	Iterator of events	Render a video and follow its progress
`render_and_wait_video` (Beta)	URL string	Render a video and get its MP4 URL
`create_video` (Beta)	Created video dict	Start a video and get its id at once, without waiting
`get_video` (Beta)	Video dict	Read the status and the MP4 URL of a video by its id
`watch_video` (Beta)	Iterator of events	Follow the progress of a video again by its id
`generate_image_signed_url`	URL string	Build a link that renders when someone opens it

Create images and PDFs covers the first three, Render videos covers the video methods, and Signed URL covers the last one.

Handle errors

Every method except generate_image_signed_url returns a dict with a result key or an error key, and never both.

{"result": b"..."}

{"error": {"code": "NOT_FOUND", "message": "...", "docs": "...", "requestId": "..."}}

An error from the API has all four keys. docs links to the page for that code, and you send requestId to support when you need help with a request. Errors lists the codes.

The SDK creates a few errors itself. They have code, message, and docs, but no requestId.

Code	Meaning
`INVALID_FORMAT`	The format is not `png`, `jpeg`, or `webp`
`TIMEOUT`	The request ran past the timeout
`TIMEOUT_ERROR`	A video stream dropped and the SDK could not read the video again
`REQUEST_ERROR`	The request failed before the API answered, for example when the connection dropped
`HTTP_ERROR`	The API answered with an error that the SDK could not read
`EXCEPTION`	Any other exception inside the SDK. `message` holds its text

generate_image_signed_url returns a string and raises ValueError when the format is not supported.

Options

client = BannerifyClient(
    os.environ["BANNERIFY_API_KEY"],
    timeout=30.0,
)

Option	Default	Description
`base_url`	`https://api.bannerify.co/v1`	The API base URL
`timeout`	`60.0`	Request timeout in seconds

Modification models

A modification is a dict. You can also pass Modification models from bannerify, and the client converts them for you.

from bannerify import Modification

client.create_image("tpl_xxx", modifications=[Modification(name="headline", text="Hello")])