Download the PHP package yongfook/bannerbear without Composer

Bannerbear PHP Library

A PHP wrapper for the Bannerbear API - an image and video generation service.

Documentation

Find the full API documentation here

Requirements

PHP 7.4 or Higher

Installation

Install the package with:

To use the bindings, load it via Autoload

V5 API

The V5 API is a new generation of the Bannerbear API. V5 API keys do not work with V2 endpoints, and V2 API keys do not work with V5 endpoints — you must use the right client class for your key.

For the V5 API, use Bannerbear\V5\Client (this section). For the legacy V2 API, see Usage below — that section is unchanged.

Table of Contents

• Authentication (V5)
• Account (V5)
• Image Templates (V5)
• Images (V5)
• Animation Templates (V5)
• Animations (V5)
• Workflows (V5)
• Workflow Runs (V5)
• Tools (V5)
• Assets (V5)
• Publications (V5)
• Batches (V5)
• Webhooks (V5)
• Instant URLs (V5)

Authentication (V5)

Or set BANNERBEAR_API_KEY and instantiate without arguments:

Account (V5)

Image Templates (V5)

V5 renames V2's templates resource to image_templates. Templates can be created, updated, and deleted through the API — config holds the full canvas.

Options for create_image_template / update_image_template

• name required for create (string)
• description (string)
• tags (array)
• width / height: canvas size in pixels (integer)
• config: full canvas configuration, ["objects" => [...]]. Passing it replaces the existing config in place (array)

Deleting is a soft delete: images already rendered from the template stay intact, but the template no longer appears in list/get calls and cannot be used for new renders.

Images (V5)

V5's modifications is an associative array with two sub-keys:

