2026-11-12 · 5 min read
How to caption videos in Go with an API
Go services tend to own the unglamorous parts of a video pipeline: transcode queues, upload handlers, webhook consumers. Adding captions usually means dragging ffmpeg and font files into a container that was clean until now. caption.sh turns that into two HTTP calls from the standard library.
Submit and poll
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"time"
)
const api = "https://api.caption.sh/v1"
const key = "YOUR_API_KEY"
func main() {
body, _ := json.Marshal(map[string]any{
"source_url": "https://your-cdn.example/clip.mp4",
"options": map[string]any{
"font": "inter",
"position": "bottom",
"max_words": 3,
"highlight": true,
"highlight_color": "#22D3EE",
},
})
req, _ := http.NewRequest("POST", api+"/videos", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+key)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
var job struct{ JobID string `json:"job_id"` }
json.NewDecoder(resp.Body).Decode(&job)
resp.Body.Close()
// poll until done or error
client := &http.Client{
// /result answers 302; keep the Location instead of following it
CheckRedirect: func(req *http.Request, via []*http.Request) error {
return http.ErrUseLastResponse
},
}
status := ""
for i := 0; i < 120; i++ {
r, _ := http.NewRequest("GET", api+"/jobs/"+job.JobID, nil)
r.Header.Set("Authorization", "Bearer "+key)
rr, err := client.Do(r)
if err != nil {
panic(err)
}
var st struct{ Status string `json:"status"` }
json.NewDecoder(rr.Body).Decode(&st)
rr.Body.Close()
status = st.Status
if status == "done" || status == "error" {
break
}
time.Sleep(5 * time.Second)
}
if status != "done" {
panic("job did not finish: " + status)
}
r, _ := http.NewRequest("GET", api+"/jobs/"+job.JobID+"/result", nil)
r.Header.Set("Authorization", "Bearer "+key)
rr, _ := client.Do(r)
fmt.Println("download:", rr.Header.Get("Location"))
rr.Body.Close()
}The options map 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 Go
- Statuses run queued, awaiting_upload, running, then done or error. A bounded for loop with time.Sleep is idiomatic enough here; in a worker, requeue the job instead of sleeping.
- Set CheckRedirect to http.ErrUseLastResponse 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 spawning 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.