API Proprietà

Sfoglia le proprietà di un account Pedra, leggi gli URL delle loro foto per usarli con create_video e gli endpoint di modifica, crea proprietà e aggiungivi foto tramite URL.

I proprietà sono il modo in cui le foto vengono organizzate in un account Pedra. Questi endpoint permettono di sfogliare i proprietà di un utente, leggere gli URL delle foto di un proprietà (per passarli direttamente a create_video o agli endpoint di modifica), creare proprietà e aggiungervi foto tramite URL — il server scarica ogni URL e la memorizza, quindi funziona qualsiasi immagine pubblica.

Le foto già nell'account sono la fonte più semplice per un video. Le foto nuove entrano in tre modi: URL pubblici con add_images_to_property; file locali con lo stesso endpoint, inviati come URI data: in base64; oppure, quando le foto sono sullo smartphone di qualcuno, un link di caricamento che apre per caricarle senza login.

Elencare i proprietà

Restituisce i proprietà dell'account (i più recenti prima), ciascuno con un conteggio foto e un appUrl.

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

Risposta

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

Elencare le foto del proprietà

Restituisce le foto di un proprietà come URL pubblici img.pedra.ai — passale direttamente a create_video o agli endpoint di modifica immagini.

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

Risposta

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

Creare un proprietà

Crea un proprietà vuoto e restituisce il suo 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" }'

Risposta

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

Aggiungere foto a un proprietà

Aggiunge foto a un proprietà tramite URL. Il server scarica ogni URL e la memorizza (quindi funziona qualsiasi immagine https pubblica — o un piccolo URI data:), poi restituisce gli URL img.pedra.ai memorizzati. Fino a 20 per chiamata.

Invia type: "360" per aggiungere invece foto 360° per un tour virtuale: ognuna viene verificata come equirettangolare (2:1) e salvata come nell'app, fino a 10 per chiamata. Anche qui funzionano gli URI data:, quindi puoi inviare file 360° locali codificati in base64 — uno o pochi per chiamata, sotto il limite di 50 MB per richiesta. Le foto che non sono 360° tornano in failed con il motivo.

Ogni foto salvata qui conta nel limite giornaliero di caricamento dell'account: 30 al giorno sul piano gratuito, 500 sui piani a pagamento. Oltre il limite, la chiamata restituisce 429 con code: "upload_limit" e non si salva nulla; le foto che falliscono da sole non contano.

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

Risposta

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

Foto dallo smartphone: link di caricamento

Quando le foto sono sullo smartphone di qualcuno — l'agente, il fotografo, il proprietario — create_upload_link è il modo più semplice per metterle in una proprietà. Restituisce una pagina senza login, valida 24 ore, che accetta fino a 100 foto (JPEG, PNG, WebP e HEIC da iPhone). Con il type: "any" predefinito accetta foto normali e foto 360°, e le immagini 2:1 vengono salvate come 360° automaticamente; type: "360" accetta solo foto 360°.

Invia l'uploadUrl alla persona; quando ha finito, chiama list_property_images (type "photo" o "360") e usa gli URL con gli endpoint di modifica, create_video o create_virtual_tour. I link di caricamento sono gratuiti; puoi crearne 5 al giorno sul piano gratuito e 50 sui piani a pagamento, e ogni file caricato conta nel limite giornaliero di caricamento. Riferimento completo: 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" }'

Successivo

Passa gli URL delle foto di un proprietà a create_video, oppure usali con qualsiasi endpoint di home staging virtuale / miglioramento.