• template — template-level changes (width, height, etc.)
• objects — array of per-layer changes (equivalent to V2's flat modifications array)

Synchronous generation routes to sync.api.bannerbear.com/v5 (10s timeout). The 3rd positional synchronous argument is a transport switch — it is not sent in the request body:

Options for create_image

• modifications: V5 modifications array (array)
• formats: output formats, e.g. ["jpg", "pdf"] (array)
• scale: scale multiplier, 1–4 (integer)
• dpi: DPI metadata (integer)
• quality: quality control (integer)
• proxy: proxy and resize external images before rendering (boolean)
• metadata: include any metadata to reference at a later point (string)
• version: pin template version (integer)
• 3rd positional synchronous: route to the sync host (boolean; SDK-only, not sent to the API)

Animation Templates (V5)

Animation templates render video instead of a still image. They carry a frame_rate and a duration_seconds in place of the image template's static canvas.

Options for create_animation_template / update_animation_template

• name required for create (string)
• description (string)
• tags (array)
• width / height: canvas size in pixels, 100–3000 (integer)
• frame_rate: 24, 30, or 60 (integer)

Animations (V5)

Rendering an animation is always asynchronous — there is no sync host for animations. Poll get_animation until the status is "completed" or "failed", or subscribe to a webhook with the resource "animation".

Options for create_animation

• modifications: V5 modifications array (array)
• formats: ["mp4"] or ["mov"]. Ignored when transparent is set — that always yields MOV (array)
• metadata: include any metadata to reference at a later point (string)

Template-level modification keys for animations: width, height, fps (24, 30, or 60), and transparent. Setting transparent renders on a transparent background and forces a MOV output, so the alpha channel survives.

Workflows (V5)

Workflows chain several steps into one named, re-runnable operation. They are read-only through the API — build them in the Bannerbear UI, then run them here.

Workflow Runs (V5)

A run is asynchronous. Poll get_workflow_run until the status is "completed" or "failed", or subscribe to a webhook with the resource "workflow_run".

Options for create_workflow_run

• inputs: values for the workflow's declared inputs (array)

Tools (V5)

Tools are standalone media operations that do not use a template. Every tool is asynchronous: the call returns a pending tool job. Poll get_tool_job until the status is "completed" or "failed", or subscribe to a webhook with the resource "tool_job".

Every tool also accepts an optional metadata string.

Place the two overlay tools with either position (plus an optional margin) or x/y — not both. position accepts top_left, top_center, top_right, center, bottom_left, bottom_center, and bottom_right. resize_video accepts a fit of cover (crops), contain (letterboxes), or blur (fills the bars with a blurred copy).

A few examples:

create_tool_job calls any tool by name — the escape hatch for tools added after this release:

Assets (V5)

Upload a file (max 5MB) and get back a durable CDN URL you can feed to image modifications or tools. Uploads are deduplicated per workspace by SHA-256, so re-uploading the same bytes returns the existing record instead of creating a duplicate.

Accepted mime types: image/jpeg, image/png, image/webp, image/gif, video/mp4, video/webm, video/quicktime, audio/mpeg, audio/wav, audio/mp4, audio/webm, audio/ogg, application/pdf.

check_assets maps each SHA-256 content hash to its existing asset (or null), so a syncing client can skip the upload round-trip for content it already pushed. Max 100 hashes per call.

Publications (V5)

Publications are templates published to the public library. Installing one clones it into your workspace as a new image template.

Batches (V5)

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

Webhooks (V5)

Webhooks are managed as a first-class resource in V5 (instead of being a per-request webhook_url parameter).

Options for create_webhook / update_webhook

• name required (string)
• url required — the URL that receives the events (string)
• resource: "image", "batch", "tool_job", "animation", or "workflow_run" (string)
• event: "all_events", "completed", or "failed" (string)
• status: "active" or "disabled" (string)

CRUD:

Instant URLs (V5)

Instant URLs are URLs bound to a template that can be manipulated with query strings — the V5 equivalent of V2's "Signed URLs" feature.

Create an Instant URL base

Options for create_instant_url / update_instant_url

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

CRUD:

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.

Options for build_instant_url

• mode: "encoded" (default) or "named_params" (string)
• signing_key: only needed when the instant URL was created with security: "signed" (string)
• modifications: same shape as create_image's modifications (array)

Usage

Table of Contents

• Authentication
• Account Info
• Images
• Videos
• Collections
• Animated Gifs
• Movies
• Screenshots
• Templates
• Template Sets
• Video Templates
• Signed URLs

Please note that all methods return dictionaries/associative arrays. Responses can be found in the developer documentation here.

Authentication

Get the API key for your project in Bannerbear and then instantiate a new client.

Alternatively, set the API key in an environment variable named BANNERBEAR_API_KEY.

Account Info

Return info about the account or project associated with the API key.

Images

Create an Image

To create an image you reference a template uid and a list of modifications. The default is async generation meaning the API will respond with a pending status and you can use get_image to retrieve the final image.

You can also create images synchronously - this will take longer to respond but the image will be delivered in the response:

Options

• modifications: an array of modifications you would like to make (array)
• webhook_url: a webhook url to post the final image object to (string)
• transparent: render image with a transparent background (boolean)
• synchronous: generate the image synchronously (boolean)
• render_pdf: render a PDF in addition to an image (boolean)
• metadata: include any metadata to reference at a later point (string)

Get an Image

List all images

Optionally you can provide a page and limit

Videos

Create a Video

Options

• input_media_url: a url to a publicly available video file you want to import (string)
• modifications: an array of modifications you would like to make to the video overlay (array)
• webhook_url: a webhook url to post the final video object to (string)
• blur: blur the imported video from 1-10 (integer)
• trim_to_length_in_seconds: trim the video to a specific length (integer)
• create_gif_preview: create a short preview gif (boolean)
• metadata: include any metadata to reference at a later point (string)

If your video is using the "Multi Overlay" build pack then you can pass in a set of frames to render via:

• frames: an array of sets of modifications (array)
• frame_durations: specify the duration of each frame (array)

Get a video

Update a Video

Options

• approved: approve the video for rendering (boolean)
• transcription: an array of strings to represent the new transcription (will overwrite the existing one) (array)

List all Videos

Options

• page: pagination (integer)

Collections

Create multiple images in one API request.

Options for create_collection

• modifications: an array of modifications you would like to make (array)
• webhook_url: a webhook url to post the final collection object to (string)
• transparent: render image with a transparent background (boolean)
• synchronous: generate the images synchronously (boolean)
• metadata: include any metadata to reference at a later point (string)

Animated Gifs

Create a slideshow style gif

Options for create_animated_gif

• frames: an array of arrays of modifications you would like to make (array)
• frame_durations: an array of times (in seconds) to show each frame (array)
• input_media_url: optionally import an external video file to use as part of the gif
• fps: frames per second e.g. 1 (integer)
• loop: whether to loop or not (boolean)
• webhook_url: a webhook url to post the final gif object to (string)
• metadata: include any metadata to reference at a later point (string)

Movies

Assemble video clips or still images into a single movie with transitions.

Options for create_movie

• width: the movie width in pixels (integer)
• height: the movie height in pixels (integer)
• transition: the transition style: fade, pixelize, slidedown, slideright, slideup, slideleft (string)
• inputs: a list of inputs (array)
• webhook_url: a webhook url to post the final movie object to (string)
• metadata: include any metadata to reference at a later point (string)

Screenshots

Take screenshots of websites.

Options for create_screenshot

• width: the desired screenshot width in pixels (integer)
• height: the desired screenshot height in pixels (integer)
• synchronous: generate the screenshot synchronously (boolean)
• mobile: use a mobile user agent
• webhook_url: a webhook url to post the final screenshot object to (string)

Templates

Template Sets

Video Templates

Signed URLs

This gem also includes a convenient utility for generating signed urls. Authenticate as above, then:

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/yongfook/bannerbear-php. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Bannerbear project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.