Ugrás a tartalomhoz
← Vissza az útmutatókhoz

API-referencia

11 perc olvasás

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 az app.prewalk.co címet: átirányít (308), és a legtöbb HTTP-kliens elhagyja az Authorization fejlé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 a field mező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 429 választ kap egy Retry-After fejlé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 útvonalJogosultságMit csinál
GET /api/mereadA kulcs fiókja, profiljai és jogosultságai
GET /api/toursreadA fiók sétáinak listája (limit ≤ 50, cursor, profileId)
GET /api/tours/{id}readEgy séta a jeleneteivel, hotspotjaival és beállításaival
GET /api/tours/{id}/eventsreadA feldolgozás állapota szerver által küldött eseményfolyamként
POST /api/tourswriteSéta létrehozása ({"title": "…"})
PATCH /api/tours/{id}writeA 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}/sceneswrite360°-os kép feltöltése nyers törzsként
POST /api/content/{id}/visibilitywriteSéta vagy projekt közzététele, csak linkkel elérhetővé tétele vagy jelszavas védelme
GET /api/projectsreadA fiók projektjeinek listája (limit, cursor, profileId)
GET /api/projects/{id}readEgy projekt a sétáival, képeivel, videóival és alaprajzaival
GET /api/stats/{contentId}statsEgy séta vagy projekt megtekintései (range napokban)
GET /api/stats/{contentId}/export.csvstatsUgyanez 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ó, vagy null a kezdőjelenethez;
  • scenes: jelenetazonosítókkal kulcsolt objektum name, view ({"yaw", "pitch", "fov"}) és north (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/tiff vagy image/webp;
  • x-file-name: a fájlnév URL-kódolva (encodeURIComponent); a jelenet erről kapja a nevét, így a 01-living-room.jpg neve „01 living room” lesz;
  • x-pw-upload-batch és x-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ő; category megadása kötelező (előbb állítsa be PATCH ké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 a password mező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ényMikorAdatok
scene.readyA 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.sharpenedA teljes felbontású csempék a helyükön vannakstage: "refine", ok (false, ha a lépés elmaradt, és a jelenet előnézeti minőségben marad), pending
scene.vr_readyA VR-textúrák a helyükön vannakstage: "vr", ok, pending
scene.failedA feldolgozás véglegesen sikertelenerror az okkal
pingA „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

ÁllapotKódJelentés
400invalid_requestEgy mező hiányzik vagy érvénytelen; a field megnevezi
400unsupported_format, unsupported_ratio, unreadable_image, rights_required, category_required, project_needs_contentA feltöltés vagy a közzététel előfeltételei (a projekthez nyilvános séta, kép vagy videó kell)
401unauthorized, invalid_api_keyNincs kulcs, vagy a kulcs hibás formátumú vagy visszavont
402plan_required, quota_exceededA csomag nem tartalmazza a funkciót, vagy elérte a korlátot (a feature vagy a limit megmondja, melyiket)
403api_key_forbidden, api_scope_missingA végpont nem érhető el kulccsal, vagy a kulcsnak nincs meg a jogosultsága
404not_foundNem az Öné, törölték, vagy nincs ilyen azonosító
409revision_conflict, slug_taken, in_password_projectEgyidejű szerkesztés (az aktuális séta a válaszban van), a cím már foglalt, projektjelszó-szabály
413file_too_largeMeghaladja a méretkorlátot
429rate_limitedTúl sok kérés; várjon Retry-After másodpercet
503maintenanceA 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_content választ ad, nyilvánosan és jelszóval egyaránt; ez a kód felváltja a project_needs_public_tour és a project_needs_tour kódot, amelyeket már nem küldünk. A GET /api/projects válasza kiegészül a videoCount mezővel.
  • 2026. október 22.: a scene.ready tartalmazza a pending mezőt; új események: scene.sharpened és scene.vr_ready; feltöltési sorrendet megadó fejlécek: x-pw-upload-batch és x-pw-upload-index; a GET /api/me kulccsal 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

  • Panoee-alternatívák: mikor érdemes váltani?

    Panoee-alternatívát keres? Miben erős a Panoee, miért váltanak róla, négy alternatíva árakkal, és hogyan költöztetheti át a sétáit (2026. november).

  • Mi az a 360 fokos fotó?

    Mi az a 360 fokos fotó? Egy pontból minden irányt mutató, 2:1 arányú kép (360° × 180°). Hogyan készül, hogyan nézhető meg, és miben más, mint a panoráma?