pictify 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61ccf483d399d895aed8467dd41ba36464a70b237c370cd03eb4a14911602a17
-  data.tar.gz: 168e24019d0d4e03c56866316a1557e397ed3c643d570ba6a9a0df49ddd2f601
+  metadata.gz: 7f414dc090d1668bcca2f5b240dbfdd0b1b1c1463dfddfe332f40dd1acd0ad2a
+  data.tar.gz: 1404b77c7a5acc442a1345b62bcb4cafc7140799f748ae6ee277b3df992f4651
 SHA512:
-  metadata.gz: 128158b9198f1a6388efad4a18152d0d563d9865b1ac306da1a280e8ad4e89882191cf912eb9a59d3ce4e1485e838861146de50a28ee55b2a52258dc1feb2c6e
-  data.tar.gz: f50e95a9dbb6e177021d512696be627a986f40e7b519712e2b994f2a920da6dae30832ccd6b8274dbb159e91308503c2de6d21ac4f94fd29a34535bfeb027d64
+  metadata.gz: eacf2d2150cc55bb131fface0a92de28e04bab52df5873a8765508e96d79d6a08739e38cc1bf34b3a226c209e3c75afbc955a712863c15ded0b035185ae9434e
+  data.tar.gz: a82cc93aafbf0b99985550d2dc476e3a33d7a38faf848a4d09b82bffc546211b5dfcd87deeba8d00c46e2467679e741195dbcff4342e558ef91dc44d0ec7b883

data/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-08-03
+
+### Added
+
+- Video template surface (`/video/templates`):
+  - `list_video_templates` — `GET /video/templates`, unwraps `{ templates }`
+    into an array of `VideoTemplate`.
+  - `get_video_template_variables(template_id)` —
+    `GET /video/templates/:uid/variables`, returns `VideoTemplateVariables`.
+  - `render_video(template_id, variables:, format:, timeout:)` —
+    `POST /video/templates/:uid/render`, waits for the finished MP4/GIF and
+    returns `VideoRenderResult` (`url`, `duration_in_frames`, `format`).
+  - `generate_video_template(prompt:, width:, height:, duration_seconds:, brand_color:, timeout:)`
+    — `POST /video/templates/generate`, returns `GenerateVideoTemplateResult`
+    (`template`, `preview_url`).
+  - `create_video_template(name:, tsx:, width:, height:, fps:, duration_seconds:, timeout:)`
+    — `POST /video/templates` with `kind: "tsx"`, `status: "draft"` and
+    `durationInFrames = (duration_seconds * fps).round`. Invalid tsx fails the
+    server-side compile gate with a 422 `RenderError` carrying the compiler
+    errors and saves nothing (retries are safe).
+- Per-request timeout override in the HTTP layer: video renders run minutes,
+  so the video methods default to their own timeouts (render 300s,
+  generate/create 180s) without changing the global `timeout` default.
+  `TimeoutError#timeout` now reports the effective per-call timeout.
+
 ## [1.0.0] - 2026-06-08
 
 ### Changed (BREAKING)

data/README.md

