# Python SDK

> Learn how to generate images and PDFs with the bannerify Python package.

Canonical: https://bannerify.co/docs/sdk/python/overview

`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

<Tabs>
  <Tab title="pip">
    ```bash
    pip install bannerify
    ```
  </Tab>
  <Tab title="uv">
    ```bash
    uv add bannerify
    ```
  </Tab>
</Tabs>

## Create a client

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

```python
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:

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

## Generate an image

```python
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](https://bannerify.co/docs/sdk/python/apis/create-image) covers the first three, [Render videos](https://bannerify.co/docs/sdk/python/apis/render-video) covers the video methods, and [Signed URL](https://bannerify.co/docs/sdk/python/apis/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.

```python
{"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](https://bannerify.co/docs/api-reference/errors/introduction) 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

```python
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.

```python
from bannerify import Modification

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

## Related

- [Previous: Signed URLs in Go](https://bannerify.co/docs/sdk/go/apis/signed-url)
- [Next: Create images and PDFs in Python](https://bannerify.co/docs/sdk/python/apis/create-image)
- [Documentation index](https://bannerify.co/docs/llms.txt)