API video e voiceover

Genera video di annunci a partire da foto, modificali senza nuovo rendering, aggiungi voiceover con IA e sottotitoli sincronizzati e scegli la musica di sottofondo — tutto da chiamate JSON sincrone.

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

Voiceover

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": "cinematic"},
    "voice": {"enabled": true, "audioId": "AUDIO_ID_FROM_GENERATE_VOICE", "showSubtitles": true},
    "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.

Aggiornare un video esistente

Modifica un video già creato — tramite videoId — senza ri-renderizzare i clip invariati. Riordinare, cambiare musica o voiceover, modificare branding, schede finali, sottotitoli e titoli vengono riassemblati gratuitamente. Solo le foto nuove o modificate vengono ri-animate (e costano crediti). Come create_video, è sincrono e restituisce la nuova videoUrl. Se il video è stato creato con una propertyId, quel collegamento viene ereditato automaticamente — non serve rinviarlo.

Semantica di aggiornamento parziale

Tutti i campi tranne videoId sono opzionali. Ometti images per mantenere la timeline esistente e cambiare solo audio/testo/branding (un riassemblaggio gratuito). Ometti music, voice, branding o il testo finale per lasciare ciascuno al valore memorizzato — modificare la musica non cancella mai il voiceover, e viceversa. Quando invii images, un clip la cui foto + effetto (+ seconda foto per le transizioni) corrisponde a uno esistente viene riutilizzato così com'è.

Parametri principali

Esempio: cambiare solo la musica

curl -X POST https://app.pedra.ai/api/update_video \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "videoId": "VIDEO_ID_FROM_CREATE",
    "music": { "enabled": true, "track": "upbeat" }
  }'

Esempio: riordinare + sostituire una foto

curl -X POST https://app.pedra.ai/api/update_video \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "videoId": "VIDEO_ID_FROM_CREATE",
    "images": [
      { "imageUrl": "https://example.com/living-room.jpg", "effect": "zoom-out" },
      { "imageUrl": "https://example.com/exterior.jpg", "effect": "zoom-in" },
      { "imageUrl": "https://example.com/new-kitchen.jpg", "effect": "zoom-in" }
    ]
  }'

Risposta

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

Crediti

I clip riutilizzati non costano nulla. Solo i frame nuovi o modificati (non statici) vengono ri-animati a 5 crediti ciascuno. Una modifica solo musica/voce/testo è gratuita. Nota: i video creati prima del riutilizzo dei clip ri-animano tutti i clip alla prima modifica basata sulle immagini.

Voiceover e audio

Un flusso in due passaggi: scrivi un copione dalle foto (o fornisci il tuo), rendilo in audio, poi allega l'audioId restituito all'oggetto voice di un video. I sottotitoli vengono generati automaticamente dai tempi delle parole del voiceover.

Generare un copione per il voiceover

Scrive un copione breve e naturale a partire dalle foto dell'annuncio e (facoltativamente) dai dati dell'immobile. Usa la visione affinché il copione rifletta ciò che è realmente nelle immagini. Restituisce il testo — passalo a /api/generate_voice, o modificalo prima.

Parametri principali

curl -X POST https://app.pedra.ai/api/generate_voice_script \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "images": [
      "https://example.com/exterior.jpg",
      "https://example.com/living-room.jpg"
    ],
    "propertyCharacteristics": [
      { "label": "Bedrooms", "value": "2" },
      { "label": "Surface", "value": "85 m²" }
    ],
    "language": "English"
  }'

Risposta

{
  "message": "Script generated successfully",
  "script": "Welcome to this bright, renovated two-bedroom apartment. Step into a sunlit, open-plan living space with room to breathe across 85 square metres."
}

La generazione del copione è gratuita.

Generare un voiceover

Rende un copione in una traccia di voiceover tramite sintesi vocale. Restituisce un audioId — passalo a voice.audioId di un video in create_video o update_video per allegare la narrazione (e i suoi sottotitoli sincronizzati).

Parametri principali

curl -X POST https://app.pedra.ai/api/generate_voice \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "text": "Welcome to this bright, renovated two-bedroom apartment.",
    "language": "English"
  }'

Risposta

{
  "message": "Voice generated successfully",
  "audioId": "<uuid>",
  "audioUrl": "https://img.pedra.ai/audio/<uuid>.mp3",
  "alignmentUrl": "https://img.pedra.ai/audio/<uuid>.alignment.json",
  "duration": 7
}

Crediti

Ogni voiceover costa 1 credito. Il limite di testo è di 1000 caratteri.

Elencare la libreria musicale

Restituisce i valori validi di music.track (chiavi di genere) con etichette, oltre alle lingue accettate dagli endpoint di voiceover. Di sola lettura — non consuma mai crediti e accetta GET o POST.

curl https://app.pedra.ai/api/music_library

Risposta

{
  "tracks": [
    { "track": "acoustic", "label": "Acoustic & Warm" },
    { "track": "chill", "label": "Chill Beats" },
    { "track": "cinematic", "label": "Cinematic & Orchestral" },
    { "track": "electronic", "label": "Modern Electronic" },
    { "track": "upbeat", "label": "Upbeat & Energetic" }
  ],
  "variantsPerTrack": 6,
  "defaultTrack": "chill",
  "voiceLanguages": ["English", "Español", "Français", "Deutsch", "Português", "Italiano", "Nederlands", "Polski"]
}

Successivo

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