2026-11-14 · 5 min read
How to caption videos in Ruby with an API
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.