Tools

Cinematic Motion

Photo to video: turn a single listing photo into a short cinematic real estate video with a professional camera move (zoom, orbit, fly-through, crane up…). No second frame needed.

post/api/v1/tools/cinematic_motion

Request

  • Base URL: https://pixly.app
  • URL: https://pixly.app/api/v1/tools/cinematic_motion
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://pixly.app/oauth/authorize, token URL https://pixly.app/api/oauth/token, scopes: tools)

Headers

Idempotency-Keystring

Recommended. A retry with the same key and body returns the first run's result (header Idempotency-Replayed: true) instead of running and charging again. Kept 24 hours; failed runs release the key.

Request body

imageUrlstring

Public https URL of the source photo, or a data: URI. Either imageUrl or r2Path is required.

r2Pathstring

Storage path of a photo already in the user's Pixly library (from list_library, or returned by an upload ticket) — the alternative to imageUrl.

cameraMove'zoom' | 'fly-through' | 'orbit' | 'pan' | 'aerial' | 'pull-back' | 'crane-up' | 'tilt-up' | 'boom-down' | 'drone-orbit' | 'flyover' | 'pull-away' | 'handheld'

Camera-move preset

direction'left-to-right' | 'right-to-left'

The direction the camera travels, for the moves that have one (orbit, pan, drone-orbit). 'left-to-right' sends the camera rightward, 'right-to-left' leftward. Ignored by every other move; omit to use the move's own default.

format'original' | '9:16' | '16:9'

Video shape. original (default) keeps the photo's own shape; 9:16 or 16:9 crop the photo, centred, to that shape before it is animated.

Response

Finished inline — resultUrls present (photo tools)

jobIdstring required

Job id — pass to get_job to poll

type'image_staging' | 'video_pair' | 'video_tour' required

Job family

status'pending' | 'processing' | 'completed' | 'failed' required

Anything not completed/failed is still running

creditsChargednumber nullable required

Credits debited for this job

createdAtstring date-time required

Submission time

completedAtstring date-time

Present once finished

resultUrlsstring[]

Presigned download URLs (present when completed; valid 7 days)

resultPathsstring[]

Storage path of each result, in resultUrls order — pass one as r2Path (or beforeR2Path, a photos[] item…) to run another tool on this result

errorstring

Failure reason; the message says whether the credit came back immediately or is in 24h refund review

notestring

Hint for agents, e.g. poll again in a few seconds

Changes

No recorded changes to this operation across all 1 revision of this API.