Pinterest Video Pin API

How to publish a video Pin to Pinterest via API.

By André LugAugust 25, 2026

Quick answer

A video Pin uses the same POST /api/posts request as an image Pin — board_id still required, media pointed at the video file. Pinterest accepts MP4, MOV, or M4V encoded with H.264 or H.265, up to 2 GB, running 4 seconds to 15 minutes, one video per Pin. PostGate detects the type automatically and validates before upload.

A video Pin is created through the exact same endpoint as an image Pin — the difference is entirely in the media file and the constraints Pinterest enforces on it. This page covers those constraints specifically: format, duration, size, and how PostGate handles the upload before Pinterest ever sees it.

How does the request differ from an image Pin?

Nothing about post.options.pinterest changes for video — board_id is still required. Point media at the video instead of an image and PostGate detects the type automatically; there’s no separate “video Pin” flag to set.

Publish a video PinPostGate API

curl -X POST https://postgate.studio/api/posts \
  -H "Authorization: Bearer $POSTGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-video-pin-001" \
  -d '{
    "post": {
      "body": "Watch the full launch story.",
      "options": { "pinterest": { "board_id": "1099...", "title": "Launch story" } }
    },
    "profiles": ["pro_pinterest123"],
    "media": ["https://cdn.example.com/launch.mp4"]
  }'

What format and file size does Pinterest accept?

Pinterest accepts MP4, MOV, and M4V, encoded with H.264 or H.265, up to 2 GB. PostGate’s Pinterest adapter enforces the same 2 GB ceiling on ingest — a file over that limit fails validation before it ever reaches Pinterest, so the error surfaces immediately instead of after a slow upload.

How long can a video Pin run?

Pinterest requires a video Pin to run at least 4 seconds and allows up to 15 minutes. In practice, engagement drops off well before that ceiling — Pinterest’s own guidance points to 6–15 seconds as the sweet spot for a promotional or product clip, with longer video reserved for tutorials or recipes where a viewer expects to watch the whole thing.

Which aspect ratio works best?

2:3 (1000×1500) and 9:16 (1080×1920) are Pinterest’s best-performing video shapes, matching how most Pins are viewed — full-width on a phone feed. 1:1 (1080×1080) works but crops more aggressively in some placements. Pinterest doesn’t reject an unlisted ratio outright, but a Pin container that isn’t vertical loses screen real estate against ones that are.

How is the video processed?

PostGate ingests the file, probes its true duration and dimensions, and prepares the Pinterest rendition asynchronously. A scheduled Pin’s video is revalidated again at delivery time, so a file that changed or expired between scheduling and publish is caught before Pinterest ever sees a broken upload. One video per Pin — Pinterest has no video carousel through this API.

Frequently asked questions

What video formats does the Pinterest API accept?

Pinterest accepts MP4, MOV, and M4V, encoded with H.264 or H.265, up to 2 GB. PostGate's Pinterest adapter enforces the same 2 GB ceiling on ingest — a file over that limit fails validation before it ever reaches Pinterest, so the error surfaces immediately instead of after a slow upload.

How long can a Pinterest video Pin be?

A video Pin must run at least 4 seconds and can run up to 15 minutes. In practice, engagement drops off well before that ceiling — Pinterest's own guidance points to 6–15 seconds as the sweet spot for a promotional or product clip, with longer video reserved for tutorials or recipes where a viewer expects to watch the whole thing.

What aspect ratio should a Pinterest video Pin use?

2:3 (1000x1500) and 9:16 (1080x1920) are Pinterest's best-performing video shapes, matching how most Pins are viewed — full-width on a phone feed. 1:1 works but crops more aggressively in some placements. Pinterest does not reject an unlisted ratio outright, but a non-vertical Pin loses screen real estate against ones that are.

Do I need a special flag to create a video Pin instead of an image Pin?

No. Nothing about post.options.pinterest changes for video — board_id is still required. Point the media array at the video instead of an image and PostGate detects the type automatically. One video per Pin; Pinterest has no video carousel through this API.