Bannerbear

DESIGN · FILES & DOCS

Templates, image and video renders, and batches run on their own key.

Connect Bannerbear with Fabriq Developer

Your user pastes their Bannerbear credential on a page Agentic Fabriq hosts, so it never reaches your backend and never becomes one shared key across all of your users. Same call as OAuth, one more argument.

from af_sdk import AgenticFabriq

af = AgenticFabriq()                      # reads AF_APP_ID / AF_APP_SECRET

url = await af.initiate_connection(request, provider="bannerbear", method="api_key")
return redirect(url)                      # an AF-hosted page, not yours

async with await af.for_user(request) as session:
    tools = await session.get_tools()     # only what this user granted

Provider names are surfaces, not vendors, and the authoritative list is the capabilities endpoint rather than any page including this one — an unknown name returns 400 with the valid list. Fabriq Developer is free to start and needs no provider paperwork. Start free or read the quickstart.

Connecting Bannerbear in practice

Bannerbear is asynchronous by default: a POST returns 202 Accepted and the finished image arrives by webhook or polling, so an agent that reads the POST response body gets no image. Bannerbear also publishes two different rate limits for itself — 60 POST requests per 10-second window in the API reference, 30 requests per 10 seconds in the help centre — and neither page says which API version its figure describes.

Scopes that draw scrutiny

Master API Key (Full Access) Bannerbear’s wording is that it "grants complete access to all projects and API endpoints". It also changes the request shape: with one "you need to add a project_id parameter to your requests", which a project key must not send.
An unscoped V5 key The permissive default rather than the restrictive one: "An unscoped key has full access." Omitting the scope list is what grants everything.
images:write, animations:write, workflows:write The V5 write scopes. Every call they permit consumes monthly API credits, so these are the scopes that cost money per request rather than merely reading data.
webhooks:read-write Lets a key change where generated media is delivered, which redirects output rather than reading it.

Rate limits

The API reference states "The Bannerbear API rate limit is 60 POST requests per 10 second window." The help centre states the limit "is currently 30 requests per 10 seconds". Exceeding it returns 429.
Monthly API credits are a separate budget that resets on the 1st of each month for paid plans: 1,000 credits on Automate at $49/month, from 10,000 on Scale at $149/month, from 50,000 on Enterprise at $299/month. "Trial accounts get a fixed non-renewable 30 API credits."
Exhausting the credit quota returns 402 Payment Required — "Your API quota is exhausted. Upgrade to continue" — not 429.
Synchronous requests to sync.api.bannerbear.com carry "a timeout of 10 seconds" and return 408 past it.

Worth knowing

The synchronous escape hatch is a different host, sync.api.bannerbear.com, and its ten-second timeout means anything slower has to go back to webhooks or polling.
Two live API generations need their own credentials: "V5 API Keys are not compatible with V2 endpoints, and vice versa."
Credits do not carry over and cannot be topped up, so quota exhaustion is a runtime 402 that only a plan upgrade clears — it is not a billing detail you can settle later.
Swapping key type changes the request body as well as the permission, because a Full Access master key requires a project_id parameter on standard endpoints that a project-scoped key omits.

Checked against Bannerbear API reference (2026-09-29), Bannerbear V5 API (2026-09-29), What are the Bannerbear API keys (2026-09-29), Why am I seeing a 429 (2026-09-29), Bannerbear pricing (2026-09-29)

Acts as the person, not as itself

Each user connects their own account. Every call carries both identities — the agent and the person it is acting for — so the agent can never reach past what that individual can already do.

Credentials never touch the agent

Tokens live in the vault and attach server-side at call time. The agent holds a session, not a secret, and revoking access does not mean rotating a key.

Every call on the record

Who asked, which agent acted, which action ran, and the verdict that let it through — one audit trail across every integration, not one per vendor.

What an agent can do

Each action is granted on its own. An agent allowed to read is not thereby allowed to write, and the scope beside each row is what the acting user must have connected for it to run at all.

bannerbear_delete_animation_templates_by_uidWRITE

Delete an animation template. DELETE /animation_templates/{uid}. Soft-deletes the template. Animations already rendered from it stay intact, but the template no longer appears in list/get calls and can't be used for new renders. 204: Template deleted. 403: Template's api_write_access is owner_only and the caller's key is not owned by its creator. 423: Template's api_write_access is nobody — unlock via the dashboard.

animation_templates:write

bannerbear_delete_image_templates_by_uidWRITE

