Skip to Content
PropertyPixel Docs
API referenceListing videos

Get a listing video

GET
/listing-videos/{id}

One listing video: its version (pass it as base_version when editing), clips in order (id, photo, still or AI, camera move, length, caption, AI clip status), settings (template, transition, music, voiceover, cards), the project's photos and their versions, and rendered files with download_url once ready. Poll this while poll_after_ms is set: AI clips take a few minutes, files about a minute.

Works with view-only access.

Authorization

headerAuthorizationBearer <pp_live_…>

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

Path Parameters

id*string

The listing video's id, from create_listing_video or list_listing_videos.

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

Response Body

Get 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 GET 'https://api.propertypixel.app/v1/listing-videos/497f6eca-6276-4993-bfeb-53cbbbba6f08'
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"}

Create a listing video POST

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.

Edit a listing video POST

Change a listing video with one or more edit ops: reorder, add or remove clips, set clip length, camera move, photo version and captions, switch template, music, transition, voiceover, opening/end cards and listing details. Returns the updated video. Most ops are free. Ops that make AI clips cost credits (set_shot_motion with motion ai, convert_all_to_ai, regenerate_shot, and set_shot_version or a new move on an ai clip). For plain AI video generation prefer generate_listing_video_ai. A photo's first AI clip in a video costs 250 credits; any later new clip of the same photo (new camera move, new version, or a regenerate) costs 150. Clips that fail are refunded automatically. Rule: an AI clip can never go back to a still photo; set_shot_motion from ai to pan_zoom is refused. Spending works in two steps. If the request costs credits, the first call (without quote_id) returns a quote and changes nothing. Show the user the cost and wait for a yes, then call again with the same arguments plus quote_id. The quote lasts 10 minutes and only matches identical arguments. A request that costs nothing runs straight away. Requires a connection with edit access. Can spend credits. A request that costs nothing runs immediately. One that costs credits returns 409 `quote_required` with a quote when sent without `quote_id`, and spends nothing. Resend with `quote_id` to run it, or send `auto_confirm: true` to skip the quote.