API-referencia
A Prewalk API az Enterprise csomag része. Egy API-kulccsal saját szoftvere sétákat hozhat létre, jeleneteket tölthet fel, közzétehet, projekteket és statisztikákat olvashat, és minden feldolgozási lépésnél aláírt webhookot kaphat. Ez az oldal a referencia; a stúdió és a nyilvános lejátszó ugyanúgy működik tovább, mint eddig.
Alap-URL és konvenciók
- Alap-URL:
https://prewalk.co. Ne használja azapp.prewalk.cocímet: átirányít (308), és a legtöbb HTTP-kliens elhagyja azAuthorizationfejlécet, ha másik hosztra irányítják át. - Formátum: JSON be és ki (
Content-Type: application/json), kivéve a jelenetfeltöltést, amely a képet nyers kéréstörzsként küldi. - Az azonosítók 12 kisbetűből és számjegyből állnak, például
teeg8crtm0u0. A dátumok ISO 8601 formátumúak, UTC szerint. - A hibák mindig egyformán néznek ki: egy HTTP-állapotkód és
{"error": {"code": "…", "message": "…"}}; az érvényesítési hibák ehhez afieldmezőt is hozzáadják. A kódok listája az oldal végén található. - Kéréskorlát: kulcsonként percenként 600 kérés. Fölötte
429választ kap egyRetry-Afterfejléccel (másodpercben).
Hitelesítés
Kulcsot a Beállítások → API menüpontban hozhat létre (a fiók tulajdonosa vagy adminisztrátora, Enterprise csomagban). A kulcs a fiókhoz tartozik, egyetlen márkaprofilra korlátozható, és legfeljebb három jogosultsága lehet: read, write és stats. A teljes kulcs csak egyszer jelenik meg; a lista csak az előtagját mutatja. Fiókonként legfeljebb 20 kulcs lehet; a visszavont kulcs azonnal érvényét veszti.
Authorization: Bearer pw_…
Egy kulcs egy fiók nevében jár el. A GET /api/me leírja, mit lát a kulcs: a fiókot és a csomagja korlátait, a fiók profiljait, azt a profilt, amelynek nevében a kulcs eljár (actor), valamint magát a kulcsot a jogosultságaival. A kulcs tulajdonosának e-mail-címét és más fiókjait soha nem adja vissza.
Végpontok
| Metódus és útvonal | Jogosultság | Mit csinál |
|---|---|---|
GET /api/me | read | A kulcs fiókja, profiljai és jogosultságai |
GET /api/tours | read | A fiók sétáinak listája (limit ≤ 50, cursor, profileId) |
GET /api/tours/{id} | read | Egy séta a jeleneteivel, hotspotjaival és beállításaival |
GET /api/tours/{id}/events | read | A feldolgozás állapota szerver által küldött eseményfolyamként |
POST /api/tours | write | Séta létrehozása ({"title": "…"}) |
PATCH /api/tours/{id} | write | A cím, a leírás, a kategória, a helyszín, a címkék, a slug (az olvasható cím), a jelenetsorrend, a kezdőjelenet és a jelenetnevek módosítása |
POST /api/tours/{id}/scenes | write | 360°-os kép feltöltése nyers törzsként |
POST /api/content/{id}/visibility | write | Séta vagy projekt közzététele, csak linkkel elérhetővé tétele vagy jelszavas védelme |
GET /api/projects | read | A fiók projektjeinek listája (limit, cursor, profileId) |
GET /api/projects/{id} | read | Egy projekt a sétáival, képeivel, videóival és alaprajzaival |
GET /api/stats/{contentId} | stats | Egy séta vagy projekt megtekintései (range napokban) |
GET /api/stats/{contentId}/export.csv | stats | Ugyanez CSV-ként (table = daily, scenes vagy referrers) |
Minden más végpont 403 api_key_forbidden választ ad, ha kulccsal hívják. A fiókot, a csapatot, a számlázást, az API-kulcsokat és a webhookokat a böngészőben kezelheti.
Séták
Lista. A GET /api/tours?limit=50 válasza {"items": […], "next": "…", "usage": {…}}. A következő oldalhoz küldje vissza a next értékét cursor-ként; a usage a fiók jelenetszámát és korlátait tartalmazza. Minden elemben szerepel az id, a title, a visibility, a publishedAt, a createdAt, az updatedAt, a profil és a jelenetek száma.
Olvasás. A GET /api/tours/{id} a teljes sétát adja vissza: title, description, category, location, tags, slug, visibility (public, link vagy password), hasPassword, publishedAt, profile, projectId, startScene, coverScene, revision, a scenes sorrendben, hotspots, settings, audio és links (a player a megosztható cím, a post a nyilvános oldal, ha a séta közzé van téve).
Egy jelenet mezői: id, name, status (queued, processing, ready vagy error), createdAt, opcionálisan view (a kezdőirány: yaw, pitch és fov radiánban), north (radiánban; a 0 a kép közepe, jobbra haladva nő), feldolgozás közben pedig stage és pct. Egy kész jelenet meta mezője tartalmazza a csempeszinteket és a média gyökerét.
Létrehozás. A POST /api/tours a {"title": "Harbor View — Unit 4"} törzzsel az új sétát adja vissza. Cím nélkül a neve „Névtelen séta” lesz.
Módosítás. A PATCH /api/tours/{id} az alábbi mezők bármelyikét fogadja, és a sétát adja vissza:
title,description,category,location,tags(karakterláncok tömbje),slug(a nyilvános cím: kisbetűk, számjegyek és kötőjelek),commentsEnabled;order: jelenetazonosítók tömbje a kívánt sorrendben; a kihagyott jelenetek megtartják a helyüket a felsoroltak után;startScene: egy jelenetazonosító; a jelenet az első helyre kerül (az első jelenet a kezdőjelenet);coverScene: egy jelenetazonosító, vagynulla kezdőjelenethez;scenes: jelenetazonosítókkal kulcsolt objektumname,view({"yaw", "pitch", "fov"}) ésnorth(fokban) mezőkkel.
Küldje el az If-Match: "<revision>" fejlécet az utoljára olvasott revision értékkel, ha el akarja kerülni, hogy felülírja valaki más módosítását: ilyenkor a válasz 409 revision_conflict, az aktuális sétával az error.tour mezőben. If-Match nélkül az utolsó mentés érvényesül.
Jelenetek feltöltése
POST /api/tours/{id}/scenes a képfájllal mint nyers törzzsel. Fejlécek:
Content-Type:image/jpeg,image/png,image/tiffvagyimage/webp;x-file-name: a fájlnév URL-kódolva (encodeURIComponent); a jelenet erről kapja a nevét, így a01-living-room.jpgneve „01 living room” lesz;x-pw-upload-batchésx-pw-upload-index(opcionális): ha egy kijelölés több fájlját párhuzamosan tölti fel, adja meg mindegyiknek ugyanazt a kötegazonosítót (betűk, számjegyek,-és_, legfeljebb 32 karakter) és a kijelölésen belüli sorszámát; a szerver ekkor megtartja ezt a sorrendet, függetlenül attól, melyik fájl végez előbb. Ezek nélkül a jelenetek a beérkezés sorrendjében kerülnek a végére.
Elfogadott képek: 2:1 arányú ekvirektanguláris panorámák a csomag szerinti szélességig (az Ingyenes csomagban 8K, a Pro csomagtól felfelé 16K), vagy a Pro csomagtól felfelé 1:1 arányú, fent-lent elrendezésű sztereó panorámák (fent a bal szem képe), legfeljebb 1 GiB méretig. A válasz maga a jelenet (status: "queued"). A feldolgozás lépésekben zajlik: először a jelenet láthatóvá válik (előnézeti csempék), majd megérkeznek a teljes felbontású csempék („élesítés”), a Pro csomagtól felfelé pedig a VR-textúrák is; ez a kettő párhuzamosan fut, és bármelyik végezhet előbb. A jelenet meta.pending mezőjéből, az eseményfolyamból és a webhookokból tudhatja meg, mely lépések futnak még.
Hibák: 400 unsupported_format (nem JPG, PNG, TIFF vagy WebP), 400 unsupported_ratio (nem 2:1, illetve nem 1:1 fent-lent), 400 unreadable_image (sérült fájl), 402 plan_required (16K vagy sztereó olyan csomagban, amely nem tartalmazza), 402 quota_exceeded (a fiók jelenetkorlátja), 413 file_too_large.
A feldolgozás állapota
A GET /api/tours/{id}/events egy szerver által küldött eseményfolyam (text/event-stream). Események: hello csatlakozáskor, queue (a várakozó jelenetek helye a sorban és a séta összefoglalója, néhány másodpercenként, amíg valami fut), scene (status, stage, pct vagy error) és tour (a séta megváltozott; olvassa be újra). Szerverek közötti integrációhoz inkább az alábbi webhookokat használja.
Közzététel és láthatóság
A POST /api/content/{id}/visibility sétákhoz és projektekhez is működik, és a tartalmat adja vissza:
{"visibility": "link"}– csak a címén érhető el (minden új séta alapértelmezése);{"visibility": "public", "rightsAccepted": true}– megjelenik a profilon és a Felfedezés oldalon, és indexelhető;categorymegadása kötelező (előbb állítsa bePATCHkéréssel), és Ön megerősíti, hogy jogosult a képek közzétételére. Projekt esetén adja hozzá a"tourIds": [...]mezőt, hogy a sétákat a projekttel együtt tegye közzé;{"visibility": "password", "password": "…"}– a Pro csomagtól felfelé; ha apasswordmezőt kihagyja, a jelenlegi jelszó megmarad.
Jelszóval védett projektben lévő séta nem lehet nyilvános, és nem kaphat saját jelszót (409 in_password_project); a hozzáférést a projekt jelszava védi.
Projektek
A projektek az API-n keresztül jelenleg csak olvashatók. A GET /api/projects listázza őket az id, title, slug, visibility, category, coverUrl, tourCount, imageCount, videoCount mezőkkel és a dátumokkal; a GET /api/projects/{id} ezekhez hozzáadja a description, location, tags, urls (public és a privát link) mezőket, a tours sétákat a jeleneteikkel, valamint a galéria images, videos és floorplans elemeit a jelölőkkel. A projekteket a stúdióban hozhatja létre, és ott adhat hozzájuk médiát.
Statisztikák
A GET /api/stats/{contentId}?range=30 egy séta vagy projekt megtekintéseit adja vissza. Hogy mit kap, az a csomagtól függ: az Ingyenes csomagban a teljes időszakra vonatkozó total értéket; a Pro csomagban nullákkal kitöltött daily sorozatot (from, to, legfeljebb 90 nap); az Office és az Enterprise csomagban legfeljebb 365 napot, továbbá sources (oldal, beágyazás, közvetlen), devices (telefon, asztali gép, VR-szemüveg), scenes és a beágyazó referrers adatokat. Az …/export.csv?range=30&table=daily a napi táblázatot adja, a table=scenes a jelenetenkénti megtekintéseket, a table=referrers pedig a beágyazó oldalakat. A megtekintéseket látogatói címenként és tartalmanként számoljuk, 30 percenként egyszer; személyes adatot nem tárolunk.
Webhookok
Legfeljebb öt webhookot adhat hozzá a Beállítások → API menüpontban. Aláírt POST kérést küldünk JSON-törzzsel:
{"eventId": "evt_…", "eventType": "scene.ready", "occurredAt": "2026-10-22T09:12:03.000Z",
"data": {"tourId": "…", "sceneId": "…", "status": "ready", "pending": ["refine", "vr"]}}
| Esemény | Mikor | Adatok |
|---|---|---|
scene.ready | A jelenet látható (előnézeti csempék) | pending: a még futó lépések – refine (teljes felbontású csempék) és vr (a szemüveg textúrái); [], ha az előnézet a végleges |
scene.sharpened | A teljes felbontású csempék a helyükön vannak | stage: "refine", ok (false, ha a lépés elmaradt, és a jelenet előnézeti minőségben marad), pending |
scene.vr_ready | A VR-textúrák a helyükön vannak | stage: "vr", ok, pending |
scene.failed | A feldolgozás véglegesen sikertelen | error az okkal |
ping | A „Teszt küldése” gomb | üres |
Fejlécek: Prewalk-Signature: ts=<unix seconds>;h1=<hex>, ahol a h1 a ts + ":" + body HMAC-SHA256 értéke az Ön webhooktitkával (pontosan a kapott bájtokon számolva), továbbá Prewalk-Event-Id és Prewalk-Event-Type. Titokcsere közben a fejléc két h1 értéket tartalmaz (ts=…;h1=<new>;h1=<old>), amíg az előző titok le nem jár: fogadja el a kézbesítést, ha bármelyik ellenőrzése sikeres. Ellenőrizze az aláírást, utasítsa el a néhány percnél régebbi időbélyeget, és szűrje ki az ismétlődéseket az eventId alapján: a kézbesítést addig ismételjük, amíg a végpontja 2xx kóddal nem válaszol (tíz kísérlet, 30 mp-cel kezdve, majd duplázva, összesen kb. négy órán át), és az újraküldött törzs bájtra azonos. 20 egymást követő sikertelen kézbesítés után a webhookot kikapcsoljuk, és a fiók tulajdonosa e-mailt kap. A végpontoknak nyilvános címen, https protokollon kell elérhetőnek lenniük; az átirányításokat nem követjük. A titok lecserélhető; az előző 24 órán át érvényes marad.
Egy teljes példa
# 1. séta létrehozása
curl -s https://prewalk.co/api/tours -H "Authorization: Bearer $PW_KEY" \
-H "Content-Type: application/json" -d '{"title":"Harbor View — Unit 4"}'
# 2. két jelenet feltöltése sorrendben
curl -s https://prewalk.co/api/tours/$TOUR/scenes -H "Authorization: Bearer $PW_KEY" \
-H "Content-Type: image/jpeg" -H "x-file-name: 01-living-room.jpg" \
-H "x-pw-upload-batch: sel-1" -H "x-pw-upload-index: 0" --data-binary @01-living-room.jpg
curl -s https://prewalk.co/api/tours/$TOUR/scenes -H "Authorization: Bearer $PW_KEY" \
-H "Content-Type: image/jpeg" -H "x-file-name: 02-kitchen.jpg" \
-H "x-pw-upload-batch: sel-1" -H "x-pw-upload-index: 1" --data-binary @02-kitchen.jpg
# 3. kategória beállítása és közzététel
curl -s -X PATCH https://prewalk.co/api/tours/$TOUR -H "Authorization: Bearer $PW_KEY" \
-H "Content-Type: application/json" -d '{"category":"real-estate","location":"Istanbul"}'
curl -s https://prewalk.co/api/content/$TOUR/visibility -H "Authorization: Bearer $PW_KEY" \
-H "Content-Type: application/json" -d '{"visibility":"public","rightsAccepted":true}'
# 4. az elmúlt 30 nap megtekintései
curl -s "https://prewalk.co/api/stats/$TOUR?range=30" -H "Authorization: Bearer $PW_KEY"
Beágyazás
A beágyazáshoz nem kell kulcs: minden sétának van https://prewalk.co/embed/{id} címe, az embed.js pedig méretezi a keretet, és teljes képernyőn nyitja meg az Ön oldalán. Azt, hogy mely weboldalak jeleníthetik meg a beágyazásait, a Beállítások → Arculat menüpontban adhatja meg. A részleteket a beágyazási útmutató tartalmazza.
Hibakódok
| Állapot | Kód | Jelentés |
|---|---|---|
| 400 | invalid_request | Egy mező hiányzik vagy érvénytelen; a field megnevezi |
| 400 | unsupported_format, unsupported_ratio, unreadable_image, rights_required, category_required, project_needs_content | A feltöltés vagy a közzététel előfeltételei (a projekthez nyilvános séta, kép vagy videó kell) |
| 401 | unauthorized, invalid_api_key | Nincs kulcs, vagy a kulcs hibás formátumú vagy visszavont |
| 402 | plan_required, quota_exceeded | A csomag nem tartalmazza a funkciót, vagy elérte a korlátot (a feature vagy a limit megmondja, melyiket) |
| 403 | api_key_forbidden, api_scope_missing | A végpont nem érhető el kulccsal, vagy a kulcsnak nincs meg a jogosultsága |
| 404 | not_found | Nem az Öné, törölték, vagy nincs ilyen azonosító |
| 409 | revision_conflict, slug_taken, in_password_project | Egyidejű szerkesztés (az aktuális séta a válaszban van), a cím már foglalt, projektjelszó-szabály |
| 413 | file_too_large | Meghaladja a méretkorlátot |
| 429 | rate_limited | Túl sok kérés; várjon Retry-After másodpercet |
| 503 | maintenance | A Prewalk frissítés alatt áll; egy perc múlva próbálja újra |
Változások
- 2026. november 10.: egy projekt csak képekkel vagy videókkal is közzétehető vagy jelszóval védhető. Az a projekt, amelyben nincs mit megjeleníteni,
400 project_needs_contentválaszt ad, nyilvánosan és jelszóval egyaránt; ez a kód felváltja aproject_needs_public_tourés aproject_needs_tourkódot, amelyeket már nem küldünk. AGET /api/projectsválasza kiegészül avideoCountmezővel. - 2026. október 22.: a
scene.readytartalmazza apendingmezőt; új események:scene.sharpenedésscene.vr_ready; feltöltési sorrendet megadó fejlécek:x-pw-upload-batchésx-pw-upload-index; aGET /api/mekulccsal hívva csak a kulcs fiókját írja le.
Kérdése van, vagy hiányzik egy végpont? Írjon nekünk: hello@prewalk.co.
Megosztás: Megosztás X-en LinkedIn WhatsApp