Delete an image template. DELETE /image_templates/{uid}. Soft-deletes the template. Existing renders that reference it stay intact, but the template will no longer appear in list/get calls and can no longer be used for new renders. 200: Template deleted. 403: Template's api_write_access is owner_only and the caller's API key is not owned by the template's creator. 423: Template's api_write_access is nobody — the owner must unlock it via the dashboard.

image_templates:write

bannerbear_delete_instant_urls_by_uidWRITE

Delete an instant URL. DELETE /instant_urls/{uid}. 200: Instant URL deleted. Plan-gated: Instant URLs are a Scale-plan feature (not on Automate); trial workspaces may hold three.

instant_urls:write

bannerbear_delete_webhooks_by_uidWRITE

Delete a webhook. DELETE /webhooks/{uid}. 200: Webhook deleted.

webhooks:write

bannerbear_delete_workflows_by_uidWRITE

Delete a workflow. DELETE /workflows/{uid}. Discards the workflow. Its past runs are kept. 204: Workflow discarded. 403: Workflow is restricted to updates from its owner's API keys. 423: Workflow is locked from API updates.

workflows:write

bannerbear_get_accountREAD

Get account info. GET /account. 200: Account details for the authenticated workspace and API key.

no provider scope

bannerbear_get_animation_templatesREAD

List animation templates. GET /animation_templates. 200: Paginated list of templates.

animation_templates:read

bannerbear_get_animation_templates_by_uidREAD

Get an animation template. GET /animation_templates/{uid}. 200: Template details.

animation_templates:read

bannerbear_get_animationsREAD

List animations. GET /animations. 200: Paginated list of animations.

animations:read

bannerbear_get_animations_by_uidREAD

Get an animation. GET /animations/{uid}. 200: Animation details + live progress.

animations:read

bannerbear_get_assetsREAD

List assets. GET /assets. 200: Paginated list of assets uploaded by this workspace.

assets:read

bannerbear_get_assets_by_uidREAD

Get an asset. GET /assets/{uid}. 200: Asset details.

assets:read

bannerbear_get_batchesREAD

List batches. GET /batches. 200: Paginated list of batches.

batches:read

bannerbear_get_batches_by_uidREAD

Get a batch. GET /batches/{uid}. 200: Batch details.

batches:read

bannerbear_get_image_templatesREAD

List image templates. GET /image_templates. 200: Paginated list of templates.

image_templates:read

bannerbear_get_image_templates_by_uidREAD

Get an image template. GET /image_templates/{uid}. 200: Template details.

image_templates:read

bannerbear_get_imagesREAD

List images. GET /images. 200: Paginated list of images.

images:read

bannerbear_get_images_by_uidREAD

Get an image. GET /images/{uid}. 200: Image details.

images:read

bannerbear_get_instant_urlsREAD

List instant URLs. GET /instant_urls. 200: Paginated list of instant URLs. Plan-gated: Instant URLs are a Scale-plan feature (not on Automate); trial workspaces may hold three.

instant_urls:read

bannerbear_get_instant_urls_by_uidREAD

Get an instant URL. GET /instant_urls/{uid}. 200: Instant URL details. Plan-gated: Instant URLs are a Scale-plan feature (not on Automate); trial workspaces may hold three.

instant_urls:read

bannerbear_get_publicationsREAD

Browse the public library. GET /publications. Returns publications with visibility=public_library from every team, which is the same set the dashboard's template library shows. Legacy V3 publications are included and their uid carries a v3_ prefix; they install as V5 image templates, converted on the way in. Publications are user-owned resources that span workspaces, so there's no workspace-scoped listing — if you need your own publication UIDs, grab them from the dashboard at publish time and hit /publications/{uid} or /publications/{uid}/install directly. 200: Paginated list of public library publications.

publications:read

bannerbear_get_publications_by_uidREAD

Get a publication. GET /publications/{uid}. Public library publications are visible to any authenticated caller, including legacy V3 ones, whose uid carries a v3_ prefix — a bare V3 uid resolves too. Published publications are only returned to the user who created them. 200: Publication details.

publications:read

bannerbear_get_tool_jobsREAD

List tool jobs. GET /tool_jobs. Newest first, 20 per page. Same polling shape /v5/images uses — Zapier / integration triggers can dedupe by uid and stop once they see a known one. 200: Paginated list of tool jobs (any tool_type, any status). outputs shape varies per-tool — see each tool's POST endpoint.

tools:read

bannerbear_get_tool_jobs_by_uidREAD

Get a tool job. GET /tool_jobs/{uid}. Poll the status and outputs of a tool run. The outputs object's shape depends on which tool created the job — refer to the tool's POST endpoint for the concrete keys. 200: Tool job details.

tools:read

