Video- & Voiceover-API

Generieren Sie Anzeigenvideos aus Fotos, bearbeiten Sie sie ohne erneutes Rendering, fügen Sie KI-Voiceovers mit synchronisierten Untertiteln hinzu und wählen Sie Hintergrundmusik — alles über synchrone JSON-Aufrufe.

Erstellt ein MP4-Video aus einer Liste von Bildern mit Bewegungseffekten, optionalen Untertiteln, Hintergrundmusik, Immobilienmerkmal-Overlays und Endkarten. Der Endpunkt ist synchron: Er blockiert, bis das Video gerendert ist, und gibt dann HTTP 200 mit der finalen videoUrl zurück.

Synchron — setzen Sie ein großzügiges Client-Timeout

Der Endpunkt blockiert während des Video-Renderings und gibt dann die abspielbare URL zurück. Das Rendering kann mehrere Minuten dauern, setzen Sie das Timeout Ihres HTTP-Clients daher großzügig — die Standard-30–60 Sekunden der meisten HTTP-Bibliotheken werden vor Pedras Antwort abbrechen.

Parameter auf oberster Ebene

Image-Objekt

Jeder Eintrag in images beschreibt einen Frame:

Wasserzeichen-Optionen

Musiktitel

Voiceover

Branding

Beispiel: minimales 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"
  }'

Beispiel: vollständiges Produktions-Anzeigenvideo

3-Frame-Walkthrough mit gemischten Effekten (zoom-in / zoom-out / transition / static), individuelles Wasserzeichen + Agentenfoto + Markenfarbe, Musik, Voiceover, Untertitel pro Frame, Overlay mit Immobilienmerkmalen und Endkarte. Entspricht dem typischen realen Payload-Muster, das Pedras eigene App verwendet.

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

Antwort

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

Credits

Jeder Frame kostet 5 Credits — außer Frames mit effect: "static", die kostenlos sind. Ein Video mit 5 Bildern und allen zoom-in/zoom-out-Effekten zieht 25 Credits ab. Siehe Preise.

Validierungsfehler

HTTP 400 wird zurückgegeben bei:

• Fehlendes oder leeres images-Array.
• Jedes Bild ohne imageUrl (der Fehler nennt den fehlerhaften Index).
• effect nicht in [zoom-in, zoom-out, transition, static].
• effect: "transition" ohne secondImageUrl.

Verfügbare Merkmalsbezeichnungen

Bei Verwendung von propertyCharacteristics werden die folgenden Etikett-Schlüssel mit passenden Symbolen im Overlay gerendert: Bedrooms, Bathrooms, Surface, Price, Location, Parking, Heating, Outdoor. Benutzerdefinierte Etiketten sind erlaubt, werden aber ohne Symbol gerendert.

Ein bestehendes Video aktualisieren

Bearbeitet ein bereits erstelltes Video — per videoId — ohne unveränderte Clips neu zu rendern. Neu anordnen, Musik oder Voiceover wechseln, Branding, Endkarten, Untertitel und Titel ändern werden kostenlos neu zusammengefügt. Nur neue oder geänderte Fotos werden neu animiert (und kosten Credits). Wie create_video ist der Aufruf synchron und gibt die neue videoUrl zurück. Wurde das Video mit einer propertyId erstellt, wird diese Verknüpfung automatisch übernommen — sie muss nicht erneut mitgeschickt werden.

Patch-Semantik

Alle Felder außer videoId sind optional. Lassen Sie images weg, um die bestehende Timeline beizubehalten und nur Audio/Text/Branding zu ändern (ein kostenloses Neu-Zusammenfügen). Lassen Sie music, voice, branding oder den Endtext weg, um jeden beim gespeicherten Wert zu belassen — das Bearbeiten der Musik löscht nie das Voiceover und umgekehrt. Wenn Sie images senden, wird ein Clip, dessen Foto + Effekt (+ zweites Foto bei Übergängen) einem bestehenden entspricht, unverändert wiederverwendet.

Parameter auf oberster Ebene

Beispiel: nur die Musik ändern

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

Beispiel: neu anordnen + ein Foto austauschen

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

Antwort

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

Credits

Wiederverwendete Clips kosten nichts. Nur neue oder geänderte (nicht statische) Frames werden zu je 5 Credits neu animiert. Eine reine Musik-/Stimme-/Text-Bearbeitung ist kostenlos. Hinweis: Videos, die vor der Clip-Wiederverwendung erstellt wurden, animieren bei ihrer ersten bildbasierten Bearbeitung alle Clips neu.

Voiceover & Audio

Ein zweistufiger Ablauf: Schreiben Sie ein Skript aus den Fotos (oder liefern Sie ein eigenes), rendern Sie es zu Audio und hängen Sie dann die zurückgegebene audioId an das voice-Objekt eines Videos an. Untertitel werden automatisch aus dem Wort-Timing des Voiceovers erzeugt.

Sprechertext generieren

Schreibt einen kurzen, natürlichen Sprechertext aus den Anzeigenfotos und (optional) den Immobiliendaten. Nutzt Bildverständnis, damit der Text das widerspiegelt, was tatsächlich auf den Bildern zu sehen ist. Gibt den Text zurück — übergeben Sie ihn an /api/generate_voice oder bearbeiten Sie ihn zuvor.

Parameter auf oberster Ebene

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

Antwort

{
  "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."
}

Die Skripterstellung ist kostenlos.

Voiceover generieren

Rendert ein Skript per Text-to-Speech in eine Voiceover-Tonspur. Gibt eine audioId zurück — übergeben Sie sie an voice.audioId eines Videos in create_video oder update_video, um die Erzählung (und ihre synchronisierten Untertitel) anzuhängen.

Parameter auf oberster Ebene

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

Antwort

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

Credits

Jedes Voiceover kostet 1 Credit. Das Textlimit beträgt 1000 Zeichen.

Musikbibliothek auflisten

Gibt die gültigen music.track-Werte (Genre-Schlüssel) mit Anzeigebezeichnungen zurück, plus die von den Voiceover-Endpunkten akzeptierten Sprachen. Schreibgeschützt — zieht nie Credits ab und akzeptiert GET oder POST.

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

Antwort

{
  "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"]
}

Weiter

Siehe Fehler und Limits für Fehlermodi und Timeout-Verhalten bei Video-Jobs.