2026-11-12 · 5 min read

How to caption videos in Go with an API

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

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.

Back to all articles