bannerbear_get_webhooksREAD

List webhooks. GET /webhooks. 200: Paginated list of webhooks.

webhooks:read

bannerbear_get_webhooks_by_uidREAD

Get a webhook. GET /webhooks/{uid}. 200: Webhook details.

webhooks:read

bannerbear_get_workflow_runsREAD

List workflow runs. GET /workflow_runs. 200: Paginated list of runs, newest first.

workflows:read

bannerbear_get_workflow_runs_by_uidREAD

Get a workflow run. GET /workflow_runs/{uid}. 200: Run details, live progress, and per-step results.

workflows:read

bannerbear_get_workflowsREAD

List workflows. GET /workflows. 200: Paginated list of workflows.

workflows:read

bannerbear_get_workflows_by_uidREAD

Get a workflow. GET /workflows/{uid}. Returns the workflow's definition — the inputs it accepts and the steps it runs, in order. Call this before POST /workflow_runs to learn what to send. 200: Workflow definition.

workflows:read

bannerbear_patch_animation_templates_by_uidWRITE

Update an animation template. PATCH /animation_templates/{uid}. Update metadata, or replace the whole canvas by sending config. Layers and keyframes both live in config, so a partial config replaces everything in it — read the template first and send back the full object with your changes applied. 200: Updated template. 403: Template's api_write_access is owner_only and the caller's key is not owned by its creator. 423: Template's api_write_access is nobody — unlock via the dashboard.

animation_templates:write

bannerbear_patch_image_templates_by_uidWRITE

Update an image template. PATCH /image_templates/{uid}. Update any subset of template attributes. Passing config fully replaces the template's canvas configuration. 200: Updated template. 403: Template's api_write_access is owner_only and the caller's API key is not owned by the template's creator. 423: Template's api_write_access is nobody — the owner must unlock it via the dashboard.

image_templates:write

bannerbear_patch_instant_urls_by_uidWRITE

Update an instant URL. PATCH /instant_urls/{uid}. 200: Updated instant URL. Plan-gated: Instant URLs are a Scale-plan feature (not on Automate); trial workspaces may hold three.

instant_urls:write

bannerbear_patch_webhooks_by_uidWRITE

Update a webhook. PATCH /webhooks/{uid}. 200: Updated webhook.

webhooks:write

bannerbear_patch_workflows_by_uidWRITE

Update a workflow. PATCH /workflows/{uid}. Change metadata, inputs or steps. Each of inputs and steps is replaced wholesale when present and left alone when omitted, so renaming a workflow does not disturb its definition. Read the workflow first and send back the full array with your changes applied. 200: Updated workflow. 403: Workflow's api_write_access is owner_only and the caller's key is not owned by its creator. 423: Workflow is locked from API updates.

workflows:write

bannerbear_post_animation_templatesWRITE

Create an animation template. POST /animation_templates. Create an animation template. Send config to author layers and keyframes directly — see the Keyframes schema for the frame shape — or omit it and build the template in the dashboard editor. duration_seconds is derived from the keyframes rather than set. 201: Template created. Trial workspaces are capped at three animation templates.

animation_templates:write

bannerbear_post_animation_templates_by_uid_animateWRITE

Animate a template with a preset. POST /animation_templates/{uid}/animate. Applies a named preset to layers, optionally staggered. Deterministic and free: no model call, no AI credits, and the same request always produces the same keyframes — three layers at stagger: 500 begin at 0, 500 and 1000ms exactly. Use this whenever the request already says what it wants. The template is versioned before it is overwritten. 200: Template with its new keyframes. 403: Template's api_write_access is owner_only and the caller's key is not owned by its creator. 423: Template's api_write_access is nobody — unlock via the dashboard.

animation_templates:write

bannerbear_post_animationsWRITE

Create an animation. POST /animations. Render an animation from a template. Async — returns 202 with a queued animation; poll GET /animations/{uid} until status is completed or failed. Duration comes from the template's keyframes, so a template with no animation is rejected. Passing modifications.template.transparent: true renders on a transparent background and forces a MOV output, since MP4 carries no alpha channel. 202: Animation queued. 402: API quota exhausted.

animations:write

bannerbear_post_assets_checkWRITE

Batch-check which asset hashes already exist. POST /assets/check. Given a list of SHA-256 content hashes, returns a map of each hash to its existing asset record (or null if not stored in this workspace). Lets syncing clients skip the upload round-trip for content that's already been uploaded — compute the hash locally, batch-check, then only POST the missing ones to /assets. Max 100 hashes per request. 200: Map of hash → asset record or null. Keys are the hashes from the request; values are the existing asset for that hash, or null if not found.

