Videos API

Generate a video from a still, and publish a video as a Pinterest pin.

Two jobs, two tools. Publishing a video you already rendered never involves the generator; generating one never involves Pinterest until you publish it.

Publish a video you already have

POST /v1/pins/video

Field	Required	Notes
`video_url`	yes	Public https URL of an MP4. Pincast downloads it and sends the file itself
`cover_image_url`	yes	Public https URL of the cover still
`account_id`	no	The organization's connected account when absent
`board_id`	no	The account's first board when absent
`title`	no	Up to 100 characters
`description`	no	Up to 800 characters
`alt_text`	no	Up to 500 characters
`link`	no	Destination URL
`publish_at`	no	ISO 8601. In the future, the pin is scheduled
`product_sku`	no	Ties the pin to a product, for the product page and the reports

Pinterest refuses a video pin without a cover, so cover_image_url is not optional. Use the video's own first frame: anything else shows a picture the video never contains.

The URL you pass is never published. Pincast fetches the file, uploads it to Pinterest and creates the pin from the media id Pinterest returns, so a link that expires the next day - the usual behaviour of a generator's CDN - costs nothing once the pin exists.

The file must be an MP4, at most 80 MB when Pincast sends it for you.

Attach the file of a video already on Pinterest

POST /v1/pins/:pinterest_pin_id/video

Field	Required	Notes
`pinterest_pin_id`	yes	The video pin as Pinterest numbers it, in the path
`video_url`	yes	Public https URL of the same video, as an MP4

For a video published by hand, outside Pincast. Pinterest's API returns a video pin's cover, never its file, so Pincast cannot add that video to the catalogue feed on its own. Publishing it again to get the file in would put the same video on Pinterest twice and split its statistics; this attaches the file to the pin that already exists, and publishes nothing.

The file is copied to the shop's server straight away. The next nightly build of the Pinterest catalogue feed gives the pin's product a video_link, and where a product has several videos, the one whose pin earned most when promoted is chosen.

The pin must be a video pin already known to Pincast: pins are read from Pinterest every night, so one published today may only be found tomorrow.

Generate a video from a still

POST /v1/videos
GET  /v1/videos

Field	Required	Notes
`image_url`	yes	The still the video starts from. It becomes the first frame
`prompt`	yes	The movement, never the product
`tail_image_url`	no	The last frame, for a transition between two stills
`model`	no	`standard` (default) or `pro`
`duration`	no	`5` (default) or `10` seconds
`product_sku`	no	Ties the run to a product

Image to video, never text to video: the product comes from a photograph, so it keeps its shape. Asked from a sentence, a garment changes between two frames and the ad shows something the shop does not sell. Describing the product in the prompt has the same effect - the model then has two of them.

The call returns as soon as the run is queued:

{ "run_id": "k17abc...", "request_id": "01a0d903-...", "status": "queued" }

A run takes two to five minutes. Read it back with GET /v1/videos, which answers queued, running, done or failed, with video_url once it lands. That URL is what POST /v1/pins/video takes.

The whole chain

# 1. ask for the video
RUN=$(curl -s -X POST https://pincast.io/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url":"https://yourcdn.com/still.jpg","prompt":"Subtle motion only: she breathes, shoulders settle back. Camera locked."}')

# 2. wait, then read the file URL
curl -s -H "Authorization: Bearer YOUR_API_KEY" https://pincast.io/v1/videos

# 3. publish it, with the same still as the cover
curl -X POST https://pincast.io/v1/pins/video \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"video_url":"<video_url>","cover_image_url":"https://yourcdn.com/still.jpg","title":"Dos droit sans effort"}'