2026-11-15 · 5 min read

How to add captions to Pinterest videos with an API

A film strip of pin-board scenes, the middle frame showing the captioned word PINS in neon
This image was generated with AI.

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.

Back to all articles