2026-11-15 · 5 min read

How to caption videos in C# with an API

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

.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.

Back to all articles