SDK

SDK ufficiali Python e JavaScript/TypeScript per l'API Pedra. Home staging virtuale, rinnovazione, miglioramento immagini e video per annunci in poche righe di codice — ogni metodo attende che la risorsa sia pronta e restituisce l'URL finale.

SDK ufficiali

Due client ufficiali avvolgono l'API REST di Pedra. Entrambi sono open source, non hanno dipendenze a runtime ed espongono ogni endpoint. Ogni metodo attende che la risorsa sia pronta e restituisce l'URL (o gli URL) finale — senza ID di lavoro da interrogare.

Installazione

Node.js

npm install @pedra-ai/sdk

Python

pip install pedra

Autenticazione

Passa la tua chiave al client oppure imposta la variabile d'ambiente PEDRA_API_KEY. Ottieni una chiave registrandoti su app.pedra.ai e aprendo Impostazioni → API. Le chiavi sono di lunga durata — non distribuirle mai nel codice client; chiama dal tuo backend. Vedi Autenticazione per i dettagli.

from pedra import Pedra

# Reads PEDRA_API_KEY from the environment…
pedra = Pedra()

# …or pass the key explicitly
pedra = Pedra("YOUR_API_KEY")

Avvio rapido

Arreda una stanza vuota. Ogni metodo immagine restituisce la stessa forma — usa url per la prima risorsa o urls per tutte.

from pedra import Pedra

pedra = Pedra()  # reads PEDRA_API_KEY

result = pedra.furnish(
    image_url="https://example.com/empty-living-room.jpg",
    room_type="Living room",
    style="Minimalist",
)

print(result.url)   # the staged image URL
print(result.urls)  # all generated URLs

Cosa puoi chiamare

Entrambi gli SDK coprono ogni endpoint Pedra con gli stessi nomi di metodo in entrambi i linguaggi:

• furnish, empty, renovation, editViaPrompt, remove — vedi Home staging virtuale.
• enhance, enhanceAndCorrectPerspective, sky, blur — vedi Miglioramento immagini.
• createVideo, updateVideo, generateVoiceScript, generateVoice, musicLibrary, oltre a credits e feedback — vedi Video e Crediti.
• listProperties, listPropertyImages, createProperty, addImagesToProperty — vedi Proprietà.
• createVirtualTour, waitForVirtualTour, getVirtualTour, listVirtualTours, updateVirtualTour, addVirtualTourScenes, deleteVirtualTour, createUploadLink, addLocalPanoramas — vedi Tour virtuali.

Python usa snake_case (edit_via_prompt, create_video, update_video, generate_voice, music_library, wait_for_virtual_tour, request_access, wait_for_access); parametri e comportamento sono identici.

Tour virtuali

I tour sono l'unico flusso asincrono: createVirtualTour ritorna subito con status: "processing", e waitForVirtualTour interroga finché il tour è pronto (circa 10 secondi per stanza). Una costruzione fallita viene restituita, non lanciata — controlla status.

from pedra import Pedra

pedra = Pedra()

tour = pedra.create_virtual_tour(
    image_urls=[  # 360° photos, in walking order
        "https://example.com/360/entrance.jpg",
        "https://example.com/360/living-room.jpg",
        "https://example.com/360/kitchen.jpg",
    ],
    name="Calle Mayor 12",
)
tour = pedra.wait_for_virtual_tour(tour.tour_id)

if tour.status == "ready":
    print(tour.tour_url)    # shareable tour page
    print(tour.embed_code)  # <iframe> for a listing page

Non hai ancora una chiave API?

Un agente o uno script può ottenerne una per la persona per cui lavora — creando il suo account Pedra se serve. requestAccess le invia un link di conferma via email (senza chiave); waitForAccess interroga finché approva e restituisce l'apiKey. Entrambi sono anche metodi statici di Pedra. Vedi Account per agenti IA.

from pedra import Pedra, request_access, wait_for_access

req = request_access("maria@example.com", agent_name="My listing assistant")
print("Check your email and click the link from Pedra.")

res = wait_for_access(req.request_id)  # polls every 5 s, up to 30 min
if res.approved:
    if res.note:
        print(res.note)  # only when there are no credits left
    pedra = Pedra(res.api_key)  # store the key; it doesn't expire

Gestione degli errori

Entrambi gli SDK sollevano PedraApiError per gli errori dell'API (con status e body) e PedraError per gli errori client/rete. Vedi Errori e limiti per l'elenco completo dei modi di errore.

Server MCP

Preferisci usare Pedra da un assistente IA? Il server MCP ufficiale di Pedra espone le stesse operazioni a Claude, ChatGPT e Cursor, così puoi fare staging e modificare le foto degli annunci direttamente da una chat.

Codice & supporto

Entrambi gli SDK hanno licenza MIT e sono sviluppati in modo aperto. Metti una stella o apri issue su GitHub e scrivi a felix@pedra.ai per aiuto con l'integrazione, quote più alte o condizioni enterprise.

Domande frequenti