Overview

Get started with our Python SDK, bannerify, for a typed and efficient experience. This SDK allows you to interact with our API without having to make HTTP requests directly.

Install

Install via pip:

pip install bannerify

Or with Poetry:

poetry add bannerify

Instantiate

If you want to use SDK, you will need your API key — you can create a new one in the settings.

from bannerify import BannerifyClient

client = BannerifyClient("your-api-key")

Response format

To make error handling explicit and prevent forgotten error checks, we return errors as part of the response structure. Every method returns a dict with either a result or an error field, never both and never none.

{
    "result": ... # the result depends on what method you called (e.g., bytes for images)
}

{
    "error": {
        # A machine readable error code
        "code": "ERROR_CODE",
        
        # A link to our documentation explaining this error
        "docs": "https://bannerify.co/docs",
        
        # A human readable explanation
        "message": "Error message"
    }
}

Checking for errors

To check for errors, use the error key in the response:

from bannerify import BannerifyClient

client = BannerifyClient("your-api-key")

result = client.create_image(
    "tpl_xxxxxxxxx",
    modifications=[
        {"name": "title", "text": "Hello World"}
    ]
)

if "error" in result:
    # Handle error
    print(f"Error: {result['error']['message']}")
else:
    # Process result
    with open("output.png", "wb") as f:
        f.write(result["result"])

Options

The constructor accepts options to customize the behavior:

API Key

client = BannerifyClient("my-api-key")

Custom Configuration

client = BannerifyClient(
    "my-api-key",
    server_url="https://api.bannerify.co",
    timeout_ms=60000
)

Examples

Generate PNG Image

result = client.create_image(
    "tpl_xxxxxxxxx",
    modifications=[
        {"name": "title", "text": "Hello World"},
        {"name": "subtitle", "text": "From Python SDK"}
    ]
)

if "result" in result:
    with open("output.png", "wb") as f:
        f.write(result["result"])

Generate WebP Image

result = client.create_image(
    "tpl_xxxxxxxxx",
    format="webp",
    modifications=[
        {"name": "title", "text": "Hello WebP"}
    ]
)

if "result" in result:
    with open("output.webp", "wb") as f:
        f.write(result["result"])

Generate Signed URL

signed_url = client.generate_image_signed_url(
    "tpl_xxxxxxxxx",
    modifications=[
        {"name": "title", "text": "Dynamic Title"}
    ]
)

print(f"<img src='{signed_url}' alt='Generated Image' />")