assets:read

bannerbear_post_batchesWRITE

Create a batch. POST /batches. 202: Batch creation accepted.

batches:write

bannerbear_post_image_templatesWRITE

Create an image template. POST /image_templates. Create a new image template in the workspace. Pass config to seed the canvas with layers; omit it to start from an empty template that can be edited later. 201: Template created. Trial workspaces are capped at three image templates.

image_templates:write

bannerbear_post_imagesWRITE

Create an image. POST /images. Create an image render. Async on api.bannerbear.com (returns 202 + pending record, poll via GET /images/{uid} or subscribe via webhook). Sync on sync.api.bannerbear.com (returns 200 + completed image inline, or 408 if the render exceeds the sync timeout). 200: Sync render complete (sync host only). 202: Async render accepted (async host only). 402: API quota exhausted — upgrade required. 403: API key does not have access to this template. 408: Sync render timed out (sync host only). Pass sync: true to render on the synchronous host instead (200 with the finished image, or 408 after 10 seconds).

images:write

bannerbear_post_instant_urlsWRITE

Create an instant URL. POST /instant_urls. 201: Instant URL created. The signing_key field is only returned here — store it now. 402: Trial cap hit — upgrade required. Plan-gated: Instant URLs are a Scale-plan feature (not on Automate); trial workspaces may hold three.

instant_urls:write

bannerbear_post_publications_by_uid_installWRITE

Install a publication into the workspace. POST /publications/{uid}/install. Clones the publication's snapshot into the API key's team. What it creates depends on the publication's template_kind — an image template, an animation template, or a workflow and the templates its steps use. A legacy V3 publication (uid prefixed v3_) is converted into a V5 image template on the way in. Returns the newly created resource. Trial accounts are capped at 3 templates per kind — installing beyond the cap returns 402. 201: Installed. The response shape matches the resource that was created, so it follows the publication's template_kind. 402: Trial cap hit — upgrade required. 403: Publication is unpublished and cannot be installed. Trial workspaces are capped at three templates per kind.

publications:write

bannerbear_post_tools_add_audioWRITE

Add or replace audio. POST /tools/add_audio. Mix an audio track over a video, or replace the original. Async — returns 202 with a pending job; poll GET /tool_jobs/{uid} until status is completed or failed. 202: Tool run accepted. 402: API quota exhausted — upgrade required.

tools:write

bannerbear_post_tools_add_cover_artWRITE

Add cover art to video. POST /tools/add_cover_art. Embed a still image as the video's poster thumbnail (no re-encode). Async — returns 202 with a pending job; poll GET /tool_jobs/{uid} until status is completed or failed. 202: Tool run accepted. 402: API quota exhausted — upgrade required.

tools:write

bannerbear_post_tools_apply_color_filterWRITE

Apply colour filter. POST /tools/apply_color_filter. Apply a named colour-grade preset to a video (Instagram-style filters). Async — returns 202 with a pending job; poll GET /tool_jobs/{uid} until status is completed or failed. 202: Tool run accepted. 402: API quota exhausted — upgrade required.

tools:write

bannerbear_post_tools_concat_videosWRITE

Join videos. POST /tools/concat_videos. Join two or more videos end-to-end into a single file. Async — returns 202 with a pending job; poll GET /tool_jobs/{uid} until status is completed or failed. 202: Tool run accepted. 402: API quota exhausted — upgrade required.

tools:write

bannerbear_post_tools_create_gif_previewWRITE

Create GIF preview. POST /tools/create_gif_preview. Turn a video into an animated GIF preview. Async — returns 202 with a pending job; poll GET /tool_jobs/{uid} until status is completed or failed. 202: Tool run accepted. 402: API quota exhausted — upgrade required.

tools:write

bannerbear_post_tools_create_pdfWRITE

Create multi-page PDF. POST /tools/create_pdf. Stitch multiple JPGs, PNGs, and PDFs into a single multi-page document. Async — returns 202 with a pending job; poll GET /tool_jobs/{uid} until status is completed or failed. 202: Tool run accepted. 402: API quota exhausted — upgrade required.

tools:write

bannerbear_post_tools_create_video_slideshowWRITE

Create video slideshow. POST /tools/create_video_slideshow. Turn a series of images into an mp4 slideshow with optional transitions. Async — returns 202 with a pending job; poll GET /tool_jobs/{uid} until status is completed or failed. 202: Tool run accepted. 402: API quota exhausted — upgrade required.

tools:write

bannerbear_post_tools_crop_videoWRITE

