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 — imposta un timeout client generoso

L'endpoint si blocca mentre il video viene renderizzato, poi restituisce l'URL riproducibile. Il rendering può richiedere alcuni minuti, quindi imposta il timeout del client HTTP in modo generoso — i 30–60 secondi predefiniti della maggior parte delle librerie HTTP termineranno prima che Pedra risponda.

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 3 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://img.pedra.ai/<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.