Skip to Content
PropertyPixel Docs
API referenceListing videos

Generate AI video

POST
/listing-videos/{id}/ai-video

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.

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
shot_ids?array<>

Still clips to turn into AI video. Omit for every still clip.

Items1 <= items <= 60
regenerate_shot_ids?array<>

AI clips to make again (a remake each).

Items1 <= items <= 60
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

Generate AI 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/ai-video' \  -H 'Content-Type: application/json' \  -d '{}'
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}

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.

Export a listing video POST

Render the video's current version to MP4 in one or more formats. Free. Needs AI video first: a draft is refused (call generate_listing_video_ai). Default format: portrait_9x16. Rendering starts once every AI clip is ready and takes about a minute. Poll get_listing_video, waiting poll_after_ms, until the file's status is ready; its download_url is a signed MP4 link valid for about an hour. Exporting again replaces a file of an older version that is still rendering. Requires a connection with edit access.