Skip to Content
PropertyPixel Docs
API referenceListing videos

Edit a listing video

POST
/listing-videos/{id}/edits

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.

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

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
base_version?integer

The video's version you last read (the version field). The call is refused if the video changed since, so you never edit a stale copy. Omit to apply to the latest version.

Range1 <= value
ops*array<|||||||||||||||||||||||||||>

Edits applied in order, all or nothing, as one new version (undoable in the Studio). Clip ids (shot_id) and photo ids come from get_listing_video.

Items1 <= items <= 50
quote_id?string

The id of a quote the user confirmed. Omit it to get a quote first; nothing is spent without one.

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
auto_confirm?boolean

REST with a personal API key only. Skip the quote step and spend immediately. For trusted scripts; ignored for app (OAuth) connections, which always get a quote.

Response Body

Edit 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
credits_spent*integer

Credits this call spent.

Example Request
curl -X POST 'https://api.propertypixel.app/v1/listing-videos/497f6eca-6276-4993-bfeb-53cbbbba6f08/edits' \  -H 'Content-Type: application/json' \  -d '{  "ops": [    {      "type": "move_shot",      "shot_id": "string",      "to_index": 0    }  ]}'
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",  "credits_spent": 0}

Get a listing video GET

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.

Generate AI video POST

Turn a listing video's still-photo clips into AI video clips (generated camera motion), or make chosen AI clips again. Spends credits. 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. Defaults: with neither shot_ids nor regenerate_shot_ids, every still clip becomes AI video. Each clip uses its current camera move; change it first with edit_listing_video (set_shot_motion, motion pan_zoom, move …), which is free. Clips are made in the background (a few minutes). Poll get_listing_video, waiting poll_after_ms, until every clip is ready or failed, then call export_listing_video. Once a clip is AI video it stays AI video: a failed clip is refunded and stays an AI clip, so retry it with regenerate_shot_ids (charged again, since the refund returned its credits). 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.