bannerbear 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: daa1514b2c5a5dddbef5836f7d64e3863932f4204e95a9625e7577b49dc70cad
-  data.tar.gz: 7a33d8e33c07d6b39561e6fbf6b64defafbb7d593a777bd1524f7623528e861c
+  metadata.gz: 29845579050c36919da99fcffdf6ec4d5577dbe243fbf114812500636969b05d
+  data.tar.gz: e13320ddb5d91bb4f957cefa72eb4292035f07a0c11f804d6f2b8e5ead471189
 SHA512:
-  metadata.gz: 20c731f7f32fab1d5afc6fc6f85134febaacd2a386b3e86c526a0c2134a099272f8d98560ca469129f3300286db7439ff8f374e8bd62d1217c985a23a770d06f
-  data.tar.gz: df3b49048aa06fb412a3715228ae2af463701267636d00cdf8a7ede033c0a77e6d1c3bd7229cfb84fe1aef3ed1d79123741e23240cedeaa4895b096ed2bd34e2
+  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,10 @@ 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)
@@ -132,6 +136,97 @@ 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"`.
@@ -153,11 +248,11 @@ Every tool also accepts an optional `metadata` string.
 | `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` | `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`, `x`, `y` | `scale`, `start` | `video_url` |
-| `overlay_image` | `video_url`, `image_url`, `x`, `y` | `opacity` | `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` |
@@ -166,11 +261,22 @@ Every tool also accepts an optional `metadata` string.
 | `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",
@@ -253,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",
-  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 —
@@ -271,11 +375,9 @@ puts hook["signing_key"]
 
 - `name` *required* (`string`)
 - `url` *required* — the URL that receives the events (`string`)
-- `resource`: `"image"`, `"batch"`, or `"tool_job"` (`string`)
+- `resource`: `"image"`, `"batch"`, `"tool_job"`, `"animation"`, or `"workflow_run"` (`string`)
 - `event`: `"all_events"`, `"completed"`, or `"failed"` (`string`)
 - `status`: `"active"` or `"disabled"` (`string`)
-- `scope`: `"all_templates"` or `"specific_templates"` (`string`)
-- `templates`: template UIDs, used when `scope` is `"specific_templates"` (`array`)
 
 CRUD:
 
@@ -286,8 +388,7 @@ bb.update_webhook("webhook uid",
   url:      "https://example.com/hook",
   resource: "image",
   event:    "completed",
-  status:   "active",
-  scope:    "all_templates"
+  status:   "active"
 )
 bb.delete_webhook("webhook uid")
 bb.list_webhooks(page: 1)

data/lib/bannerbear/v5/client.rb

@@ -47,6 +47,74 @@ 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
@@ -57,11 +125,13 @@ module Bannerbear
         "remove_bg"              => [:image_url],
         "create_pdf"             => [:urls],
         "trim_video"             => [:video_url, :start, :end],
-        "concat_videos"          => [:video_urls, :width, :height],
+        "concat_videos"          => [:video_urls, :width, :height, :fps],
         "resize_video"           => [:video_url, :width, :height, :fit],
         "crop_video"             => [:video_url, :x, :y, :width, :height],
-        "overlay_video"          => [:base_video_url, :overlay_video_url, :x, :y, :scale, :start],
-        "overlay_image"          => [:video_url, :image_url, :x, :y, :opacity],
+        # 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],
@@ -158,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)

data/lib/bannerbear/version.rb

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

metadata

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