@@ -223,6 +223,62 @@ template = client.create_template(
 puts template.uid
 ```
 
+## Video Templates
+
+Video templates render MP4s (or animated GIFs) server-side. Render requests
+wait for the finished file and can legitimately run minutes — the video methods
+use their own per-call timeouts (render 300s, generate/create 180s) instead of
+the global `timeout`, and every method accepts a `timeout:` override.
+
+```ruby
+# List video templates — GET /video/templates
+templates = client.list_video_templates
+templates.each { |t| puts "#{t.uid}: #{t.name} (#{t.kind}, #{t.duration_in_frames} frames)" }
+
+# What variables can I set? — GET /video/templates/:uid/variables
+vars = client.get_video_template_variables("video-template-uid")
+vars.variables.each { |v| puts "  - #{v.name} (#{v.type}, default: #{v.default_value})" }
+
+# Render to MP4 (or GIF) — POST /video/templates/:uid/render
+# Omitted variables render their defaults. Each render consumes one video credit.
+video = client.render_video(
+  "video-template-uid",
+  variables: { title: "Welcome, Maya!" },
+  format: :mp4  # :mp4 (default) or :gif — GIF is capped at 15fps / 720px wide
+)
+puts video.url
+puts video.duration_in_frames
+puts video.format
+
+# Generate a template from a prompt with AI — POST /video/templates/generate
+# Takes 30-60 seconds; metered as one render.
+result = client.generate_video_template(
+  prompt: "A 8s product launch teaser for a coffee brand, warm and bold",
+  width: 1080,
+  height: 1080,
+  duration_seconds: 8,
+  brand_color: "#ff0055"  # optional
+)
+puts result.template.uid
+puts result.preview_url
+
+# Upload a Remotion scene you wrote — POST /video/templates
+# The tsx must export a zod `schema` (flat fields with defaults — they become
+# the template's variables) and a default React component; imports limited to
+# remotion, react and zod. It passes a compile gate BEFORE anything is saved:
+# invalid tsx raises a 422 Pictify::RenderError carrying the compiler errors
+# (err.errors) and creates NOTHING — retrying is always safe.
+template = client.create_video_template(
+  name: "My Scene",
+  tsx: tsx_source,
+  width: 1080,
+  height: 1080,
+  fps: 30,
+  duration_seconds: 8  # durationInFrames is computed as (seconds * fps).round
+)
+puts template.uid
+```
+
 ## Error Handling
 
 ```ruby

data/lib/pictify/client.rb

@@ -25,6 +25,11 @@ module Pictify
     DEFAULT_TIMEOUT = 30
     DEFAULT_MAX_RETRIES = 3
 
+    # Video renders legitimately run minutes; these per-call defaults override
+    # the global +timeout+ for the video endpoints only.
+    DEFAULT_VIDEO_RENDER_TIMEOUT = 300
+    DEFAULT_VIDEO_TEMPLATE_TIMEOUT = 180
+
     # @param api_key [String] Your Pictify API key
     # @param base_url [String] Custom API base URL
     # @param timeout [Integer] Request timeout in seconds
@@ -288,24 +293,171 @@ module Pictify
       Template.new(response["template"] || {})
     end
 
+    # ------------------------------------------------------------------------
+    # Video templates
+    # ------------------------------------------------------------------------
+
+    # List your video templates.
+    #
+    # +GET /video/templates+ — unwraps the +{ templates }+ envelope.
+    #
+    # @return [Array<VideoTemplate>]
+    def list_video_templates
+      response = request(:get, "video/templates")
+      (response["templates"] || []).map { |t| VideoTemplate.new(t) }
+    end
+
+    # A video template's variable definitions — what you can set when
+    # rendering it. Call before {#render_video} to know what to pass.
+    #
+    # +GET /video/templates/:uid/variables+.
+    #
+    # @param template_id [String] The video template UID
+    # @return [VideoTemplateVariables]
+    def get_video_template_variables(template_id)
+      response = request(:get, "video/templates/#{encode(template_id)}/variables")
+      VideoTemplateVariables.new(response)
+    end
+
+    # Render a video template to MP4 — or an animated GIF — with variables.
+    #
+    # +POST /video/templates/:uid/render+ — the request WAITS for the finished
+    # file (up to a few minutes) and returns its hosted URL. Each render
+    # consumes one video credit. Omitted variables render their defaults;
+    # unknown variable names fail with a 422 {RenderError}.
+    #
+    # @example
+    #   video = client.render_video("abc123", variables: { title: "Welcome, Maya!" }, format: :gif)
+    #   puts video.url
+    #
+    # @param template_id [String] The video template UID (see {#list_video_templates})
+    # @param variables [Hash] Variables to inject; omitted variables render their defaults
+    # @param format [Symbol, String] Output format (default mp4). +gif+ is a
+    #   palette-optimised animated GIF capped at 15fps / 720px wide
+    # @param timeout [Integer, nil] Per-call timeout in seconds (default 300 —
+    #   video renders take minutes; the global +timeout+ is not used here)
+    # @return [VideoRenderResult]
+    def render_video(template_id, variables: {}, format: "mp4", timeout: nil)
+      response = request(:post, "video/templates/#{encode(template_id)}/render", {
+        variables: variables || {},
+        format: (format || :mp4).to_s
+      }, nil, timeout: timeout || DEFAULT_VIDEO_RENDER_TIMEOUT)
+      VideoRenderResult.new(response)
+    end
+
+    # Generate a new video template from a prompt using AI.
+    #
+    # +POST /video/templates/generate+ — the service designs a motion brief,
+    # writes the scene as code, compiles it, renders preview frames and reviews
+    # them visually — then saves a draft template whose texts, colors and
+    # optional image are editable variables. Takes 30-60 seconds; metered as
+    # one render.
+    #
+    # @param prompt [String] What the video is for, with any mood/style
+    #   guidance (max 2000 chars)
+    # @param width [Integer] Canvas width in pixels (default 1080)
+    # @param height [Integer] Canvas height in pixels (default 1080)
+    # @param duration_seconds [Numeric] Video length in seconds, 1-60 (default 8)
+    # @param brand_color [String, nil] Optional brand color (hex) to build the
+    #   palette around
+    # @param timeout [Integer, nil] Per-call timeout in seconds (default 180)
+    # @return [GenerateVideoTemplateResult]
+    def generate_video_template(prompt:, width: 1080, height: 1080, duration_seconds: 8,
+                                brand_color: nil, timeout: nil)
+      response = request(:post, "video/templates/generate", {
+        prompt: prompt,
+        width: width,
+        height: height,
+        durationSeconds: duration_seconds,
+        brandColor: brand_color
+      }, nil, timeout: timeout || DEFAULT_VIDEO_TEMPLATE_TIMEOUT)
+      GenerateVideoTemplateResult.new(response)
+    end
+
+    # Upload a Remotion scene you wrote as a new video template.
+    #
+    # +POST /video/templates+ — unwraps the +{ template }+ envelope. The SDK
+    # sends +kind: "tsx"+, +status: "draft"+ and computes
+    # +durationInFrames = (duration_seconds * fps).round+.
+    #
+    # The source passes a compile gate BEFORE anything is saved: invalid tsx
+    # rejects with a 422 {RenderError} carrying the compiler errors
+    # (+error.errors+) and creates NOTHING, so retrying cannot litter the
+    # account with broken templates.
+    #
+    # @param name [String] Template name shown in the dashboard
+    # @param tsx [String] The complete single-file Remotion scene source. Must
+    #   export a zod +schema+ (flat fields with defaults — they become the
+    #   template's variables) and a default React component; imports limited to
+    #   +remotion+, +react+ and +zod+
+    # @param width [Integer] Canvas width in pixels (default 1080)
+    # @param height [Integer] Canvas height in pixels (default 1080)
+    # @param fps [Integer] Frames per second (default 30)
+    # @param duration_seconds [Numeric] Video length in seconds (default 8)
+    # @param timeout [Integer, nil] Per-call timeout in seconds (default 180 —
+    #   the compile gate bundles the scene)
+    # @return [VideoTemplate]
+    def create_video_template(name:, tsx:, width: 1080, height: 1080, fps: 30,
+                              duration_seconds: 8, timeout: nil)
+      response = request(:post, "video/templates", {
+        name: name,
+        kind: "tsx",
+        tsx: tsx,
+        width: width,
+        height: height,
+        fps: fps,
+        durationInFrames: (duration_seconds * fps).round,
+        status: "draft"
+      }, nil, timeout: timeout || DEFAULT_VIDEO_TEMPLATE_TIMEOUT)
+      VideoTemplate.new(response["template"] || {})
+    end
+
+    # Runs between the retry middleware and the adapter. The net_http adapter
+    # wraps +Net::OpenTimeout+ as +Faraday::ConnectionFailed+, which would slip
+    # a timeout past a retry exception list that (deliberately) excludes
+    # timeouts — so timeout-flavored connection failures are re-raised as
+    # +Faraday::TimeoutError+ before the retry middleware sees them.
+    class TimeoutClassifier < Faraday::Middleware
+      TIMEOUT_HINTS = ["timeout", "timed out", "execution expired"].freeze
+
+      def call(env)
+        @app.call(env)
+      rescue Faraday::ConnectionFailed => e
+        raise Faraday::TimeoutError, e if e.cause.is_a?(Timeout::Error) ||
+                                          TIMEOUT_HINTS.any? { |hint| e.message.to_s.downcase.include?(hint) }
+
+        raise
+      end
+    end
+
     private
 
     def encode(value)
-      CGI.escape(value.to_s)
+      # escapeURIComponent, not escape: CGI.escape is form encoding (space
+      # becomes "+", which the server decodes as a literal plus in a path).
+      CGI.escapeURIComponent(value.to_s)
     end
 
     def connection
       @connection ||= Faraday.new(url: @base_url) do |f|
         f.request :retry,
                   max: @max_retries,
-                  interval: 0.05,
+                  interval: 1,
                   backoff_factor: 2,
                   retry_statuses: [500, 502, 503, 504],
-                  # Keep faraday-retry's defaults (which include RetriableResponse
-                  # — required for retry_statuses to engage) and add network
-                  # failures so 5xx and connection drops retry, but 4xx never do.
-                  exceptions: Faraday::Retry::Middleware::DEFAULT_EXCEPTIONS + [Faraday::ConnectionFailed],
+                  # An EXPLICIT exception list. faraday-retry's defaults include
+                  # Faraday::TimeoutError and Timeout::Error, and with POST
+                  # opted in a timing-out render was retried — but generation
+                  # endpoints are billed, non-idempotent POSTs and the server
+                  # keeps rendering (and meters) after the client aborts, so a
+                  # timed-out call could bill max_retries+1 credits. Timeouts
+                  # must surface immediately (TimeoutClassifier below keeps
+                  # them out of ConnectionFailed); genuine connection failures
+                  # stay retryable, and RetriableResponse keeps retry_statuses
+                  # engaged. 4xx never retry.
+                  exceptions: [Faraday::ConnectionFailed, Faraday::RetriableResponse],
                   methods: %i[get post put delete patch]
+        f.use TimeoutClassifier
         f.options.timeout = @timeout
         f.options.open_timeout = 10
         f.headers["Authorization"] = "Bearer #{@api_key}"
@@ -316,9 +468,14 @@ module Pictify
 
     # Make an authenticated JSON request. Nil body fields are stripped so the
     # backend applies its own defaults. HTTP errors are mapped to typed errors.
-    def request(method, path, body = nil, params = nil)
+    #
+    # +timeout+ overrides the global read timeout for this request only (video
+    # renders legitimately run minutes); the client-wide default is untouched.
+    def request(method, path, body = nil, params = nil, timeout: nil)
+      effective_timeout = timeout || @timeout
       response = connection.send(method) do |req|
         req.url(path, params)
+        req.options.timeout = timeout if timeout
         req.body = JSON.generate(strip_nils(body)) if body
       end
 
@@ -329,10 +486,10 @@ module Pictify
       env = e.response
       raise Pictify.error_from_response(env.status, error_body(env.body))
     rescue Faraday::TimeoutError
-      raise TimeoutError.new("Request timed out", timeout: @timeout)
+      raise TimeoutError.new("Request timed out", timeout: effective_timeout)
     rescue Faraday::ConnectionFailed => e
       if e.message.include?("timeout") || e.message.include?("timed out") || e.message.include?("execution expired")
-        raise TimeoutError.new("Request timed out", timeout: @timeout)
+        raise TimeoutError.new("Request timed out", timeout: effective_timeout)
       end
 
       raise NetworkError.new(nil, original_error: e)

data/lib/pictify/errors.rb

@@ -129,8 +129,9 @@ module Pictify
   #
   # The Pictify API has no unified error envelope: image/GIF endpoints return
   # +{ error, code }+ while template/CRUD endpoints return +{ message }+ or
-  # +{ message, errors }+. Message precedence is +error+ then +message+ then a
-  # fallback.
+  # +{ message, errors }+. Message precedence is +error+ then +message+ then
+  # the joined +errors+ strings (the video compile gate's 422 shape, where the
+  # strings are the fix instructions) then a fallback.
   #
   # Status mapping:
   #   - 401            -> AuthenticationError
@@ -142,7 +143,14 @@ module Pictify
   #   - 5xx            -> ServerError
   def self.error_from_response(status_code, body)
     body ||= {}
-    message = body["error"] || body["message"] || "An unexpected error occurred"
+    # The video compile gate returns 422 { errors: ["..."] } with no
+    # message/error key — those strings ARE the fix instructions, so they
+    # join into the message rather than leaving a generic fallback.
+    errors = body["errors"]
+    joined_errors = if errors.is_a?(Array) && !errors.empty? && errors.all? { |e| e.is_a?(String) }
+                      errors.join("; ")
+                    end
+    message = body["error"] || body["message"] || joined_errors || "An unexpected error occurred"
 
     case status_code
     when 401

data/lib/pictify/types.rb

@@ -12,6 +12,12 @@ module Pictify
   # GIF quality presets accepted by the +/gif+ endpoint.
   GIF_QUALITIES = %i[low medium high].freeze
 
+  # Video output formats supported by video template renders.
+  #
+  # +gif+ produces a palette-optimised animated GIF capped at 15fps / 720px
+  # wide — the same render, encoded for places an MP4 cannot autoplay.
+  VIDEO_FORMATS = %i[mp4 gif].freeze
+
   # Result of an +/image+ render (+render_html+ / +render_url+).
   #
   # Maps the API response +{ url, id, createdAt }+.
@@ -253,4 +259,91 @@ module Pictify
       @pagination = data["pagination"] ? Pagination.new(data["pagination"]) : nil
     end
   end
+
+  # A video template returned by +list_video_templates+ / +create_video_template+
+  # (and nested in +generate_video_template+ results).
+  #
+  # +kind+ is +"timeline"+ (studio-built) or +"tsx"+ (Remotion scene) — both
+  # render identically. The API keys video templates by +uid+ and declares
+  # variables in +variableDefinitions+. Unknown fields are kept in +raw+.
+  class VideoTemplate
+    attr_reader :uid, :name, :kind, :width, :height, :fps, :duration_in_frames,
+                :poster_url, :status, :variable_definitions, :created_at,
+                :updated_at, :raw
+
+    def initialize(data)
+      @raw = data
+      @uid = data["uid"]
+      @name = data["name"]
+      @kind = data["kind"]
+      @width = data["width"]
+      @height = data["height"]
+      @fps = data["fps"]
+      @duration_in_frames = data["durationInFrames"]
+      @poster_url = data["posterUrl"]
+      @status = data["status"]
+      @variable_definitions = (data["variableDefinitions"] || []).map do |v|
+        TemplateVariableDefinition.new(v)
+      end
+      @created_at = parse_time(data["createdAt"])
+      @updated_at = parse_time(data["updatedAt"])
+    end
+
+    private
+
+    def parse_time(value)
+      return nil unless value
+
+      Time.parse(value)
+    rescue ArgumentError, TypeError
+      nil
+    end
+  end
+
+  # A video template's variable definitions (+get_video_template_variables+) —
+  # what you can set when rendering it.
+  #
+  # Maps +{ templateUid, templateName, kind, variables: [...], referenced: [...] }+.
+  # +referenced+ lists every variable name the document actually references.
+  class VideoTemplateVariables
+    attr_reader :template_uid, :template_name, :kind, :variables, :referenced, :raw
+
+    def initialize(data)
+      @raw = data
+      @template_uid = data["templateUid"]
+      @template_name = data["templateName"]
+      @kind = data["kind"]
+      @variables = (data["variables"] || []).map { |v| TemplateVariableDefinition.new(v) }
+      @referenced = data["referenced"] || []
+    end
+  end
+
+  # Result of a video template render (+render_video+).
+  #
+  # Maps +{ url, durationInFrames, format }+. +format+ echoes what was actually
+  # produced ("mp4" or "gif").
+  class VideoRenderResult
+    attr_reader :url, :duration_in_frames, :format, :raw
+
+    def initialize(data)
+      @raw = data
+      @url = data["url"]
+      @duration_in_frames = data["durationInFrames"]
+      @format = data["format"]
+    end
+  end
+
+  # Result of AI video template generation (+generate_video_template+).
+  #
+  # Maps +{ template: {...}, previewUrl }+ — the saved draft {VideoTemplate}
+  # plus a rendered preview frame of the generated scene (may be +nil+).
+  class GenerateVideoTemplateResult
+    attr_reader :template, :preview_url, :raw
+
+    def initialize(data)
+      @raw = data
+      @template = VideoTemplate.new(data["template"] || {})
+      @preview_url = data["previewUrl"]
+    end
+  end
 end

data/lib/pictify/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pictify
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pictify
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Pictify
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-08 00:00:00.000000000 Z
+date: 2026-08-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday