2026-11-15 · 5 min read

How to caption videos in Java with an API

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

Java services run a lot of media pipelines: Spring upload handlers, batch transcoders, Kafka consumers that chew through video all day. Captioning has always meant dragging ffmpeg and font files into the JVM container. caption.sh turns that into a few calls on the built-in HttpClient.

Submit and poll

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class CaptionJob {
    public static void main(String[] args) throws Exception {
        String api = "https://api.caption.sh/v1";
        String key = "YOUR_API_KEY";
        HttpClient client = HttpClient.newBuilder()
            // NEVER redirects: /result answers 302; keep the Location header
            .followRedirects(HttpClient.Redirect.NEVER)
            .connectTimeout(Duration.ofSeconds(10))
            .build();

        String body = """
            {
              "source_url": "https://your-cdn.example/clip.mp4",
              "options": {
                "font": "inter",
                "position": "bottom",
                "max_words": 3,
                "highlight": true,
                "highlight_color": "#22D3EE"
              }
            }""";
        HttpResponse<String> res = client.send(
            HttpRequest.newBuilder(URI.create(api + "/videos"))
                .header("Authorization", "Bearer " + key)
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(body))
                .build(),
            HttpResponse.BodyHandlers.ofString());
        String jobId = res.body().replaceAll(".*\"job_id\":\"([^\"]+)\".*", "$1");

        // poll until done or error
        String status = "";
        for (int i = 0; i < 120; i++) {
            HttpResponse<String> job = client.send(
                HttpRequest.newBuilder(URI.create(api + "/jobs/" + jobId))
                    .header("Authorization", "Bearer " + key).GET().build(),
                HttpResponse.BodyHandlers.ofString());
            status = job.body().replaceAll(".*\"status\":\"([^\"]+)\".*", "$1");
            if (status.equals("done") || status.equals("error")) break;
            Thread.sleep(5000);
        }
        if (!status.equals("done")) throw new IllegalStateException(status);

        HttpResponse<String> result = client.send(
            HttpRequest.newBuilder(URI.create(api + "/jobs/" + jobId + "/result"))
                .header("Authorization", "Bearer " + key).GET().build(),
            HttpResponse.BodyHandlers.ofString());
        System.out.println("download: " + result.headers()
            .firstValue("Location").orElseThrow());
    }
}

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. The example uses regex for JSON fields to stay dependency-free; use Jackson or Gson in a real service.

Details that matter in Java

  • Statuses run queued, awaiting_upload, running, then done or error. A bounded loop with Thread.sleep suits a script; in a worker, requeue the message with a delay instead of holding the thread.
  • Build the HttpClient with Redirect.NEVER 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