bannerbear 1.0.0

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

Bannerbear Python Library

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

Documentation

Find the full API documentation here.

Requirements

Python 3.8 or higher.

Installation

pip install bannerbear

V5 API

The V5 API 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
• Account
• Image Templates
• Images
• Batches
• Webhooks
• Instant URLs

Authentication

from bannerbear.v5 import Client

bb = Client("your V5 API key")

Or set BANNERBEAR_API_KEY and instantiate without arguments:

bb = Client()

Account

bb.account()

Image Templates

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

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:

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)

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

Batches

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

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.

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:

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

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:

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.

# 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.