Metadata-Version: 2.4
Name: bannerbear
Version: 1.0.0
Summary: Bannerbear API wrapper for Python — an image and video generation service.
Project-URL: Homepage, https://github.com/yongfook/bannerbear-python
Project-URL: Documentation, https://developers.bannerbear.com/v5/
Author-email: Jon Yongfook <yongfook@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Jon Yongfook
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: requests>=2.25
Description-Content-Type: text/markdown

# Bannerbear Python Library

A Python wrapper for the Bannerbear API — an image and video generation service.

## Documentation

Find the full API documentation [here](https://developers.bannerbear.com/v5/).

## Requirements

Python 3.8 or higher.

## Installation

```sh
pip install bannerbear
```

## V5 API

The [V5 API](https://developers.bannerbear.com/v5/) is the current generation of the Bannerbear API. V5 API keys are not compatible with V2 endpoints, and vice versa.

> This library currently ships the V5 client only. V2 support may be added in a future release under `bannerbear.v2`.

### Table of Contents

- [Authentication](#authentication)
- [Account](#account)
- [Image Templates](#image-templates)
- [Images](#images)
- [Batches](#batches)
- [Webhooks](#webhooks)
- [Instant URLs](#instant-urls)

### Authentication

```python
from bannerbear.v5 import Client

bb = Client("your V5 API key")
```

Or set `BANNERBEAR_API_KEY` and instantiate without arguments:

```python
bb = Client()
```

### Account

```python
bb.account()
```

### Image Templates

```python
bb.list_image_templates(page=1)
bb.get_image_template("template uid")
bb.update_image_template("template uid", {
    "name": "New Name",
    "description": "...",
    "tags": ["portrait"],
})
```

### Images

V5's `modifications` is a dict with two sub-keys:

- `template` — template-level changes (width, height, etc.)
- `objects` — list of per-layer changes

```python
bb.create_image("template uid", {
    "modifications": {
        "template": {"width": 1080, "height": 1080},
        "objects": [
            {"name": "headline", "text": "Hello World!"},
            {
                "name": "photo",
                "image_url": "https://images.unsplash.com/photo-1555400038-63f5ba517a47?w=1000&q=80",
            },
        ],
    },
})
```

Synchronous generation routes to `sync.api.bannerbear.com/v5` (10s timeout). `synchronous` is a keyword-only flag — it's a transport switch and is **not** sent in the request body:

```python
bb.create_image("template uid", {"modifications": {"objects": [...]}}, synchronous=True)
```

##### Options for `create_image`

- `modifications`: V5 modifications dict
- `formats`: output formats, e.g. `["jpg", "pdf"]`
- `scale`: scale multiplier, 1–4
- `dpi`: DPI metadata
- `quality`: quality control
- `proxy`: proxy server for asset fetching
- `metadata`: include any metadata to reference at a later point
- `version`: pin template version
- `synchronous` (keyword-only): route to the sync host (SDK-only, not sent to the API)

```python
bb.get_image("image uid")
bb.list_images(page=1)
```

### Batches

Generate multiple images in one request (up to 100).

```python
bb.create_batch({
    "type": "image",
    "items": [
        {"template": "template uid 1", "modifications": {"objects": [...]}},
        {"template": "template uid 2", "modifications": {"objects": [...]}},
    ],
})
bb.get_batch("batch uid")
bb.list_batches(page=1)
```

### Webhooks

Webhooks are managed as a first-class resource in V5.

```python
hook = bb.create_webhook({
    "name": "my-webhook",
    "url": "https://example.com/hook",
    "resource": "image",
    "event": "completed",
    "status": "active",
    "scope": "all",
    "templates": [],
})

# IMPORTANT: signing_key is ONLY returned in the create response. Store it now —
# subsequent get_webhook calls will not include it.
print(hook["signing_key"])
```

CRUD:

```python
bb.get_webhook("webhook uid")
bb.update_webhook("webhook uid", {
    "name": "renamed",
    "url": "https://example.com/hook",
    "resource": "image",
    "event": "completed",
    "status": "active",
    "scope": "all",
})
bb.delete_webhook("webhook uid")
bb.list_webhooks(page=1)
```

### Instant URLs

Instant URLs are URLs bound to a template that can be manipulated with query strings.

#### Create an Instant URL base

```python
iurl = bb.create_instant_url({
    "name": "my-instant-url",
    "template": "template uid",
    "mode": "encoded",         # or "named_params"
    "security": "signed",      # or "open"
    "status": "active",
    "scale": 1,                # 1, 2, 3, or 4
})

# IMPORTANT: signing_key is ONLY returned in the create response. Store it now.
print(iurl["signing_key"])
print(iurl["base_url"])
```

##### Options for `create_instant_url` / `update_instant_url`

- `name` *required*
- `template` *required* — image template UID
- `mode`: `"encoded"` or `"named_params"`
- `security`: `"signed"` or `"open"`
- `status`: `"active"` or `"disabled"`
- `scale`: 1, 2, 3, or 4
- `rate_limit`: enable per-IP rate limiting
- `template_version`: pin template version
- `max_renders`: cap total renders
- `expires_at`: ISO 8601 expiry

CRUD:

```python
bb.get_instant_url("uid")
bb.update_instant_url("uid", {"name": "...", "template": "...", ...})
bb.delete_instant_url("uid")
bb.list_instant_urls(page=1)
```

#### Build an Instant URL with modifications

`build_instant_url` is a pure local helper — no API call. It composes the URL from a base + modifications and, if a signing key is provided, appends the HMAC signature.

```python
# Encoded mode, signed
bb.build_instant_url(
    iurl["base_url"],
    mode="encoded",
    signing_key=iurl["signing_key"],
    modifications={
        "template": {"width": 1030, "height": 890},
        "objects": [{"name": "title", "text": "Hello!", "color": "#ffffff"}],
    },
)

# Named params mode, signed
bb.build_instant_url(
    iurl["base_url"],
    mode="named_params",
    signing_key=iurl["signing_key"],
    modifications={
        "template": {"width": 1030, "height": 890},
        "objects": [{"name": "title", "text": "Hello!"}],
    },
)

# Open (unsigned): omit signing_key
bb.build_instant_url(
    iurl["base_url"],
    mode="encoded",
    modifications={"objects": [{"name": "title", "text": "Hello!"}]},
)
```

##### Options for `build_instant_url`

- `base_url` (positional, required) — from the `create_instant_url` response
- `modifications` (kwarg, required) — same shape as `create_image`'s modifications
- `mode` (kwarg) — `"encoded"` (default) or `"named_params"`
- `signing_key` (kwarg) — only needed when the instant URL was created with `security="signed"`

## License

MIT. See [LICENSE](LICENSE).
