2026-11-13 · 5 min read
How to caption videos in PHP with an API
A lot of video tooling lives in PHP: WordPress media flows, Laravel queues, legacy upload pipelines that have run for years. Captioning usually means shelling out to ffmpeg and shipping font files in the deploy. caption.sh turns that into a handful of cURL calls from the PHP you already run.
Submit and poll
<?php
$api = "https://api.caption.sh/v1";
$key = "YOUR_API_KEY";
function http(string $method, string $url, string $key, ?array $body = null): array {
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HEADER => true,
CURLOPT_FOLLOWLOCATION => false, // /result answers 302; keep the Location
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $key",
"Content-Type: application/json",
],
]);
if ($body !== null) {
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
}
$raw = curl_exec($ch);
$size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
curl_close($ch);
return [substr($raw, 0, $size), json_decode(substr($raw, $size), true)];
}
[$h, $job] = http("POST", "$api/videos", $key, [
"source_url" => "https://your-cdn.example/clip.mp4",
"options" => [
"font" => "inter",
"position" => "bottom",
"max_words" => 3,
"highlight" => true,
"highlight_color" => "#22D3EE",
],
]);
$jobId = $job["job_id"];
// poll until done or error
$status = "";
for ($i = 0; $i < 120; $i++) {
[, $job] = http("GET", "$api/jobs/$jobId", $key);
$status = $job["status"];
if ($status === "done" || $status === "error") break;
sleep(5);
}
if ($status !== "done") {
throw new RuntimeException("job did not finish: $status");
}
[$headers] = http("GET", "$api/jobs/$jobId/result", $key);
preg_match("/^Location:\s*(\S+)/mi", $headers, $m);
echo "download: {$m[1]}\n";The options array 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 PHP
- Statuses run queued, awaiting_upload, running, then done or error. The bounded for loop with sleep works for a script; in a queue worker, release the job back with a delay instead of sleeping.
- Keep CURLOPT_FOLLOWLOCATION off for the /result call so the 302 Location header is readable 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.