2026-11-13 · 5 min read
How to add captions to Facebook Reels with an API
Facebook Reels and feed videos compete with every sound-off scroll on the platform. Facebook feed videos autoplay muted by default, so the opening seconds carry no audio at all: captions are how the message lands before anyone taps for sound. caption.sh generates them with an API call.
The caption.sh workflow
import requests, time
API = "https://api.caption.sh/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}
job = requests.post(
f"{API}/videos",
headers=HEADERS,
json={
"source_url": "https://your-cdn.example/reel.mp4",
"options": {
"position": "center",
"max_words": 3,
"max_lines": 2,
"caps": True,
"highlight": True,
"highlight_color": "#22D3EE",
"outline_width": 2,
},
},
).json()
job_id = job["job_id"]
for _ in range(120):
job = requests.get(f"{API}/jobs/{job_id}", headers=HEADERS).json()
if job["status"] in ("done", "error"):
break
time.sleep(5)
if job["status"] == "done":
r = requests.get(f"{API}/jobs/{job_id}/result", headers=HEADERS,
allow_redirects=False)
video_url = r.headers["Location"]Jobs run queued, awaiting_upload, running, then done or error; poll until a terminal status. The result endpoint answers 302, so read the Location header with redirects disabled. Results are stored for 24 hours, then deleted. A 429 means the transcription throughput ceiling is reached; wait and retry rather than submitting duplicates.
Fit for Facebook
- Reels are vertical; export your edit at 1080x1920 before captioning so text lands where you designed it.
- Center position with three words per line and a strong outline reads against busy vertical footage.
- Facebook also offers its own auto-captions on upload. Burned-in captions still earn their place in the feed, where autoplay is muted, and they survive downloads and re-uploads where platform captions do not travel.
- Keep key text out of the bottom UI zone where the caption, likes, and follow button sit.
Tradeoffs and cost
- Burned-in captions cannot be toggled, resized, or translated by viewers. Leave Facebook's own captions on for viewers who need adjustable text.
- Each job covers up to 10 minutes, well past any Reel.
- At $0.10 per minute prepaid, captioning a one-minute Reel costs $0.10.