API de propriedades

Explora as propriedades de uma conta Pedra, lê os URLs das suas fotos para usar no create_video e nos endpoints de edição, cria propriedades e adiciona-lhes fotos por URL.

Os imóveis são a forma como as fotos são organizadas numa conta Pedra. Estes endpoints permitem explorar os imóveis de um utilizador, ler os URLs das fotos de um imóvel (para os passar diretamente ao create_video ou aos endpoints de edição), criar imóveis e adicionar-lhes fotos por URL — o servidor descarrega cada URL e armazena-a, por isso funciona qualquer imagem pública.

As fotos que já estão na conta são a fonte mais fácil para um vídeo. As fotos novas entram de três formas: URLs públicos com add_images_to_property; ficheiros locais com o mesmo endpoint, enviados como URIs data: em base64; ou, quando as fotos estão no telemóvel de alguém, um link de carregamento que essa pessoa abre para as carregar sem login.

Listar imóveis

Devolve os imóveis da conta (mais recentes primeiro), cada um com uma contagem de fotos e um appUrl.

curl -X POST https://app.pedra.ai/api/list_properties \
  -H "Content-Type: application/json" \
  -d '{ "apiKey": "YOUR_API_KEY" }'

Resposta

{
  "properties": [
    {
      "propertyId": "<uuid>",
      "name": "Calle Mayor 12",
      "createdAt": "2026-06-30T10:00:00.000Z",
      "photoCount": 8,
      "appUrl": "https://app.pedra.ai/?propertyId=<uuid>"
    }
  ]
}

Listar fotos do imóvel

Devolve as fotos de um imóvel como URLs públicos img.pedra.ai — passa-as diretamente ao create_video ou aos endpoints de edição de imagens.

curl -X POST https://app.pedra.ai/api/list_property_images \
  -H "Content-Type: application/json" \
  -d '{ "apiKey": "YOUR_API_KEY", "propertyId": "PROPERTY_ID" }'

Resposta

{
  "propertyId": "<uuid>",
  "name": "Calle Mayor 12",
  "images": [
    {
      "imageId": "<uuid>",
      "url": "https://img.pedra.ai/<uuid>",
      "name": "Image 1",
      "aspectRatio": 1.5
    }
  ]
}

Criar um imóvel

Cria um imóvel vazio e devolve o seu propertyId e appUrl.

curl -X POST https://app.pedra.ai/api/create_property \
  -H "Content-Type: application/json" \
  -d '{ "apiKey": "YOUR_API_KEY", "name": "Calle Mayor 12" }'

Resposta

{
  "message": "Property created",
  "propertyId": "<uuid>",
  "appUrl": "https://app.pedra.ai/?propertyId=<uuid>"
}

Adicionar fotos a um imóvel

Adiciona fotos a um imóvel por URL. O servidor descarrega cada URL e armazena-a (por isso funciona qualquer imagem https pública — ou um pequeno URI data:), e depois devolve os URLs img.pedra.ai armazenados. Até 20 por chamada.

Envia type: "360" para adicionar antes fotos 360° para um tour virtual: cada uma é verificada como equirretangular (2:1) e guardada tal como na app, até 10 por chamada. Os URIs data: também funcionam aqui, por isso podes enviar ficheiros 360° locais em base64 — um ou poucos por chamada, abaixo do limite de 50 MB por pedido. As fotos que não são 360° voltam em failed com o motivo.

Cada foto guardada aqui conta para o limite diário de carregamento da conta: 30 por dia no plano gratuito, 500 nos planos pagos. Acima dele, a chamada devolve 429 com code: "upload_limit" e nada é guardado; as fotos que falham por si não contam.

curl -X POST https://app.pedra.ai/api/add_images_to_property \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "propertyId": "PROPERTY_ID",
    "imageUrls": [
      "https://example.com/kitchen.jpg",
      "https://example.com/living-room.jpg"
    ],
    "names": ["IMG_0412.jpg", "IMG_0413.jpg"]
  }'

Resposta

{
  "message": "Added 2 image(s)",
  "propertyId": "<uuid>",
  "added": [
    { "imageId": "<uuid>", "url": "https://img.pedra.ai/<uuid>", "name": "IMG_0412.jpg", "aspectRatio": 1.5 }
  ],
  "failed": [],
  "appUrl": "https://app.pedra.ai/?propertyId=<uuid>"
}

Fotos do telemóvel: links de carregamento

Quando as fotos estão no telemóvel de alguém — o agente, o fotógrafo, o proprietário — create_upload_link é a forma mais simples de as pôr num imóvel. Devolve uma página sem login, válida 24 horas, que aceita até 100 fotos (JPEG, PNG, WebP e HEIC a partir de um iPhone). Com o type: "any" predefinido aceita fotos normais e fotos 360°, e as imagens 2:1 são guardadas como 360° automaticamente; type: "360" aceita só fotos 360°.

Envia o uploadUrl à pessoa; quando ela terminar, chama list_property_images (type "photo" ou "360") e usa os URLs com os endpoints de edição, create_video ou create_virtual_tour. Os links de carregamento são grátis; podes criar 5 por dia no plano gratuito e 50 nos planos pagos, e cada ficheiro carregado conta para o limite diário de carregamento. Referência completa: create_upload_link.

curl -X POST https://app.pedra.ai/api/create_upload_link \
  -H "Content-Type: application/json" \
  -d '{ "apiKey": "YOUR_API_KEY", "propertyId": "PROPERTY_ID" }'

Seguinte

Passa os URLs das fotos de um imóvel ao create_video, ou usa-os com qualquer endpoint de home staging virtual / melhoria.