> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.bannerify.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Learn how to generate images and PDFs with the Bannerify Python SDK.

Use `bannerify` to call the Bannerify API from Python without writing raw HTTP requests.

## Install

Install via pip:

```bash theme={null}
pip install bannerify
```

Or with Poetry:

```bash theme={null}
poetry add bannerify
```

## Instantiate

You need a project API key before using the SDK. Create one in **Dashboard → API Keys** and keep it server-side.

```python theme={null}
from bannerify import BannerifyClient

client = BannerifyClient("bnfy_xxx")
```

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

<CodeGroup titles={["Success", "Error"]}>
  ```python theme={null}
  {
      "result": ... # the result depends on what method you called (e.g., bytes for images)
  }
  ```

  ```python theme={null}
  {
      "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"
      }
  }
  ```
</CodeGroup>

## Checking for errors

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

```python theme={null}
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

```python theme={null}
client = BannerifyClient("my-api-key")
```

### Custom Configuration

```python theme={null}
client = BannerifyClient(
    "my-api-key",
    server_url="https://api.bannerify.co",
    timeout_ms=60000
)
```

## Examples

### Generate PNG Image

```python theme={null}
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

```python theme={null}
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

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

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