2026-11-14 · 5 min read

How to caption videos in Ruby with an API

A film strip of programming scenes, the middle frame showing the captioned word RUBY in neon
This image was generated with AI.

Ruby apps handle video constantly: Rails uploads, Sidekiq media jobs, script-based pipelines. Adding captions usually means vendoring ffmpeg and font configs into the deploy. caption.sh turns it into a few Net::HTTP calls from the standard library.

Submit and poll

require "net/http"
require "json"
require "uri"

API = "https://api.caption.sh/v1"
KEY = "YOUR_API_KEY"

def http(method, path, body = nil)
  uri = URI("#{API}#{path}")
  req = Net::HTTP.const_get(method.capitalize).new(uri)
  req["Authorization"] = "Bearer #{KEY}"
  req["Content-Type"] = "application/json"
  req.body = JSON.generate(body) if body
  Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |h|
    # /result answers 302; Net::HTTP does not follow it by default
    h.request(req)
  end
end

res = http(:post, "/videos", {
  source_url: "https://your-cdn.example/clip.mp4",
  options: {
    font: "inter",
    position: "bottom",
    max_words: 3,
    highlight: true,
    highlight_color: "#22D3EE",
  },
})
job_id = JSON.parse(res.body)["job_id"]

# poll until done or error
status = nil
120.times do
  status = JSON.parse(http(:get, "/jobs/#{job_id}").body)["status"]
  break if %w[done error].include?(status)
  sleep 5
end
raise "job did not finish: #{status}" unless status == "done"

res = http(:get, "/jobs/#{job_id}/result")
puts "download: #{res["Location"]}"

The options hash accepts the documented keys only: font, caps, size, max_words, max_lines, position, text_color, highlight, highlight_color, decoration, decoration_color, outline_width, backdrop_radius, backdrop_opacity, max_tilt, censor_captions, and censor_audio. Every key is optional; defaults produce the standard word-by-word style.

Details that matter in Ruby

  • Statuses run queued, awaiting_upload, running, then done or error. A bounded loop with sleep suits a script; in Sidekiq, re-enqueue with a delay instead of sleeping in the worker.
  • Net::HTTP does not follow the 302 from /result by default, so the Location header is right there in the response. Results are stored for 24 hours, then deleted, so download promptly.
  • A 429 means the transcription throughput ceiling is reached. Back off and retry the same job rather than submitting duplicates per retry.
  • One job accepts up to 10 minutes of video. Split longer footage first and total the per-minute cost across segments.

Cost and tradeoffs

Pricing is prepaid at $0.10 per minute, so cost is predictable before you run a batch. Burned-in captions cannot be toggled, resized, or translated by viewers, so keep platform-side captions available where accessibility matters.

Back to all articles