class RubyLLM::VideoJob

A VideoJob is an in-flight video generation. RubyLLM.animate_later returns one immediately; poll it with refresh and read the finished clip with video. RubyLLM.animate runs the same job through wait.

job = RubyLLM.animate_later("a paper boat sailing down a gutter")
job.wait
job.video.save("boat.mp4")

Attributes

duration [R]

The clip length in seconds the request asked for, or nil when it left the length to the provider’s default.

error [R]

The provider’s failure message when failed?, or nil.

id [R]

The provider’s id for the job.

model [R]

The id of the model rendering the video.

raw [R]

The provider’s raw response from the last submit or poll.

resolution [R]

The resolution the request asked for, as the provider spells it, such as "720p" or "1280x720", or nil when it left the resolution to the provider’s default.

status [R]

The job state: :pending, :completed, or :failed.

Public Class Methods

animate_later (prompt = nil, model: nil, provider: nil, assume_model_exists: false, context: nil, with: nil, extend: nil, provider_options: {}, metadata: nil, owner: nil)

Source

# File lib/ruby_llm/video_job.rb, line 49
def self.animate_later(prompt = nil,
                       model: nil,
                       provider: nil,
                       assume_model_exists: false,
                       context: nil,
                       with: nil,
                       extend: nil,
                       provider_options: {},
                       metadata: nil,
                       owner: nil)
  config = context&.config || RubyLLM.config
  model ||= config.default_video_model
  model, provider_instance = Models.resolve(model, provider: provider, assume_model_exists: assume_model_exists,
                                                   config: config)
  payload = {
    provider: provider_instance.slug,
    provider_class: provider_instance.name,
    model: model.id,
    model_info: model,
    prompt: prompt,
    provider_options: provider_options,
    metadata: metadata
  }

  RubyLLM.instrument('video_job.ruby_llm', payload, config: config) do |event|
    job = Accounting::Usage.owned_by(owner) do
      provider_instance.animate_later(prompt, model:, with:, extend:, provider_options:)
    end
    event[:job_id] = job.id
    job
  end
end

Submits a video generation job and returns a VideoJob without waiting for the result. Most code calls this through RubyLLM.animate_later. Takes the same arguments as Video.animate. The job records its usage, attributed to owner: or the owner of RubyLLM.with_usage_owner, once it finishes.

job = RubyLLM.animate_later("a hummingbird in slow motion")
job.id      # => "0eb6910f-a353-4699-9d1e-6a4f7a5b39e2"
job.done?   # => false

Public Instance Methods

completed? ()

Source

# File lib/ruby_llm/video_job.rb, line 108
def completed?
  status == :completed
end

Returns true when the job finished with a video.

cost ()

Source

# File lib/ruby_llm/video_job.rb, line 139
def cost
  Cost.new(tokens: Tokens.new(reported_cost: @reported_cost))
end

Returns the Cost the provider reported for the job. Its total is nil while the job is pending or when the provider reports no price.

job.wait
job.cost.total # => 0.05

done? ()

Source

# File lib/ruby_llm/video_job.rb, line 103
def done?
  !pending?
end

Returns true once the job finished, successfully or not.

failed? ()

Source

# File lib/ruby_llm/video_job.rb, line 114
def failed?
  status == :failed
end

Returns true when the job finished without a video. error carries the provider’s failure message.

pending? ()

Source

# File lib/ruby_llm/video_job.rb, line 98
def pending?
  status == :pending
end

Returns true while the provider is still rendering the video.

refresh ()

Source

# File lib/ruby_llm/video_job.rb, line 120
def refresh
  return self if done?

  state = @protocol.refresh_video_job(self)
  @status = state.fetch(:status)
  @raw = state[:raw]
  @error = state[:error]
  @reported_cost = state[:reported_cost]
  record_usage
  self
end

Re-fetches the job from the provider, updating status, error, and raw. Does nothing once the job is done?. Returns self.

video ()

Source

# File lib/ruby_llm/video_job.rb, line 167
def video
  raise Error, "Video generation failed: #{error}" if failed?
  return unless completed?

  @video ||= @protocol.download_video(self).tap { |video| video.config = @protocol.config }
end

Returns the finished Video, downloading it from the provider when its API requires that. Returns nil while pending? and raises Error when failed?.

wait (timeout: nil, interval: nil)

Source

# File lib/ruby_llm/video_job.rb, line 147
def wait(timeout: nil, interval: nil)
  timeout ||= @protocol.config.video_generation_timeout
  interval ||= @protocol.config.video_generation_poll_interval
  deadline = monotonic_time + timeout

  until done?
    remaining = deadline - monotonic_time
    raise Error, "Video generation timed out after #{timeout} seconds" unless remaining.positive?

    sleep [interval, remaining].min
    refresh
  end
  raise Error, "Video generation failed: #{error}" if failed?

  self
end

Polls the job until it finishes, then returns self. Raises Error when the job fails or timeout elapses first. timeout and interval are seconds and default to the configured video_generation_timeout and video_generation_poll_interval.