Crop video. POST /tools/crop_video. Crop a video to an explicit rectangle in pixels. Async — returns 202 with a pending job; poll GET /tool_jobs/{uid} until status is completed or failed. 202: Tool run accepted. 402: API quota exhausted — upgrade required.

tools:write

bannerbear_post_tools_generate_ai_imageWRITE

Generate AI image. POST /tools/generate_ai_image. Generate an image from a text prompt using your choice of AI model. Async — returns 202 with a pending job; poll GET /tool_jobs/{uid} until status is completed or failed. 202: Tool run accepted. 402: API quota exhausted — upgrade required.

tools:write

bannerbear_post_tools_generate_voiceoverWRITE

Generate voiceover. POST /tools/generate_voiceover. Turn text into spoken audio using a natural-sounding TTS voice. Async — returns 202 with a pending job; poll GET /tool_jobs/{uid} until status is completed or failed. 202: Tool run accepted. 402: API quota exhausted — upgrade required.

tools:write

bannerbear_post_tools_overlay_imageWRITE

Add image overlay. POST /tools/overlay_image. Burn a logo, watermark, or badge onto a video. Async — returns 202 with a pending job; poll GET /tool_jobs/{uid} until status is completed or failed. 202: Tool run accepted. 402: API quota exhausted — upgrade required.

tools:write

bannerbear_post_tools_overlay_videoWRITE

Overlay video. POST /tools/overlay_video. Layer one video on top of another as picture-in-picture. Async — returns 202 with a pending job; poll GET /tool_jobs/{uid} until status is completed or failed. 202: Tool run accepted. 402: API quota exhausted — upgrade required.

tools:write

bannerbear_post_tools_remove_bgWRITE

Remove background. POST /tools/remove_bg. Cut the subject out of an image against a transparent background. Async — returns 202 with a pending job; poll GET /tool_jobs/{uid} until status is completed or failed. 202: Tool run accepted. 402: API quota exhausted — upgrade required.

tools:write

bannerbear_post_tools_resize_videoWRITE

Resize video. POST /tools/resize_video. Rescale a video to target dimensions, cover-crop or contain-letterbox. Async — returns 202 with a pending job; poll GET /tool_jobs/{uid} until status is completed or failed. 202: Tool run accepted. 402: API quota exhausted — upgrade required.

tools:write

bannerbear_post_tools_soften_videoWRITE

Soften video. POST /tools/soften_video. Smooth skin and flat surfaces while keeping edges sharp. Async — returns 202 with a pending job; poll GET /tool_jobs/{uid} until status is completed or failed. 202: Tool run accepted. 402: API quota exhausted — upgrade required.

tools:write

bannerbear_post_tools_subtitle_videoWRITE

Transcribe and burn subtitles. POST /tools/subtitle_video. Auto-transcribe the audio and burn styled subtitles onto the video. Async — returns 202 with a pending job; poll GET /tool_jobs/{uid} until status is completed or failed. 202: Tool run accepted. 402: API quota exhausted — upgrade required.

tools:write

bannerbear_post_tools_trim_videoWRITE

Trim video. POST /tools/trim_video. Keep a slice of a video by start and end time. Async — returns 202 with a pending job; poll GET /tool_jobs/{uid} until status is completed or failed. 202: Tool run accepted. 402: API quota exhausted — upgrade required.

tools:write

bannerbear_post_webhooksWRITE

Create a webhook. POST /webhooks. 201: Webhook created. The signing_key field is only returned here — store it now. Bannerbear calls the URL when the webhook is created and refuses it with 422 ('Url responded with HTTP 405') unless the URL answers that request with a success status.

webhooks:write

bannerbear_post_workflow_runsWRITE

Run a workflow. POST /workflow_runs. Start a workflow. Async — returns 202 immediately; poll GET /workflow_runs/{uid} until status is completed or failed. Steps run in order, each feeding the next. A run charges nothing itself: each step is billed as the resource it creates, so a run costs exactly what running its steps individually would. To process many rows, POST once per row — each is its own run. 202: Run queued. 403: Workflow restricted to runs from its owner's API keys. 423: Workflow is locked from API runs.

workflows:write

bannerbear_post_workflowsWRITE

Create a workflow. POST /workflows. Create a workflow with its inputs and steps in one call. Every step's ref is validated against its adapter — an unknown tool slug or a template UID outside this workspace is rejected — and a step may only reference steps before it. 201: Workflow created. Trial workspaces are capped at three workflows.

workflows:write

Often connected alongside

Put Bannerbear behind one governed endpoint.

Same permissions, same audit trail, whatever else you connect next.

Start free See pricing