Machen Sie aus 360°-Fotos mit einem Aufruf einen gehosteten, teilbaren virtuellen Rundgang. Die KI benennt die Räume und setzt die Navigationspunkte dazwischen; Sie erhalten eine öffentliche URL und einen Einbettungs-iframe.
Senden Sie Ihre 360°-Fotos per POST und erhalten Sie einen gehosteten virtuellen Rundgang zum Teilen oder Einbetten. Pedra importiert die equirektangulären Fotos, die KI benennt jeden Raum und setzt die Navigationspunkte von Tür zu Tür, und die Antwort liefert eine öffentliche tourUrl und einen fertigen embedCode-iframe. Kein Viewer zum Hosten, keine Navigationspunkte zum Setzen von Hand.
Was Sie mit einem einzigen Aufruf bekommen:
Eine gehostete Rundgang-Seite — eine öffentliche tourUrl plus ein embedCode-iframe für jede Exposé-Seite, jedes CRM oder Portal. Funktioniert auf dem Handy (mit Gyroskop) und am Desktop.
KI-Raumnamen — Räume ohne Namen werden automatisch benannt (Eingang, Küche, Schlafzimmer 1…), in der Sprache des Rundgangs und kostenlos. Namen, die Sie übergeben, werden nie geändert.
KI-Navigation — Pedra findet jede Tür im Foto und setzt die Navigationspunkte zwischen den Räumen, in beide Richtungen.
Volle Kontrolle danach — Räume umbenennen, umsortieren, entfernen oder hinzufügen und die Navigationspunkte durch eigene ersetzen, alles über die API.
Funktioniert aus dem Chat — dieselben Endpunkte sind Tools im Pedra-MCP-Server, sodass ChatGPT und Claude einen Rundgang aus einer Unterhaltung heraus erstellen können.
So funktioniert es
Das Erstellen eines Rundgangs ist asynchron: Der Create-Aufruf gibt sofort eine tourId zurück, und der Rundgang wird im Hintergrund gebaut (etwa 10 Sekunden pro verknüpftem Raum).
Erstellen — POST /api/create_virtual_tour mit Ihren 360°-Fotos in Laufreihenfolge. Sie erhalten sofort tourId, tourUrl und embedCode, mit status: "processing".
Abfragen — rufen Sie POST /api/get_virtual_tour alle paar Sekunden auf, bis status"ready" ist (oder "failed", mit dem Grund in error).
Teilen — versenden Sie die tourUrl oder fügen Sie den embedCode in Ihre Exposé-Seite ein. Die URL bleibt gleich, wenn Sie den Rundgang später bearbeiten.
# 1. Create the tour (returns immediately with "status": "processing")
curl -X POST https://app.pedra.ai/api/create_virtual_tour \
-H "Content-Type: application/json" \
-d '{
"apiKey": "YOUR_API_KEY",
"name": "Calle Mayor 12",
"scenes": [
{ "imageUrl": "https://example.com/360/entrance.jpg", "name": "Entrance" },
{ "imageUrl": "https://example.com/360/living-room.jpg" },
{ "imageUrl": "https://example.com/360/kitchen.jpg" },
{ "imageUrl": "https://example.com/360/bedroom.jpg" }
]
}'
# 2. Poll until "status" is "ready" (or "failed")
curl -X POST https://app.pedra.ai/api/get_virtual_tour \
-H "Content-Type: application/json" \
-d '{ "apiKey": "YOUR_API_KEY", "tourId": "TOUR_ID" }'
Verknüpfungsmodi & Credits
Der Parameter linking bestimmt, wie Navigationspunkte gesetzt werden. Das Benennen der Räume ist immer kostenlos. Credits werden erst abgebucht, wenn die Verknüpfung startet, und ein fehlgeschlagener Aufbau kostet nie etwas.
Modus
Was er macht
Kosten
sequential
Standard. Übergeben Sie die Räume in Laufreihenfolge; jeder Raum wird mit dem nächsten verknüpft, in beide Richtungen.
max(3, ⌈Räume ÷ 3⌉) Credits — 3 bis 9 Räume, 4 für 12, 10 für 30
smart
Die KI vergleicht jedes Raumpaar und verknüpft die, die sichtbar verbunden sind — wenn Sie die Laufreihenfolge nicht kennen. Langsamer; bis zu 40 Räume.
5–160 Credits je nach Raumanzahl (Tabelle unten)
none
Keine Navigationspunkte. Setzen Sie später eigene mit update_virtual_tour.
Kostenlos
Smart-Verknüpfung nach Raumanzahl
Räume
Credits
1–6
5 credits
7–10
12 credits
11–15
25 credits
16–20
50 credits
21–25
70 credits
26–30
100 credits
31–35
130 credits
36–40
160 credits
add_virtual_tour_scenes kostet so viel wie die sequential-Verknüpfung, gezählt werden nur die neuen Räume. get_virtual_tour, list_virtual_tours, update_virtual_tour, delete_virtual_tour und create_upload_link sind kostenlos. Prüfen Sie Ihr Guthaben mit credits.
Einen virtuellen Rundgang erstellen
POST/api/create_virtual_tour
Importiert die 360°-Fotos und benennt und verknüpft die Räume dann im Hintergrund. Übergeben Sie scenes in Laufreihenfolge — die erste ist der Startpunkt des Rundgangs. Ohne propertyId wird eine neue Immobilie mit dem Namen aus name angelegt. Um einen Rundgang aus Fotos zu bauen, die schon in einer Immobilie liegen (etwa über einen Upload-Link hochgeladene), übergeben Sie nur die propertyId und lassen scenes weg: Dann werden alle 360°-Fotos der Immobilie in Upload-Reihenfolge verwendet. Eine Immobilie hat einen Rundgang; gibt es schon einen, erhalten Sie 409 tour_exists mit dessen tourId.
apiKeystringerforderlich
Ihr API-Schlüssel.
scenesarray
Die 360°-Fotos in Laufreihenfolge (max. 50). Pflicht, außer Sie übergeben eine propertyId, deren 360°-Fotos den Rundgang bilden sollen.
imageUrlsarray
Kurzform für scenes: eine einfache Liste von 360°-Foto-URLs.
propertyIdstring
Baut den Rundgang in dieser Immobilie. Nötig, wenn Szenen imageId verwenden. Ohne scenes werden alle 360°-Fotos der Immobilie in Upload-Reihenfolge verwendet. Weglassen, um eine neue Immobilie anzulegen.
namestring
Titel des Rundgangs, z. B. die Adresse des Inserats. Auch der Name der neuen Immobilie, falls eine angelegt wird.
linkingstring
Wie Navigationspunkte gesetzt werden — siehe Verknüpfungsmodi & Credits.
Values:sequentialsmartnone
Default:sequential
languagestring
Sprache der Rundgang-Seite und der KI-Raumnamen. Nicht-englische Rundgänge erhalten eine URL wie /de/virtual-tour/….
Values:enesfrdeitpt
Default:en
Scene-Objekt
Jede Szene ist { imageUrl } oder { imageId }, mit optionalem name. Ein einfacher String wird als imageUrl behandelt. Bis zu 50 Szenen pro Rundgang.
imageUrlstring
Öffentliche URL (oder data:-URI) eines equirektangulären 360°-Fotos — 2:1, bis 80 MB. Dropbox- und Google-Drive-Freigabelinks funktionieren.
imageIdstring
Ein 360°-Foto, das schon in der Immobilie liegt (aus list_property_images mit type "360"). Statt imageUrl verwenden.
namestring
Raumname. Weglassen, dann benennt die KI den Raum.
Gibt den Status des Rundgangs zurück und, sobald er fertig ist, seine Szenen, Navigationslinks und Anzeigeeinstellungen. Diesen Endpunkt fragen Sie nach create_virtual_tour und add_virtual_tour_scenes ab.
apiKeystringerforderlich
Ihr API-Schlüssel.
tourIdstringerforderlich
Die ID des Rundgangs (aus create_virtual_tour oder list_virtual_tours).
processing — wird gebaut. progress.stage ist queued, importing, naming oder linking, ggf. mit done / total.
ready — live unter tourUrl. Enthält scenes, links und settings.
failed — es wurde nichts berechnet. error nennt den Grund, und failedScenes listet jedes Foto, das nicht verwendet werden konnte (z. B. eines, das nicht 2:1 ist). Erfolgreich importierte Fotos bleiben in der Immobilie, sodass Sie das fehlerhafte ersetzen und den Rundgang per imageId neu erstellen können.
Schlägt ein add_virtual_tour_scenes-Aufruf fehl, bleibt der Rundgang ready und enthält lastError und failedScenes. Bei einem Konto im Gratis-Tarif wird der Rundgang gebaut, aber der öffentliche Link zeigt eine Upgrade-Seite: Die Antworten enthalten dann shareable: false und eine shareableNote.
Gibt die Rundgänge des Kontos zurück, neueste zuerst (bis zu 100), mit denselben Übersichtsfeldern wie get_virtual_tour, aber ohne scenes, links und settings. Gelöschte Rundgänge fehlen.
Benennen Sie den Rundgang oder seine Räume um, sortieren oder entfernen Sie Räume, ersetzen Sie die Navigationspunkte und ändern Sie ihr Aussehen. Kostenlos und sofort. Die Validierung gilt ganz oder gar nicht: Ist ein Feld ungültig, ändert sich nichts. Gibt den vollständigen Rundgang zurück, wie get_virtual_tour, oder 409 tour_processing, solange er noch gebaut wird.
apiKeystringerforderlich
Ihr API-Schlüssel.
tourIdstringerforderlich
Die ID des Rundgangs (aus create_virtual_tour oder list_virtual_tours).
namestring
Neuer Titel des Rundgangs.
sceneNamesobject
Raumnamen nach sceneId, z. B. { "<sceneId>": "Küche" }.
sceneOrderarray
Jede sceneId genau einmal, in der neuen Reihenfolge. Die erste ist der Startpunkt des Rundgangs.
removeScenesarray
sceneIds, die aus dem Rundgang entfernt werden. Die Fotos bleiben in der Immobilie, betroffene Links entfallen. Mindestens eine Szene muss bleiben.
linksarray
Ersetzt ALLE Navigationslinks. Jeder Link gilt in eine Richtung: { fromSceneId, toSceneId, yaw, pitch? }.
navigationStylestring
Farbe der Navigationspunkte.
Values:whiteblue
navigationSizestring
Größe der Navigationspunkte.
Values:smallmediumlarge
showLabelsboolean
Den Namen des Zielraums immer neben jedem Navigationspunkt anzeigen.
languagestring
Sprache der Rundgang-Seite.
Values:enesfrdeitpt
Link-Objekt
fromSceneIdstringerforderlich
Die Szene, in der der Navigationspunkt angezeigt wird.
toSceneIdstringerforderlich
Die Szene, zu der er führt.
yawnumbererforderlich
Horizontaler Winkel im Foto der fromScene, −180 bis 180. 0 ist die Bildmitte; negativ ist links.
pitchnumber
Vertikaler Winkel, −90 bis 90. 0 ist der Horizont.
Default:0
Um die Links der KI anzupassen statt neu anzufangen, lesen Sie links aus get_virtual_tour, bearbeiten die Liste und senden sie zurück.
Fügt einem bestehenden Rundgang 360°-Fotos hinzu. Mit sequential wird nur der neue Abschnitt verknüpft: der letzte bestehende Raum mit dem ersten neuen, dann jeder neue Raum mit dem nächsten. Bestehende Links, auch selbst gesetzte, bleiben erhalten. Kostet max(3, ⌈neue Räume ÷ 3⌉) Credits. Asynchron wie das Erstellen, und der Rundgang bleibt währenddessen online — fragen Sie get_virtual_tour ab, bis status wieder "ready" ist.
apiKeystringerforderlich
Ihr API-Schlüssel.
tourIdstringerforderlich
Die ID des Rundgangs (aus create_virtual_tour oder list_virtual_tours).
scenesarrayerforderlich
Die hinzuzufügenden 360°-Fotos, gleiches Format wie bei create_virtual_tour. Szenen per imageId müssen 360°-Fotos der Immobilie des Rundgangs sein.
linkingstring
sequential verknüpft den neuen Abschnitt; none fügt die Räume ohne Navigationspunkte hinzu.
{
"tourId": "1d7aabf8-3c2e-4b8a-9f61-0c5d2e7a4b19",
"propertyId": "196e742a-5b0d-4c9e-8a3f-7e2b1c6d9f04",
"name": "Calle Mayor 12",
"status": "processing",
"tourUrl": "https://app.pedra.ai/virtual-tour/1d7aabf8-3c2e-4b8a-9f61-0c5d2e7a4b19",
"sceneCount": 6,
"linkCount": 6,
"progress": { "stage": "queued" },
"addedScenes": [
{ "sceneId": "3e7b1a95-4c0f-4b2d-9e68-1a5d8c3f7b02", "name": "Bathroom", "source": "https://example.com/360/bathroom.jpg" },
{ "sceneId": "9f6c2d48-7a1e-4e5b-8c3d-0b4a6f9e2d17", "name": null, "source": "https://example.com/360/terrace.jpg" }
],
"creditsCost": 3,
"estimatedSeconds": 31,
"message": "Adding the scenes. The tour stays live while this runs. Poll get_virtual_tour until status is \"ready\"."
}
Einen virtuellen Rundgang löschen
POST/api/delete_virtual_tour
Löscht den Rundgang. Sein öffentlicher Link liefert ab dann 404; die 360°-Fotos bleiben in der Immobilie, sodass Sie daraus einen neuen Rundgang bauen können. Löschen geht nur über die API — es gibt dafür kein MCP-Tool.
apiKeystringerforderlich
Ihr API-Schlüssel.
tourIdstringerforderlich
Die ID des Rundgangs (aus create_virtual_tour oder list_virtual_tours).
{
"message": "Virtual tour deleted. Its 360° photos are still in the property.",
"tourId": "1d7aabf8-3c2e-4b8a-9f61-0c5d2e7a4b19"
}
Einen Upload-Link erstellen
POST/api/create_upload_link
Gibt eine Upload-Seite ohne Login für eine Immobilie zurück, 24 Stunden gültig. Schicken Sie sie an die Person mit den Fotos — Fotograf, Makler, Eigentümer. Sie öffnet sie am Handy oder Computer, zieht die Fotos hinein (bis zu 100 Dateien, JPEG, PNG oder WebP, bis zu 80 MB pro Datei; HEIC-Fotos vom iPhone funktionieren, wenn sie direkt vom iPhone hochgeladen werden) und sieht Vorschaubilder, Fortschritt und am Ende ein „Fertig". Die Dateien werden nach Dateiname sortiert, was bei 360°-Kameras der Aufnahmereihenfolge entspricht — meist auch der Laufreihenfolge.
type legt fest, was die Seite annimmt:
"any" (Standard) — normale Fotos und 360°-Fotos. 2:1-Bilder werden erkannt und automatisch als 360°-Fotos gespeichert. Für Fotos zum Bearbeiten, Einrichten oder für ein Video, oder eine Mischung.
"360" — nur 360°-Fotos; alles andere wird mit einer klaren Meldung abgelehnt. Verwenden Sie es, wenn der Link für einen virtuellen Rundgang ist.
Die Fotos werden so gespeichert wie in der Web-App: normale Fotos mit 2048 px an der langen Seite (3072 px, wenn die Datei größer als 20 MB ist), 360°-Fotos mit 4096 px Breite (6144 px über 20 MB).
So kommt auch ein Chat-Assistent an Fotos auf einem Handy: Claude kann Chat-Anhänge nicht an ein Tool übergeben, und Fotos, die noch auf dem Handy liegen, sind gar nicht im Chat. Also erstellt der Assistent einen Upload-Link, Sie laden hoch, und er macht weiter. (In ChatGPT funktionieren im Chat angehängte Fotos direkt — siehe MCP-Server.) Der Link kann nur Fotos zu dieser einen Immobilie hinzufügen — er gibt keinen weiteren Zugriff auf das Konto. Wenn der Upload fertig ist, rufen Sie list_property_images auf (type"photo" oder "360"), um URLs zum Bearbeiten oder für ein Video zu bekommen, oder create_virtual_tour mit der propertyId und ohne scenes.
Limits: 5 Upload-Links pro Tag im Free-Tarif, 50 in bezahlten Tarifen (429 upload_link_limit) — jeder Link gilt 24 Stunden, verwenden Sie also den von heute wieder, statt einen neuen zu erstellen. Jede über einen Link hochgeladene Datei zählt außerdem zum täglichen Upload-Limit.
apiKeystringerforderlich
Ihr API-Schlüssel.
propertyIdstring
Die Immobilie, in die die Fotos kommen. Weglassen, um eine neue Immobilie mit dem Namen aus name anzulegen.
namestring
Name der neuen Immobilie, z. B. die Adresse des Inserats. Wird auf der Upload-Seite angezeigt.
typestring
Was die Seite annimmt: "any" für Fotos und 360°-Fotos (2:1-Bilder werden automatisch als 360° gespeichert) oder "360" nur für 360°-Fotos — für einen virtuellen Rundgang.
{
"uploadUrl": "https://app.pedra.ai/upload/q7Ht2vXk9LmP4wRz8NcB1sYd6FgJ3eUa0KoV5iTn?lang=es",
"propertyId": "196e742a-5b0d-4c9e-8a3f-7e2b1c6d9f04",
"propertyName": "Calle Mayor 12",
"type": "360",
"expiresAt": "2026-10-01T15:26:30.687Z",
"maxFiles": 100,
"appUrl": "https://app.pedra.ai/?projectId=196e742a-5b0d-4c9e-8a3f-7e2b1c6d9f04",
"message": "Send this link to whoever has the 360° photos. It works on a phone or a computer with no login, for 24 hours. When they're done, list the property's photos (list_property_images; type "360" for 360° photos) and use them."
}
360°-Fotos hochladen
Rundgänge entstehen aus equirektangulären 360°-Fotos — den 2:1-Panoramen, die 360°-Kameras exportieren. Jedes Foto wird auf 2:1 geprüft (1,9–2,1 wird akzeptiert), darf bis zu 80 MB groß sein und wird als JPEG mit 4096 px Breite gespeichert (6144 px, wenn die Datei größer als 20 MB ist). Es gibt drei Wege, sie hochzuladen:
Öffentliche URLs, direkt — übergeben Sie sie als scenes an create_virtual_tour. Am besten, wenn die Fotos schon online sind (Ihr CDN oder Storage-Bucket). Dropbox- und Google-Drive-Freigabelinks werden automatisch in direkte Downloads umgewandelt.
add_images_to_property mit type: "360" — speichern Sie die Fotos zuerst in einer Immobilie (bis zu 10 pro Aufruf) und rufen Sie dann create_virtual_tour nur mit der propertyId auf. Es akzeptiert auch data:-URIs, sodass Sie lokale Dateien base64-kodiert senden können — eine oder wenige pro Aufruf, unter dem Anfragelimit von 50 MB.
Ein Upload-Link — wenn die Fotos auf dem Handy oder der Kamera einer Person liegen statt online. Siehe create_upload_link mit type: "360".
Lokale 360°-Dateien als data:-URIs senden, zwei pro Aufruf, und dann den Rundgang bauen:
import base64
import pathlib
import requests
API = "https://app.pedra.ai/api"
API_KEY = "YOUR_API_KEY"
def data_uri(path):
return "data:image/jpeg;base64," + base64.b64encode(path.read_bytes()).decode()
# Sorted by file name = shooting order on most 360° cameras
files = sorted(pathlib.Path("./calle-mayor-12").glob("*.jpg"))
prop = requests.post(f"{API}/create_property",
json={"apiKey": API_KEY, "name": "Calle Mayor 12"}).json()
for i in range(0, len(files), 2): # two per call keeps the body under 50 MB
res = requests.post(f"{API}/add_images_to_property", json={
"apiKey": API_KEY,
"propertyId": prop["propertyId"],
"type": "360",
"imageUrls": [data_uri(p) for p in files[i:i + 2]],
}).json()
for f in res["failed"]:
print("Skipped:", f["error"])
# No scenes: every 360° photo in the property, in upload order
tour = requests.post(f"{API}/create_virtual_tour",
json={"apiKey": API_KEY, "propertyId": prop["propertyId"]}).json()
Fehler
Fehler kommen als { "error": "...", "code": "..." } zurück (code nur wo angegeben). Siehe Fehler und Limits für das allgemeine Modell.
400 — ungültige Eingabe: ein Foto, das kein 360°-Foto ist, mehr als 50 Szenen, ein unbekannter linking-Wert. no_panoramas: Die Immobilie hat noch keine 360°-Fotos. no_new_scenes: Alle hinzugefügten Szenen sind schon im Rundgang.
402 insufficient_credits — mit creditsRequired, creditsAvailable und upgradeUrl. Es wird nichts erstellt oder berechnet.
404 — User not found (falscher API-Schlüssel), Virtual tour not found oder Property not found for this account.
409 — tour_exists: Die Immobilie hat schon einen Rundgang (dessen tourId steht in der Antwort). tour_processing: Der Rundgang wird noch gebaut — warten Sie, bis er fertig ist. tour_failed: Der Aufbau ist fehlgeschlagen — löschen Sie den Rundgang und erstellen Sie ihn neu.
429 — upload_limit: Die per URL übergebenen Fotos würden das tägliche Upload-Limit des Kontos überschreiten (30 pro Tag im Free-Tarif, 500 in bezahlten Tarifen, Reset um Mitternacht UTC); der ganze Aufruf wird abgelehnt und nichts gespeichert. upload_link_limit: Das Konto hat seine Upload-Links für heute schon erstellt.
Weiter
Erstellen Sie Rundgänge aus ChatGPT oder Claude mit dem MCP-Server, verwalten Sie die Fotos eines Rundgangs mit der Immobilien-API, oder machen Sie aus demselben Inserat ein Video.
