bannerbear 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 850108dc51b0e1e90d1e7e6452ce69b65c972638e33d7f6b946f0f81ab4fe1cd
-  data.tar.gz: f4c1e8883281527d9c515a07d358a251629ec19fb06a2dab4506fb95cfd9576a
+  metadata.gz: daa1514b2c5a5dddbef5836f7d64e3863932f4204e95a9625e7577b49dc70cad
+  data.tar.gz: 7a33d8e33c07d6b39561e6fbf6b64defafbb7d593a777bd1524f7623528e861c
 SHA512:
-  metadata.gz: de72ce94b734dbcfc73ca872ce5b2ce9f41c23b6f5c1bf40e2cf78bf8e2938b81933ab20113c41b5e8ad0af2dc034ff251b696ef310219063ea066dfdbf759ba
-  data.tar.gz: 92bfc10f330f5d318084b8e446491678029de74807ef353e2d679279590e22487780e15f4b093fa0bf374c8601fc6e685faf8d9d96f9fa4266f088638080186f
+  metadata.gz: 20c731f7f32fab1d5afc6fc6f85134febaacd2a386b3e86c526a0c2134a099272f8d98560ca469129f3300286db7439ff8f374e8bd62d1217c985a23a770d06f
+  data.tar.gz: df3b49048aa06fb412a3715228ae2af463701267636d00cdf8a7ede033c0a77e6d1c3bd7229cfb84fe1aef3ed1d79123741e23240cedeaa4895b096ed2bd34e2

data/README.md

@@ -31,6 +31,9 @@ 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)
+- [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 +58,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 +122,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 +132,112 @@ bb.get_image("image uid")
 bb.list_images(page: 1)
 ```
 
+### 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` | `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` |
+| `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` |
+
+A few examples:
+
+```ruby
+bb.remove_bg(image_url: "https://example.com/product.png")
+
+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: [...] } }
@@ -132,7 +258,7 @@ hook = bb.create_webhook(
   resource:  "image",
   event:     "completed",
   status:    "active",
-  scope:     "all",
+  scope:     "all_templates",
   templates: []
 )
 
@@ -141,6 +267,16 @@ 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"`, or `"tool_job"` (`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:
 
 ```ruby
@@ -151,7 +287,7 @@ bb.update_webhook("webhook uid",
   resource: "image",
   event:    "completed",
   status:   "active",
-  scope:    "all"
+  scope:    "all_templates"
 )
 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,92 @@ module Bannerbear
         post_response "/images", payload.slice(:modifications, :formats, :scale, :dpi, :quality, :proxy, :metadata, :version).merge({:template => uid}), payload[:sync]
       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],
+        "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],
+        "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 = {})
@@ -183,6 +277,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.3.0"
 end

metadata

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