Class: RubyLLM::Video

Inherits:
Object
  • Object
show all
Includes:
Support::Inspectable
Defined in:
lib/ruby_llm/video.rb

Overview

A Video is a generated clip. Save it with #save or read the raw bytes with #to_blob. Both handle hosted URLs and inline data.

video = RubyLLM.animate("a paper boat sailing down a rainy gutter")
video.save("boat.mp4")

Constant Summary

Constants included from Support::Inspectable

Support::Inspectable::TRUNCATE_AT

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Support::Inspectable

#full_inspect, #inspect, #pretty_print

Constructor Details

#initialize(url: nil, data: nil, mime_type: nil, model: nil, duration: nil, raw: nil) ⇒ Video

:nodoc:



96
97
98
99
100
101
102
103
 
# File 'lib/ruby_llm/video.rb', line 96

def initialize(url: nil, data: nil, mime_type: nil, model: nil, duration: nil, raw: nil) # :nodoc:
  @url = url
  @data = data
  @mime_type = mime_type
  @model = model
  @duration = duration
  @raw = raw
end

Instance Attribute Details

#config ⇒ Object

:nodoc:



92
93
94
 
# File 'lib/ruby_llm/video.rb', line 92

def config # :nodoc:
  @config || RubyLLM.config
end

#data ⇒ Object (readonly)

The raw video bytes, returned inline or downloaded with the provider's credentials, or nil when the video is hosted at #url.



18
19
20
 
# File 'lib/ruby_llm/video.rb', line 18

def data
  @data
end

#duration ⇒ Object (readonly)

The clip length in seconds, when the provider reports one.



27
28
29
 
# File 'lib/ruby_llm/video.rb', line 27

def duration
  @duration
end

#mime_type ⇒ Object (readonly)

The MIME type of the video, such as "video/mp4".



21
22
23
 
# File 'lib/ruby_llm/video.rb', line 21

def mime_type
  @mime_type
end

#model ⇒ Object (readonly)

The id of the model that generated the video.



24
25
26
 
# File 'lib/ruby_llm/video.rb', line 24

def model
  @model
end

#raw ⇒ Object (readonly)

The provider's raw job response, for provider-specific fields such as reported cost.



31
32
33
 
# File 'lib/ruby_llm/video.rb', line 31

def raw
  @raw
end

#url ⇒ Object (readonly)

The URL of the hosted video, for providers that return one, or nil.



14
15
16
 
# File 'lib/ruby_llm/video.rb', line 14

def url
  @url
end

Class Method Details

.animate(prompt = nil, model: nil, provider: nil, assume_model_exists: false, context: nil, with: nil, extend: nil, provider_options: {}, metadata: nil) ⇒ Object

Generates a video from prompt, blocks until the provider finishes rendering it, and returns a Video. Most code calls this through RubyLLM.animate. Video generation is asynchronous on every provider, so this submits a job with VideoJob.animate_later and polls until it is done, honoring config.video_generation_timeout and config.video_generation_poll_interval.

model: selects the video model and defaults to the configured default_video_model. provider: forces a specific provider, and assume_model_exists: skips the registry lookup. with: passes a reference image or a video to edit on models that support it. Models driven by image and audio input can omit the prompt and pass both attachments through with:. extend: continues a source video instead. It accepts a Video, file path, URL, or Attachment and cannot be combined with with:. provider_options: takes options in the provider's request vocabulary, such as durations and resolutions, and merges them into the request as-is. context: supplies a Context whose configuration replaces the global one. metadata: is included in the instrumentation payload.

video = RubyLLM.animate("a hummingbird in slow motion", model: "veo-3.1-fast-generate-preview")

RubyLLM.animate(
"Make the waterfall crash down",
model: "grok-imagine-video-1.5",
with: "waterfall.png",
provider_options: { duration: 5 }
)


63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/ruby_llm/video.rb', line 63

def self.animate(prompt = nil,
                 model: nil,
                 provider: nil,
                 assume_model_exists: false,
                 context: nil,
                 with: nil,
                 extend: nil,
                 provider_options: {},
                 metadata: nil)
  config = context&.config || RubyLLM.config
  payload = { model:, prompt:, provider_options:, metadata: }

  RubyLLM.instrument('video.ruby_llm', payload, config: config) do |event|
    job = VideoJob.animate_later(prompt, model:, provider:, assume_model_exists:,
                                         context:, with:, extend:, provider_options:, metadata:)
    event[:model] = job.model
    event[:job_id] = job.id
    job.wait
    result = job.video
    event[:result] = result
    event[:response_model] = result.model
    result
  end
end

Instance Method Details

#save(path) ⇒ Object

Writes the binary video to path, expanding it first. Returns path as given.

video.save("clip.mp4")


119
120
121
122
 
# File 'lib/ruby_llm/video.rb', line 119

def save(path)
  File.binwrite(File.expand_path(path), to_blob)
  path
end

#to_blob ⇒ Object

Returns the raw binary video bytes, downloading from #url when the provider returned a hosted video.

video_bytes = video.to_blob


110
111
112
 
# File 'lib/ruby_llm/video.rb', line 110

def to_blob
  data || Transport::Connection.basic(config).get(url).body
end