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