API de vídeo e narração

Gere vídeos de anúncios a partir de fotos, edite-os sem voltar a renderizar, adicione narrações com IA e legendas sincronizadas, e escolha música de fundo — tudo a partir de chamadas JSON síncronas.

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 — define um timeout de cliente generoso

O endpoint bloqueia enquanto o vídeo é renderizado, depois devolve o URL reproduzível. A renderização pode demorar vários minutos, por isso define o timeout do teu cliente HTTP de forma generosa — os 30–60 segundos padrão da maioria das bibliotecas HTTP terminarão antes da Pedra responder.

Parâmetros de topo

Objeto image

Cada entrada de images descreve um frame:

Opções de marca de água

Faixas de música

Narração

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

Resposta

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

Atualizar um vídeo existente

Edita um vídeo que já criaste — através do videoId — sem voltar a renderizar os clips inalterados. Reordenar, trocar a música ou a narração, alterar o branding, os cartões finais, as legendas e os títulos são reagrupados gratuitamente. Apenas fotos novas ou alteradas são reanimadas (e consomem créditos). Tal como o create_video, é síncrono e devolve o novo videoUrl. Se o vídeo foi criado com um propertyId, essa ligação é herdada automaticamente — não é preciso voltar a enviá-lo.

Semântica de atualização parcial

Todos os campos exceto videoId são opcionais. Omite images para manter a linha de tempo existente e mudar apenas áudio/texto/branding (um reagrupamento gratuito). Omite music, voice, branding ou o texto final para deixar cada um no valor guardado — editar a música nunca apaga a narração, e vice-versa. Quando envias images, um clip cuja foto + efeito (+ segunda foto nas transições) corresponde a um existente é reutilizado tal como está.

Parâmetros de topo

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

Exemplo: reordenar + trocar uma 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" }
    ]
  }'

Resposta

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

Créditos

Os clips reutilizados não custam nada. Apenas frames novos ou alterados (não estáticos) são reanimados a 5 créditos cada. Uma edição apenas de música/voz/texto é gratuita. Nota: vídeos criados antes da reutilização de clips reanimam todos os clips na sua primeira edição baseada em imagens.

Narração e áudio

Um fluxo em dois passos: escreve um guião a partir das fotos (ou fornece o teu), renderiza-o para áudio e depois anexa o audioId devolvido ao objeto voice de um vídeo. As legendas são geradas automaticamente a partir dos tempos das palavras da narração.

Gerar um guião de narração

Escreve um guião de narração curto e natural a partir das fotos do anúncio e (opcionalmente) dos dados do imóvel. Usa visão para que o guião reflita o que está realmente nas imagens. Devolve o texto do guião — passa-o a /api/generate_voice, ou edita-o antes.

Parâmetros de topo

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

Resposta

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

A geração do guião é gratuita.

Gerar uma narração

Renderiza um guião numa faixa de narração por conversão de texto em voz. Devolve um audioId — passa-o ao voice.audioId de um vídeo em create_video ou update_video para anexar a narração (e as suas legendas sincronizadas).

Parâmetros de topo

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

Resposta

{
  "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 narração custa 1 crédito. O limite de texto é de 1000 caracteres.

Listar a biblioteca de música

Devolve os valores válidos de music.track (chaves de género) com rótulos, mais os idiomas aceites pelos endpoints de narração. Apenas leitura — nunca consome créditos e aceita GET ou POST.

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

Resposta

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

Seguinte

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