2026-11-15 · 5 min read
How to caption videos in C# with an API
.NET shops caption video the hard way today: an ffmpeg sidecar in the container, font files in the image, and a wrapper process to babysit. caption.sh replaces that with a few HttpClient calls, and System.Text.Json is all the JSON you need.
Submit and poll
using System.Text;
using System.Text.Json;
using System.Net.Http.Headers;
var api = "https://api.caption.sh/v1";
var key = "YOUR_API_KEY";
var handler = new HttpClientHandler {
// /result answers 302; keep the Location instead of following it
AllowAutoRedirect = false
};
using var client = new HttpClient(handler);
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", key);
var body = JsonSerializer.Serialize(new {
source_url = "https://your-cdn.example/clip.mp4",
options = new {
font = "inter",
position = "bottom",
max_words = 3,
highlight = true,
highlight_color = "#22D3EE"
}
});
var res = await client.PostAsync(api + "/videos",
new StringContent(body, Encoding.UTF8, "application/json"));
var jobId = JsonDocument.Parse(await res.Content.ReadAsStringAsync())
.RootElement.GetProperty("job_id").GetString();
// poll until done or error
string status = "";
for (var i = 0; i < 120; i++) {
var job = await client.GetStringAsync(api + "/jobs/" + jobId);
status = JsonDocument.Parse(job).RootElement
.GetProperty("status").GetString() ?? "";
if (status is "done" or "error") break;
await Task.Delay(5000);
}
if (status != "done") throw new Exception($"job did not finish: {status}");
var result = await client.GetAsync(api + "/jobs/" + jobId + "/result");
Console.WriteLine("download: " +
result.Headers.Location);The options object 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 .NET
- Statuses run queued, awaiting_upload, running, then done or error. The polling loop suits a console tool; in a hosted service, schedule the next check with a delayed queue message instead of Task.Delay inside a worker.
- Set AllowAutoRedirect = false so the 302 from /result surfaces its Location header instead of being followed. 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.