API de vídeo y locución

Genera vídeos para anuncios inmobiliarios desde fotos, edítalos sin volver a renderizar, añade locuciones con IA y subtítulos sincronizados, y elige música de fondo — todo desde llamadas JSON síncronas.

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 — configura un timeout de cliente generoso

El endpoint bloquea mientras se renderiza el vídeo y luego devuelve la URL reproducible. El renderizado puede tardar varios minutos, así que configura el timeout del cliente HTTP de forma generosa — los 30–60 segundos por defecto de la mayoría de librerías HTTP cortarán antes de que Pedra responda.

Parámetros principales

Objeto image

Cada entrada de images describe un frame:

Opciones de marca de agua

Pistas de música

Locución

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

Respuesta

{
  "message": "Video created successfully",
  "videoId": "<uuid>",
  "videoUrl": "https://img.pedra.ai/<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.

Actualizar un vídeo existente

Edita un vídeo que ya creaste — mediante videoId — sin volver a renderizar los clips que no cambian. Reordenar, cambiar la música o la locución, modificar el branding, las tarjetas finales, los subtítulos y los títulos se vuelven a ensamblar gratis. Solo las fotos nuevas o modificadas se vuelven a animar (y consumen créditos). Como create_video, es síncrono y devuelve la nueva videoUrl. Si el vídeo se creó con un propertyId, ese vínculo se hereda automáticamente — no hace falta enviarlo de nuevo.

Semántica de actualización parcial

Todos los campos excepto videoId son opcionales. Omite images para conservar la línea de tiempo existente y cambiar solo audio/texto/branding (un re-ensamblado gratuito). Omite music, voice, branding o el texto final para dejar cada uno con su valor guardado — editar la música nunca borra la locución, y viceversa. Cuando sí envías images, un clip cuya foto + efecto (+ segunda foto en transiciones) coincide con uno existente se reutiliza tal cual.

Parámetros principales

Ejemplo: cambiar solo la música

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

Ejemplo: reordenar + cambiar 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" }
    ]
  }'

Respuesta

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

Créditos

Los clips reutilizados no cuestan nada. Solo los frames nuevos o modificados (no estáticos) se vuelven a animar a 5 créditos cada uno. Una edición solo de música/voz/texto es gratuita. Nota: los vídeos creados antes de la reutilización de clips vuelven a animar todos los clips en su primera edición basada en imágenes.

Locución y audio

Un flujo de dos pasos: escribe un guion a partir de las fotos (o aporta el tuyo), renderízalo a audio y luego adjunta el audioId devuelto al objeto voice de un vídeo. Los subtítulos se generan automáticamente a partir de los tiempos de las palabras de la locución.

Generar un guion de locución

Escribe un guion de locución breve y natural a partir de las fotos del anuncio y (opcionalmente) los datos de la propiedad. Usa visión para que el guion refleje lo que realmente aparece en las imágenes. Devuelve el texto del guion — pásalo a /api/generate_voice, o edítalo antes.

Parámetros principales

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

Respuesta

{
  "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 generación de guiones es gratuita.

Generar una locución

Renderiza un guion a una pista de locución mediante texto a voz. Devuelve un audioId — pásalo a voice.audioId de un vídeo en create_video o update_video para adjuntar la narración (y sus subtítulos sincronizados).

Parámetros principales

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

Respuesta

{
  "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éditos

Cada locución cuesta 1 crédito. El límite de texto es de 1000 caracteres.

Listar la biblioteca de música

Devuelve los valores válidos de music.track (claves de género) con etiquetas, además de los idiomas aceptados por los endpoints de locución. De solo lectura — nunca consume créditos y acepta GET o POST.

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

Respuesta

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

Siguiente

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