API per la creazione di video

Genera video di annunci immobiliari a partire da foto. Aggiungi sottotitoli, musica, caratteristiche dell'immobile e branding personalizzato — tutto da una singola chiamata JSON sincrona.

Crea un video MP4 da un elenco di immagini con effetti di movimento, sottotitoli opzionali, musica di sottofondo, sovrapposizioni delle caratteristiche dell'immobile e schede finali. L'endpoint è sincrono: si blocca fino al rendering del video, poi restituisce HTTP 200 con la videoUrl finale.

Sincrono, con timeout lungo

L'endpoint si blocca fino a 10 minuti mentre il video viene renderizzato, poi restituisce l'URL riproducibile. Imposta il timeout del client HTTP ad almeno 11 minuti — i 30–60 secondi predefiniti della maggior parte delle librerie HTTP termineranno prima che Pedra risponda.

Se il rendering supera 10 minuti, l'endpoint restituisce 500 con {"error": "Video processing timeout after 10 minutes..."}. Il video potrebbe ancora completarsi in background — contatta il supporto con il corpo della richiesta se accade.

Parametri principali

Oggetto image

Ogni voce in images descrive un frame:

Opzioni filigrana

Tracce musicali

Branding

Esempio: video minimo

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"
  }'

Esempio: video di annuncio di produzione completo

Walkthrough di 7 frame con effetti misti (zoom-in / zoom-out / transition / static), filigrana personalizzata + foto dell'agente + colore del brand, musica, voiceover, sottotitoli per frame, overlay con caratteristiche dell'immobile e scheda finale. Corrisponde al pattern di payload reale usato dall'app stessa di Pedra.

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"
  }'

Risposta

{
  "message": "Video created successfully",
  "videoId": "<uuid>",
  "videoUrl": "https://pedraimages.s3.eu-west-3.amazonaws.com/<uuid>"
}

Crediti

Ogni frame costa 5 crediti — tranne i frame con effect: "static", che sono gratuiti. Un video da 5 immagini con tutti gli effetti zoom-in/zoom-out consuma 25 crediti. Vedi Prezzi.

Errori di validazione

HTTP 400 viene restituito per:

• Array images mancante o vuoto.
• Qualsiasi immagine senza imageUrl (l'errore indica l'indice problematico).
• effect non in [zoom-in, zoom-out, transition, static].
• effect: "transition" senza secondImageUrl.

Etichette delle caratteristiche disponibili

Quando usi propertyCharacteristics, le seguenti chiavi di etichetta vengono renderizzate con icone corrispondenti nell'overlay: Bedrooms, Bathrooms, Surface, Price, Location, Parking, Heating, Outdoor. Le etichette personalizzate sono accettate ma renderizzate senza icona.

Successivo

Vedi Errori e limiti per le modalità di errore dei job video e il comportamento dei timeout.