bannerbear 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 850108dc51b0e1e90d1e7e6452ce69b65c972638e33d7f6b946f0f81ab4fe1cd
-  data.tar.gz: f4c1e8883281527d9c515a07d358a251629ec19fb06a2dab4506fb95cfd9576a
+  metadata.gz: 29845579050c36919da99fcffdf6ec4d5577dbe243fbf114812500636969b05d
+  data.tar.gz: e13320ddb5d91bb4f957cefa72eb4292035f07a0c11f804d6f2b8e5ead471189
 SHA512:
-  metadata.gz: de72ce94b734dbcfc73ca872ce5b2ce9f41c23b6f5c1bf40e2cf78bf8e2938b81933ab20113c41b5e8ad0af2dc034ff251b696ef310219063ea066dfdbf759ba
-  data.tar.gz: 92bfc10f330f5d318084b8e446491678029de74807ef353e2d679279590e22487780e15f4b093fa0bf374c8601fc6e685faf8d9d96f9fa4266f088638080186f
+  metadata.gz: 2977c792ce41055fb8248ff4941ab5cccbdc2265c9589004124381c66163ddbcc1ab7a5a49ac811cbee75bef91780483fad8843e09cb26d1c5e5f520c37feaf0
+  data.tar.gz: 829e80632d438b428f6f8ed18d3009e0593fa480f96056200623f8b578658117fc5f626dbe5786e8333faa7adeafbb600659cb03a6b1c19d2878a0f6247970e1

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    bannerbear (0.2.0)
+    bannerbear (0.4.0)
       httparty
 
 GEM

data/README.md

