Video

Create video API

Generate listing videos from photos. Add subtitles, music, property characteristics, and custom branding — all from a single synchronous JSON call.

POST/api/create_video

Builds an MP4 video from a list of images with motion effects, optional subtitles, background music, property characteristic overlays, and ending cards. The endpoint is synchronous: it blocks until the video is rendered, then returns HTTP 200 with the final videoUrl.

Walkthrough video examples
Watch real listing videos generated from a handful of photos — vertical and horizontal.
See examples →

Synchronous — set a generous client timeout

The endpoint blocks while the video renders, then returns the playable URL. Rendering can take several minutes, so set your HTTP client timeout generously — the default of 30–60s on most HTTP libraries will hang up before Pedra responds.

Top-level parameters

apiKeystringrequired
Your API key.
imagesarrayrequired
Ordered list of image objects. Each becomes a frame/clip in the video. See "Image object" below.
isVerticalboolean
9:16 vertical format for Instagram Reels / TikTok. Default is 16:9 horizontal.
Default: false
propertyCharacteristicsarray
Array of {label, value} pairs (Bedrooms, Bathrooms, Surface, Price, etc). Only shown when an image has characteristics.enabled = true.
musicobject
Background music. Object: { enabled: boolean, track: string }.
voiceobject
Voiceover. Object: { enabled: boolean, audioUrl: string }.
brandingobject
Custom logo, agent photo, and brand color overlay. See "Branding" section.
endingTitlestring
Headline displayed on the final card.
endingSubtitlestring
Subtitle on the final card (typically a CTA or contact info).

Image object

Each entry in images describes one frame:

imageUrlstringrequired
URL of the photo (or base64 data URI).
effectstringrequired
Motion effect applied to this frame.
Values: zoom-in zoom-out static transition
secondImageUrlstring
Required when effect = "transition". The image to transition to.
subtitlestring
Caption shown over this frame.
titlestring
Large title overlay (e.g., "Living Room", "Kitchen").
watermarkobject
Watermark config: { enabled, position, opacity }. Enabled by default at bottom-right with opacity 1.0. Set { enabled: false } to disable.
characteristicsobject
Show the propertyCharacteristics overlay on this frame: { enabled: true }.

Watermark options

enabledboolean
Show the Pedra watermark.
Default: true
positionstring
Where the watermark appears.
Values: top-left top top-right left center right bottom-left bottom bottom-right
Default: bottom-right
opacitynumber
0.0 (invisible) to 1.0 (fully opaque).
Default: 1

Music tracks

enabledbooleanrequired
Turn background music on.
trackstringrequired
Music style.
Values: calm uplifting corporate piano

Branding

showWatermarkboolean
Show your custom logo as a watermark instead of Pedra's.
watermarkUrlstring
URL to your logo (PNG with transparency recommended).
showProfessionalPictureboolean
Display the agent's photo on the ending card.
professionalPictureUrlstring
URL to the agent's headshot.
primaryColorstring
Brand color used for overlays, as a hex string (e.g., "#007BFF").

Example: minimal video

curl -X POST https://app.pedra.ai/api/create_video \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "images": [
      { "imageUrl": "https://example.com/img1.jpg", "effect": "zoom-in" },
      { "imageUrl": "https://example.com/img2.jpg", "effect": "zoom-out" }
    ],
    "isVertical": false,
    "endingTitle": "Contact us!",
    "endingSubtitle": "Visit our website"
  }'

Example: full production listing video

3-frame walkthrough with mixed effects (zoom-in / zoom-out / transition / static), branded watermark + agent photo + brand color, music, voiceover, subtitles per frame, property characteristics overlay, and ending card. Matches the typical real-world payload pattern Pedra's own app uses.

curl -X POST https://app.pedra.ai/api/create_video \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "images": [
      {
        "imageUrl": "https://example.com/exterior.jpg",
        "effect": "zoom-in",
        "subtitle": "Renovated 2-bedroom in Barcelona",
        "watermark": {"enabled": true, "position": "bottom-right", "opacity": 0.75},
        "characteristics": {"enabled": true}
      },
      {
        "imageUrl": "https://example.com/living-room.jpg",
        "effect": "zoom-out",
        "subtitle": "Bright, open-plan living space",
        "watermark": {"enabled": true, "position": "bottom-right", "opacity": 0.75}
      },
      {
        "imageUrl": "https://example.com/before.jpg",
        "secondImageUrl": "https://example.com/after.jpg",
        "effect": "transition",
        "title": "Before & After"
      }
    ],
    "isVertical": false,
    "propertyCharacteristics": [
      {"label": "Price", "value": "€450,000"},
      {"label": "Bedrooms", "value": "2"},
      {"label": "Bathrooms", "value": "1"},
      {"label": "Surface", "value": "85 m²"}
    ],
    "music": {"enabled": true, "track": "uplifting"},
    "voice": {"enabled": true, "audioUrl": "https://example.com/voiceover.mp3"},
    "branding": {
      "showWatermark": true,
      "watermarkUrl": "https://example.com/agency-logo.png",
      "showProfessionalPicture": true,
      "professionalPictureUrl": "https://example.com/agent-photo.jpg",
      "primaryColor": "#000000"
    },
    "endingTitle": "Felix Ingla",
    "endingSubtitle": "felix@pedra.ai"
  }'

Response

JSON
{
  "message": "Video created successfully",
  "videoId": "<uuid>",
  "videoUrl": "https://img.pedra.ai/<uuid>"
}

Credits

Each frame costs 5 credits — except frames with effect: "static", which are free. A 5-image video with all zoom-in/zoom-out effects deducts 25 credits. See Pricing.

Validation errors

HTTP 400 is returned for:

  • Missing or empty images array.
  • Any image missing imageUrl (error names the offending index).
  • effect not in [zoom-in, zoom-out, transition, static].
  • effect: "transition" without secondImageUrl.

Available characteristic labels

When using propertyCharacteristics, the following label keys render with matching icons in the overlay: Bedrooms, Bathrooms, Surface, Price, Location, Parking, Heating, Outdoor. Custom labels are accepted but render without an icon.

Next

See Errors & limits for video job failure modes and timeout behavior.