2026-11-15 · 5 min read
How to add captions to Pinterest videos with an API
Pinterest is a visual search engine, and most browsing there happens silently: people scroll idea pins and video pins in places where audio stays off. The message of a video pin has to work as text. caption.sh adds the captions with an API call instead of an editing session.
Why caption for Pinterest
- Video pins surface in a sound-off feed, so the hook has to be readable, not heard.
- How-to and recipe pins get saved and rewatched; on-screen steps make the pin useful on repeat viewings.
- Pinterest content has a long shelf life. Captions keep working for the months a pin keeps circulating.
- The same captioned file reposts cleanly to other vertical surfaces.
The 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/pin-video.mp4",
"options": {
"font": "inter",
"position": "center",
"max_words": 4,
"max_lines": 2,
"highlight": True,
"highlight_color": "#E11D48",
"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.
Fit for Pinterest
- Pinterest favors vertical 2:3 or 9:16; export at the final aspect ratio before captioning so text lands where you designed it.
- Center or lower-center placement reads well against recipe and DIY footage; keep text clear of the title zone Pinterest overlays.
- Pinterest's tone is instructional rather than frantic: max_words at 4 and a steady highlight fit better than hyper-kinetic styling.
Tradeoffs and cost
- Burned-in captions cannot be toggled, resized, or translated by viewers. Where the surface offers switchable captions, keep those enabled too.
- Each job covers up to 10 minutes, well past any video pin.
- A 429 means the transcription throughput ceiling is reached. Wait and retry rather than submitting duplicates.
- At $0.10 per minute prepaid, captioning a 30-second pin costs $0.05.