2026-11-13 · 5 min read

How to add captions to Facebook Reels with an API

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

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.

Back to all articles