API vidéo et voix off

Générez des vidéos d'annonces à partir de photos, modifiez-les sans nouveau rendu, ajoutez des voix off IA avec sous-titres synchronisés et choisissez une musique de fond — le tout depuis des appels JSON synchrones.

Construit une vidéo MP4 à partir d'une liste d'images avec effets de mouvement, sous-titres optionnels, musique de fond, superpositions de caractéristiques du bien et cartes finales. L'endpoint est synchrone : il se bloque jusqu'à ce que la vidéo soit rendue, puis renvoie HTTP 200 avec l'videoUrl final.

Synchrone — définissez un timeout client généreux

L'endpoint se bloque pendant le rendu de la vidéo, puis renvoie l'URL lisible. Le rendu peut prendre plusieurs minutes, alors configurez le timeout de votre client HTTP de manière généreuse — les 30–60 secondes par défaut de la plupart des bibliothèques HTTP couperont avant que Pedra ne réponde.

Paramètres principaux

Objet image

Chaque entrée de images décrit une image :

Options de filigrane

Pistes musicales

Voix off

Branding

Exemple : vidéo minimale

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

Exemple : vidéo d'annonce de production complète

Walkthrough de 3 images avec effets mélangés (zoom-in / zoom-out / transition / static), filigrane personnalisé + photo de l'agent + couleur de marque, musique, voix off, sous-titres par image, superposition des caractéristiques du bien et carte finale. Correspond au payload réel utilisé par l'application Pedra elle-même.

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

Réponse

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

Crédits

Chaque image coûte 5 crédits — sauf les images avec effect: "static", qui sont gratuites. Une vidéo de 5 images avec tous les effets zoom-in/zoom-out déduit 25 crédits. Voir Tarification.

Erreurs de validation

HTTP 400 est renvoyé pour :

• Tableau images manquant ou vide.
• Toute image sans imageUrl (l'erreur indique l'index fautif).
• effect hors de [zoom-in, zoom-out, transition, static].
• effect: "transition" sans secondImageUrl.

Étiquettes de caractéristiques disponibles

Lorsque vous utilisez propertyCharacteristics, les clés d'étiquettes suivantes s'affichent avec des icônes correspondantes dans la superposition : Bedrooms, Bathrooms, Surface, Price, Location, Parking, Heating, Outdoor. Les étiquettes personnalisées sont acceptées mais s'affichent sans icône.

Mettre à jour une vidéo existante

Modifie une vidéo déjà créée — via videoId — sans refaire le rendu des clips inchangés. Réorganiser, changer la musique ou la voix off, modifier le branding, les cartes finales, les sous-titres et les titres sont réassemblés gratuitement. Seules les photos nouvelles ou modifiées sont réanimées (et coûtent des crédits). Comme create_video, l'appel est synchrone et renvoie la nouvelle videoUrl. Si la vidéo a été créée avec un propertyId, ce lien est hérité automatiquement — inutile de le renvoyer.

Sémantique de mise à jour partielle

Tous les champs sauf videoId sont optionnels. Omettez images pour conserver la timeline existante et ne changer que l'audio/le texte/le branding (un réassemblage gratuit). Omettez music, voice, branding ou le texte de fin pour laisser chacun à sa valeur enregistrée — modifier la musique n'efface jamais la voix off, et inversement. Lorsque vous envoyez images, un clip dont la photo + l'effet (+ la seconde photo pour les transitions) correspond à un clip existant est réutilisé tel quel.

Paramètres principaux

Exemple : changer uniquement la musique

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

Exemple : réorganiser + remplacer une photo

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

Réponse

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

Crédits

Les clips réutilisés ne coûtent rien. Seules les images nouvelles ou modifiées (non statiques) sont réanimées à 5 crédits chacune. Une modification uniquement musique/voix/texte est gratuite. Remarque : les vidéos créées avant la réutilisation des clips réaniment tous les clips lors de leur première modification basée sur les images.

Voix off et audio

Un flux en deux étapes : rédigez un script à partir des photos (ou fournissez le vôtre), faites-en le rendu audio, puis attachez l'audioId renvoyé à l'objet voice d'une vidéo. Les sous-titres sont générés automatiquement à partir du minutage des mots de la voix off.

Générer un script de voix off

Rédige un script de voix off court et naturel à partir des photos de l'annonce et (optionnellement) des informations sur le bien. Utilise la vision pour que le script reflète ce qui est réellement sur les images. Renvoie le texte du script — transmettez-le à /api/generate_voice, ou modifiez-le d'abord.

Paramètres principaux

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

Réponse

{
  "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 génération de script est gratuite.

Générer une voix off

Effectue le rendu d'un script en piste de voix off via la synthèse vocale. Renvoie un audioId — transmettez-le au voice.audioId d'une vidéo dans create_video ou update_video pour attacher la narration (et ses sous-titres synchronisés).

Paramètres principaux

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

Réponse

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

Crédits

Chaque voix off coûte 1 crédit. La limite de texte est de 1000 caractères.

Lister la bibliothèque musicale

Renvoie les valeurs valides de music.track (clés de genre) avec leurs libellés, ainsi que les langues acceptées par les endpoints de voix off. En lecture seule — ne déduit jamais de crédits et accepte GET ou POST.

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

Réponse

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

Suivant

Voir Erreurs et limites pour les modes d'échec des tâches vidéo et le comportement des timeouts.