Skip to Content
PropertyPixel Docs
API referenceListing videos

Create a listing video

POST
/listing-videos

Create a listing video from 2–30 of a project's photos in a template. Free and immediate: it returns a draft in which every clip is a still photo with a gentle camera move, ordered by room unless ordered is true.

Next: show the user the draft (get_listing_video has the clips), adjust it with edit_listing_video if they ask, then generate_listing_video_ai to turn the clips into AI video (spends credits). A draft can't be exported until it has AI video.

Requires a connection with edit access.

Authorization

headerAuthorizationBearer <pp_live_…>

An API key from Settings → Developers (pp_live_…), or an OAuth access token.

Header Parameters

Idempotency-Key?string

A unique key (for example a UUID) that makes retries safe. A retry with the same key and body returns the stored response; the same key with a different body returns 422. Keys last 24 hours.

Lengthlength <= 255

Request Body

application/json
  1. body
project_id*string

The project whose photos make the video.

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
photo_ids?array<>

The photos to use, 2–30. Get ids from get_project. Alternatively pass all_photos: true.

Items1 <= items <= 30
all_photos?boolean

Use every photo in the project (up to 30) instead of listing photo_ids.

versions?

Which version of each photo to show: photo_id → an edit's job_id, or "original". Photos not listed use their default: the picked (hearted) edit, else the newest finished edit, else the original.

template_id*string

The look: music, transitions, pacing and type. See list_listing_video_options for each template's description.

Value in"calm_luxury""fast_social""bright_modern""classic_tour""cinematic""warm_welcome""beat_drop""house_tour""golden_hour""slow_sunday""clean_cuts"
ordered?boolean

Keep photo_ids in the order given. Default false: clips are ordered by room (exterior first, then living spaces, kitchen, bedrooms, bathrooms…).

Defaultfalse
address?string

Address for the opening card. Default: the project's address.

Lengthlength <= 120
price?string

Listing price text, e.g. "$850,000".

Lengthlength <= 24
beds?number
Range0 <= value <= 50
baths?number
Range0 <= value <= 50
intro_card?boolean

Open with a card showing the listing details. Default: on when there is an address.

end_card?boolean

Close with a card showing the agent's saved details (name, brokerage, phone, logo). Default: on when the workspace has saved details.

music_track_id?|

Override the template's music (a track id from list_listing_video_options, or null for none).

Response Body

Create a listing video

application/json
  1. response
object*string
id*string
Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
project_id*string
Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
title*string
version*integer

The current revision. Pass it as base_version to edit tools so a stale edit is refused.

is_draft*boolean

True until AI video has been generated for at least one photo. Drafts can't be exported.

template_id*string
Value in"calm_luxury""fast_social""bright_modern""classic_tour""cinematic""warm_welcome""beat_drop""house_tour""golden_hour""slow_sunday""clean_cuts"
watermarked*boolean

Trial account: exported files carry a PropertyPixel watermark.

credits*
duration_sec*number

Sum of the clip lengths.

shots*array<>

The clips in play order.

settings*
photos*array<>

Every photo in the project that can be added (add_shot) and its versions (set_shot_version).

exports*array<>

Rendered files, newest first. Export with export_listing_video.

share_url*|null
studio_url*string

Open the video editor in the PropertyPixel Studio.

Formaturi
poll_after_ms*|

Clips, voiceover or files are still being made: call get_listing_video again after this long. Null when nothing is in progress.

created_at*string
updated_at*string
Example Request
curl -X POST 'https://api.propertypixel.app/v1/listing-videos' \  -H 'Content-Type: application/json' \  -d '{  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",  "template_id": "calm_luxury"}'
Example Response
{  "object": "listing_video",  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",  "title": "string",  "version": 0,  "is_draft": true,  "template_id": "calm_luxury",  "watermarked": true,  "credits": {    "per_photo": 0,    "per_remake": 0  },  "duration_sec": 0,  "shots": [    {      "id": "string",      "photo_id": "50c42bd2-615e-4fec-a325-0e5c4d3d73d3",      "source_job_id": "82ec7aa8-71eb-48cf-81de-c1b18e40e554",      "room_type": "string",      "motion": "pan_zoom",      "move": "push_in",      "duration_sec": 0,      "caption": "string",      "clip": {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "status": "pending",        "preview_url": "http://example.com"      }    }  ],  "settings": {    "transition": {      "preset": "string",      "duration_sec": 0    },    "opening": {      "preset": "string",      "duration_sec": 0    },    "closing": {      "preset": "string",      "duration_sec": 0    },    "beat": {      "cuts": true,      "pulse": true    },    "music": {      "track_id": "string",      "volume": 0    },    "voiceover": {      "enabled": true,      "script": "string",      "voice_id": "string",      "status": "pending"    },    "captions": true,    "intro": {      "address": "string",      "price": "string",      "beds": 0,      "baths": 0    },    "intro_card": true,    "end_card": true,    "disclosure": true,    "cards": {      "style": "string",      "brand_color": "string",      "font": "string"    }  },  "photos": [    {      "photo_id": "50c42bd2-615e-4fec-a325-0e5c4d3d73d3",      "label": "string",      "room_type": "string",      "paid": true,      "versions": [        {          "source_job_id": "82ec7aa8-71eb-48cf-81de-c1b18e40e554",          "label": "string",          "favourite": true        }      ]    }  ],  "exports": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "format": "portrait_9x16",      "status": "pending",      "progress": 0,      "edit_version": 0,      "current": true,      "download_url": "http://example.com",      "size_bytes": 0,      "duration_sec": 0,      "error": {        "code": "string",        "message": "string",        "retryable": true      },      "created_at": "string"    }  ],  "share_url": "http://example.com",  "studio_url": "http://example.com",  "poll_after_ms": 0,  "created_at": "string",  "updated_at": "string"}