API de creación de vídeo

Genera vídeos para anuncios inmobiliarios desde fotos. Añade subtítulos, música, características de la propiedad y branding personalizado — todo desde una sola llamada JSON síncrona.

Crea un vídeo MP4 a partir de una lista de imágenes con efectos de movimiento, subtítulos opcionales, música de fondo, superposiciones con características de la propiedad y tarjetas finales. El endpoint es síncrono: bloquea hasta que se renderiza el vídeo y luego devuelve HTTP 200 con la videoUrl final.

Síncrono, con timeout largo

El endpoint bloquea hasta 10 minutos mientras se renderiza el vídeo y luego devuelve la URL reproducible. Configura el timeout del cliente HTTP a al menos 11 minutos — los 30–60 segundos por defecto de la mayoría de librerías HTTP cortarán antes de que Pedra responda.

Si el renderizado supera los 10 minutos, el endpoint devuelve 500 con {"error": "Video processing timeout after 10 minutes..."}. El vídeo puede completarse en segundo plano — contacta con soporte con el cuerpo de la petición si esto ocurre.

Parámetros principales

Objeto image

Cada entrada de images describe un frame:

Opciones de marca de agua

Pistas de música

Branding

Ejemplo: vídeo mínimo

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

Ejemplo: vídeo de anuncio completo de producción

Walkthrough de 7 frames con efectos mezclados (zoom-in / zoom-out / transition / static), marca de agua personalizada + foto del agente + color de marca, música, locución, subtítulos por frame, superposición con características de la propiedad y tarjeta final. Coincide con el patrón de payload real que usa la propia app de 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"
  }'

Respuesta

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

Créditos

Cada frame cuesta 5 créditos — excepto los frames con effect: "static", que son gratuitos. Un vídeo de 5 imágenes con todos los efectos zoom-in/zoom-out consume 25 créditos. Consulta Precios.

Errores de validación

Se devuelve HTTP 400 cuando:

• Array images ausente o vacío.
• Cualquier imagen sin imageUrl (el error indica el índice infractor).
• effect no incluido en [zoom-in, zoom-out, transition, static].
• effect: "transition" sin secondImageUrl.

Etiquetas de características disponibles

Cuando uses propertyCharacteristics, las siguientes claves de etiqueta se renderizan con iconos en la superposición: Bedrooms, Bathrooms, Surface, Price, Location, Parking, Heating, Outdoor. Las etiquetas personalizadas se aceptan pero se renderizan sin icono.

Siguiente

Consulta Errores y límites para conocer los modos de fallo de los trabajos de vídeo y el comportamiento ante timeouts.