@@ -31,6 +31,13 @@ For the **legacy V2 API**, see [Usage](#usage) below — that section is unchang
 - [Account (V5)](#account-v5)
 - [Image Templates (V5)](#image-templates-v5)
 - [Images (V5)](#images-v5)
+- [Animation Templates (V5)](#animation-templates-v5)
+- [Animations (V5)](#animations-v5)
+- [Workflows (V5)](#workflows-v5)
+- [Workflow Runs (V5)](#workflow-runs-v5)
+- [Tools (V5)](#tools-v5)
+- [Assets (V5)](#assets-v5)
+- [Publications (V5)](#publications-v5)
 - [Batches (V5)](#batches-v5)
 - [Webhooks (V5)](#webhooks-v5)
 - [Instant URLs (V5)](#instant-urls-v5)
@@ -55,14 +62,38 @@ bb.account
 
 ### Image Templates (V5)
 
-V5 renames V2's `templates` resource to `image_templates`.
+V5 renames V2's `templates` resource to `image_templates`. Templates can be created, updated, and deleted through the API — `config` holds the full canvas.
 
 ```ruby
 bb.list_image_templates(page: 1)
 bb.get_image_template("template uid")
+
+bb.create_image_template(
+  name:        "My Template",
+  description: "Created from the API",
+  tags:        ["portrait"],
+  width:       1080,
+  height:      1080,
+  config:      { objects: [
+    { id: "bg",       type: "rectangle", left: 0, top: 0, width: 1080, height: 1080, "background-color" => "#0f172a" },
+    { id: "headline", type: "text",      left: 80, top: 400, width: 920, text: "Hello World!", "font-size" => 72, color: "#ffffff" }
+  ] }
+)
+
 bb.update_image_template("template uid", name: "New Name", description: "...", tags: ["portrait"])
+bb.delete_image_template("template uid")
 ```
 
+##### 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 (`hash`)
+
+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 **object** with two sub-keys:
@@ -95,7 +126,7 @@ bb.create_image("template uid", sync: true, modifications: { objects: [...] })
 - `scale`: scale multiplier, 1–4 (`integer`)
 - `dpi`: DPI metadata (`integer`)
 - `quality`: quality control (`integer`)
-- `proxy`: proxy server for asset fetching (`string`)
+- `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`)
 - `sync`: route to the sync host (`boolean`; Ruby-only, not sent to the API)
@@ -105,13 +136,214 @@ bb.get_image("image uid")
 bb.list_images(page: 1)
 ```
 
+### 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.
+
+```ruby
+bb.list_animation_templates(page: 1)
+bb.get_animation_template("template uid")
+
+bb.create_animation_template(
+  name:        "My Animation",
+  description: "Created from the API",
+  tags:        ["promo"],
+  width:       1080,
+  height:      1080,
+  frame_rate:  30
+)
+
+bb.update_animation_template("template uid", name: "New Name", frame_rate: 60)
+bb.delete_animation_template("template uid")
+```
+
+##### 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"`.
+
+```ruby
+animation = bb.create_animation("animation template uid",
+  modifications: {
+    template: { width: 1080, height: 1080, fps: 30 },
+    objects:  [
+      { name: "headline", text: "Hello World!" }
+    ]
+  },
+  formats: ["mp4"]
+)
+
+animation = bb.get_animation(animation["uid"])
+animation["status"]        # => "queued" | "rendering" | "completed" | "failed"
+animation["files"]         # => { "mp4" => "https://..." } when completed
+
+bb.list_animations(page: 1)
+```
+
+##### Options for `create_animation`
+
+- `modifications`: V5 modifications object (`hash`)
+- `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.
+
+```ruby
+bb.list_workflows(page: 1)
+
+workflow = bb.get_workflow("workflow uid")
+workflow["inputs"]   # the inputs this workflow declares
+workflow["steps"]
+```
+
+### 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"`.
+
+```ruby
+run = bb.create_workflow_run("workflow uid",
+  inputs: { "headline" => "Hello World!", "photo" => "https://example.com/photo.jpg" }
+)
+
+run = bb.get_workflow_run(run["uid"])
+run["status"]     # => "queued" | "running" | "completed" | "failed"
+run["outputs"] if run["status"] == "completed"
+
+bb.list_workflow_runs(page: 1)
+```
+
+##### Options for `create_workflow_run`
+
+- `inputs`: values for the workflow's declared inputs (`hash`)
+
+### 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"`.
+
+```ruby
+job = bb.trim_video(video_url: "https://example.com/clip.mp4", start: 2.5, end: 10.0)
+
+job = bb.get_tool_job(job["uid"])
+job["status"]             # => "pending" | "running" | "completed" | "failed"
+job["outputs"]["video_url"] if job["status"] == "completed"
+
+bb.list_tool_jobs(page: 1)
+```
+
+Every tool also accepts an optional `metadata` string.
+
+| Method | Required | Optional | Output key |
+| --- | --- | --- | --- |
+| `remove_bg` | `image_url` | — | `image_url` |
+| `create_pdf` | `urls` | — | `pdf_url` |
+| `trim_video` | `video_url`, `start`, `end` | — | `video_url` |
+| `concat_videos` | `video_urls` | `width`, `height`, `fps` | `video_url` |
+| `resize_video` | `video_url`, `width`, `height` | `fit` | `video_url` |
+| `crop_video` | `video_url`, `x`, `y`, `width`, `height` | — | `video_url` |
+| `overlay_video` | `base_video_url`, `overlay_video_url` | `position`, `margin`, `x`, `y`, `scale`, `start` | `video_url` |
+| `overlay_image` | `video_url`, `image_url` | `position`, `margin`, `x`, `y`, `opacity` | `video_url` |
+| `subtitle_video` | `video_url` | `language`, `font`, `font_size`, `color`, `bold`, `italic`, `outline_color`, `outline_width`, `shadow_size`, `shadow_color`, `background_style`, `background_color`, `alignment` | `video_url` |
+| `generate_voiceover` | `text`, `voice` | — | `audio_url` |
+| `add_audio` | `video_url`, `audio_url`, `mode` | `volume`, `loop`, `ducking` | `video_url` |
+| `add_cover_art` | `video_url`, `image_url` | — | `video_url` |
+| `create_video_slideshow` | `image_urls` | `slide_duration`, `transition`, `transition_duration`, `width`, `height` | `video_url` |
+| `apply_color_filter` | `video_url`, `filter` | — | `video_url` |
+| `soften_video` | `video_url`, `strength` | — | `video_url` |
+
+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:
+
+```ruby
+bb.remove_bg(image_url: "https://example.com/product.png")
+
+# Corner placement, 40px in from each edge
+bb.overlay_image(
+  video_url: "https://example.com/clip.mp4",
+  image_url: "https://example.com/logo.png",
+  position:  "bottom_right",
+  margin:    40,
+  opacity:   0.8
+)
+
+bb.subtitle_video(
+  video_url:        "https://example.com/talk.mp4",
+  font:             "montserrat",
+  font_size:        32,
+  color:            "#ffffff",
+  background_style: "outline",
+  alignment:        "2"
+)
+
+bb.generate_voiceover(text: "Welcome to Bannerbear.", voice: "rachel")
+
+bb.create_video_slideshow(
+  image_urls:     ["https://example.com/1.jpg", "https://example.com/2.jpg"],
+  slide_duration: 3,
+  transition:     "fade",
+  width:          1280,
+  height:         720
+)
+```
+
+`create_tool_job` calls any tool by name — the escape hatch for tools added after this release:
+
+```ruby
+bb.create_tool_job("remove_bg", image_url: "https://example.com/product.png")
+```
+
+### 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.
+
+```ruby
+asset = bb.upload_asset(File.binread("logo.png"), "image/png")
+asset["url"]
+
+bb.get_asset("asset uid")
+bb.list_assets(page: 1)
+```
+
+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 `nil`), so a syncing client can skip the upload round-trip for content it already pushed. Max 100 hashes per call.
+
+```ruby
+digest = OpenSSL::Digest::SHA256.hexdigest(File.binread("logo.png"))
+found  = bb.check_assets([digest])
+bb.upload_asset(File.binread("logo.png"), "image/png") if found[digest].nil?
+```
+
+### Publications (V5)
+
+Publications are templates published to the public library. Installing one clones it into your workspace as a new image template.
+
+```ruby
+bb.list_publications(page: 1)
+bb.get_publication("publication uid")
+
+template = bb.install_publication("publication uid")
+template["uid"]
+```
+
 ### Batches (V5)
 
 Generate multiple images in one request (up to 100).
 
 ```ruby
 bb.create_batch(
-  type:  "image",
+  type:  "images",
   items: [
     { template: "template uid 1", modifications: { objects: [...] } },
     { template: "template uid 2", modifications: { objects: [...] } }
@@ -127,13 +359,11 @@ Webhooks are managed as a first-class resource in V5 (instead of being a per-req
 
 ```ruby
 hook = bb.create_webhook(
-  name:      "my-webhook",
-  url:       "https://example.com/hook",
-  resource:  "image",
-  event:     "completed",
-  status:    "active",
-  scope:     "all",
-  templates: []
+  name:     "my-webhook",
+  url:      "https://example.com/hook",
+  resource: "image",
+  event:    "completed",
+  status:   "active"
 )
 
 # IMPORTANT: signing_key is ONLY returned in the create response. Store it now —
@@ -141,6 +371,14 @@ hook = bb.create_webhook(
 puts hook["signing_key"]
 ```
 
+##### 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:
 
 ```ruby
@@ -150,8 +388,7 @@ bb.update_webhook("webhook uid",
   url:      "https://example.com/hook",
   resource: "image",
   event:    "completed",
-  status:   "active",
-  scope:    "all"
+  status:   "active"
 )
 bb.delete_webhook("webhook uid")
 bb.list_webhooks(page: 1)

data/lib/bannerbear/v5/client.rb

@@ -21,8 +21,16 @@ module Bannerbear
         get_response "/image_templates/#{uid}"
       end
 
+      def create_image_template(payload = {})
+        post_response "/image_templates", payload.slice(:name, :description, :tags, :width, :height, :config)
+      end
+
       def update_image_template(uid, payload = {})
-        patch_response "/image_templates/#{uid}", payload.slice(:name, :description, :tags)
+        patch_response "/image_templates/#{uid}", payload.slice(:name, :description, :tags, :width, :height, :config)
+      end
+
+      def delete_image_template(uid)
+        delete_response "/image_templates/#{uid}"
       end
 
       # Images
@@ -39,6 +47,162 @@ module Bannerbear
         post_response "/images", payload.slice(:modifications, :formats, :scale, :dpi, :quality, :proxy, :metadata, :version).merge({:template => uid}), payload[:sync]
       end
 
+      # Animation Templates
+
+      def list_animation_templates(params = {})
+        get_response "/animation_templates?#{URI.encode_www_form(params.slice(:page))}"
+      end
+
+      def get_animation_template(uid)
+        get_response "/animation_templates/#{uid}"
+      end
+
+      def create_animation_template(payload = {})
+        post_response "/animation_templates", payload.slice(:name, :description, :tags, :width, :height, :frame_rate)
+      end
+
+      def update_animation_template(uid, payload = {})
+        patch_response "/animation_templates/#{uid}", payload.slice(:name, :description, :tags, :width, :height, :frame_rate)
+      end
+
+      def delete_animation_template(uid)
+        delete_response "/animation_templates/#{uid}"
+      end
+
+      # Animations
+      #
+      # Rendering is always asynchronous — there is no synchronous host for
+      # animations. Poll get_animation until the status is "completed" or
+      # "failed", or subscribe to a webhook with the resource "animation".
+
+      def list_animations(params = {})
+        get_response "/animations?#{URI.encode_www_form(params.slice(:page))}"
+      end
+
+      def get_animation(uid)
+        get_response "/animations/#{uid}"
+      end
+
+      def create_animation(uid, payload = {})
+        post_response "/animations", payload.slice(:modifications, :formats, :metadata).merge({:template => uid})
+      end
+
+      # Workflows
+
+      def list_workflows(params = {})
+        get_response "/workflows?#{URI.encode_www_form(params.slice(:page))}"
+      end
+
+      def get_workflow(uid)
+        get_response "/workflows/#{uid}"
+      end
+
+      # Workflow Runs
+      #
+      # 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".
+
+      def list_workflow_runs(params = {})
+        get_response "/workflow_runs?#{URI.encode_www_form(params.slice(:page))}"
+      end
+
+      def get_workflow_run(uid)
+        get_response "/workflow_runs/#{uid}"
+      end
+
+      def create_workflow_run(uid, payload = {})
+        post_response "/workflow_runs", payload.slice(:inputs).merge({:workflow => uid})
+      end
+
+      # Tools
+      #
+      # Every tool is asynchronous: the POST 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".
+
+      TOOL_PARAMS = {
+        "remove_bg"              => [:image_url],
+        "create_pdf"             => [:urls],
+        "trim_video"             => [:video_url, :start, :end],
+        "concat_videos"          => [:video_urls, :width, :height, :fps],
+        "resize_video"           => [:video_url, :width, :height, :fit],
+        "crop_video"             => [:video_url, :x, :y, :width, :height],
+        # Place the overlay with either :position (+ optional :margin) or :x/:y,
+        # not both.
+        "overlay_video"          => [:base_video_url, :overlay_video_url, :x, :y, :position, :margin, :scale, :start],
+        "overlay_image"          => [:video_url, :image_url, :x, :y, :position, :margin, :opacity],
+        "subtitle_video"         => [:video_url, :language, :font, :font_size, :color, :bold, :italic,
+                                     :outline_color, :outline_width, :shadow_size, :shadow_color,
+                                     :background_style, :background_color, :alignment],
+        "generate_voiceover"     => [:text, :voice],
+        "add_audio"              => [:video_url, :audio_url, :mode, :volume, :loop, :ducking],
+        "add_cover_art"          => [:video_url, :image_url],
+        "create_video_slideshow" => [:image_urls, :slide_duration, :transition, :transition_duration, :width, :height],
+        "apply_color_filter"     => [:video_url, :filter],
+        "soften_video"           => [:video_url, :strength]
+      }.freeze
+
+      def create_tool_job(tool, payload = {})
+        allowed = TOOL_PARAMS[tool.to_s]
+        raise ArgumentError, "unknown tool: #{tool.inspect}" if allowed.nil?
+        post_response "/tools/#{tool}", payload.slice(*allowed, :metadata)
+      end
+
+      # Defines one method per tool, e.g. remove_bg(payload) or trim_video(payload).
+      TOOL_PARAMS.each_key do |tool|
+        define_method(tool) { |payload = {}| create_tool_job(tool, payload) }
+      end
+
+      # Tool Jobs
+
+      def list_tool_jobs(params = {})
+        get_response "/tool_jobs?#{URI.encode_www_form(params.slice(:page))}"
+      end
+
+      def get_tool_job(uid)
+        get_response "/tool_jobs/#{uid}"
+      end
+
+      # Assets
+
+      def list_assets(params = {})
+        get_response "/assets?#{URI.encode_www_form(params.slice(:page))}"
+      end
+
+      def get_asset(uid)
+        get_response "/assets/#{uid}"
+      end
+
+      # Uploads raw file bytes (max 5MB). content_type must be the mime type of
+      # the data, e.g. "image/png" or "video/mp4". Uploads are deduplicated per
+      # workspace by SHA-256, so re-uploading the same bytes returns the
+      # existing asset instead of creating a duplicate.
+      def upload_asset(data, content_type)
+        upload_response "/assets", data, content_type
+      end
+
+      # Returns a map of SHA-256 content hash => asset (or nil when the hash is
+      # not stored in this workspace). Max 100 hashes per call.
+      def check_assets(content_hashes)
+        post_response "/assets/check", { :content_hashes => content_hashes }
+      end
+
+      # Publications
+
+      def list_publications(params = {})
+        get_response "/publications?#{URI.encode_www_form(params.slice(:page))}"
+      end
+
+      def get_publication(uid)
+        get_response "/publications/#{uid}"
+      end
+
+      # Clones a publication into the workspace as a new image template.
+      def install_publication(uid)
+        post_response "/publications/#{uid}/install", {}
+      end
+
       # Batches
 
       def list_batches(params = {})
@@ -64,11 +228,11 @@ module Bannerbear
       end
 
       def create_webhook(payload = {})
-        post_response "/webhooks", payload.slice(:name, :url, :resource, :event, :status, :scope, :templates)
+        post_response "/webhooks", payload.slice(:name, :url, :resource, :event, :status)
       end
 
       def update_webhook(uid, payload = {})
-        patch_response "/webhooks/#{uid}", payload.slice(:name, :url, :resource, :event, :status, :scope, :templates)
+        patch_response "/webhooks/#{uid}", payload.slice(:name, :url, :resource, :event, :status)
       end
 
       def delete_webhook(uid)
@@ -183,6 +347,20 @@ module Bannerbear
         return body
       end
 
+      def upload_response(url, data, content_type)
+        response = HTTParty.post("#{BB_API_ENDPOINT}#{url}",
+          body: data,
+          timeout: 30,
+          headers: {
+            'Authorization' => "Bearer #{@api_key}",
+            'Content-Type' => content_type
+          }
+        )
+        body = JSON.parse(response.body)
+        return {"error" => body['message'], "code" => response.code} if response.code >= 400
+        return body
+      end
+
       def delete_response(url)
         response = HTTParty.delete("#{BB_API_ENDPOINT}#{url}",
           timeout: 5,

data/lib/bannerbear/version.rb

@@ -1,3 +1,3 @@
 module Bannerbear
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bannerbear
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Jon Yongfook
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-13 00:00:00.000000000 Z
+date: 2026-08-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty