API de criação de vídeo

Gere vídeos de anúncios imobiliários a partir de fotos. Adicione legendas, música, características do imóvel e branding personalizado — tudo a partir de uma única chamada JSON síncrona.

Constrói um vídeo MP4 a partir de uma lista de imagens com efeitos de movimento, legendas opcionais, música de fundo, sobreposições com características do imóvel e cartões finais. O endpoint é síncrono: bloqueia até o vídeo ser renderizado e depois devolve HTTP 200 com o videoUrl final.

Síncrono, com timeout longo

O endpoint bloqueia até 10 minutos enquanto o vídeo é renderizado, depois devolve o URL reproduzível. Define o timeout do teu cliente HTTP para pelo menos 11 minutos — os 30–60 segundos padrão da maioria das bibliotecas HTTP terminarão antes da Pedra responder.

Se a renderização exceder 10 minutos, o endpoint devolve 500 com {"error": "Video processing timeout after 10 minutes..."}. O vídeo pode ainda terminar em segundo plano — contacta o suporte com o corpo do pedido se isto acontecer.

Parâmetros de topo

Objeto image

Cada entrada de images descreve um frame:

Opções de marca de água

Faixas de música

Branding

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

Exemplo: vídeo de anúncio de produção completo

Walkthrough de 7 frames com efeitos mistos (zoom-in / zoom-out / transition / static), marca de água personalizada + foto do agente + cor da marca, música, narração, legendas por frame, sobreposição com características do imóvel e cartão final. Corresponde ao padrão de payload real que a própria app Pedra utiliza.

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

Resposta

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

Créditos

Cada frame custa 5 créditos — exceto frames com effect: "static", que são gratuitos. Um vídeo de 5 imagens com todos os efeitos zoom-in/zoom-out consome 25 créditos. Ver Preços.

Erros de validação

HTTP 400 é devolvido para:

• Array images em falta ou vazio.
• Qualquer imagem sem imageUrl (o erro indica o índice em falta).
• effect fora de [zoom-in, zoom-out, transition, static].
• effect: "transition" sem secondImageUrl.

Rótulos de características disponíveis

Ao usar propertyCharacteristics, as seguintes chaves de rótulo são renderizadas com ícones correspondentes na sobreposição: Bedrooms, Bathrooms, Surface, Price, Location, Parking, Heating, Outdoor. Rótulos personalizados são aceites mas renderizados sem ícone.

Seguinte

Ver Erros e limites para os modos de falha das tarefas de vídeo e o comportamento de timeouts.