Langsung ke konten
← Kembali ke Panduan

Referensi API

10 menit baca

API Prewalk adalah bagian dari paket Enterprise. Dengan kunci API, perangkat lunak Anda sendiri dapat membuat tur, mengunggah adegan, memublikasikan, membaca proyek dan statistik, serta menerima webhook bertanda tangan di setiap tahap pemrosesan. Halaman ini adalah referensinya; studio dan pemutar publik tetap berfungsi seperti sebelumnya.

URL dasar dan konvensi

  • URL dasar: https://prewalk.co. Jangan gunakan app.prewalk.co: alamat itu melakukan pengalihan (308), dan sebagian besar klien HTTP membuang header Authorization saat dialihkan ke host lain.
  • Format: JSON untuk masukan dan keluaran (Content-Type: application/json), kecuali unggahan adegan, yang mengirim gambar sebagai isi permintaan mentah.
  • ID terdiri atas 12 huruf kecil dan angka, misalnya teeg8crtm0u0. Tanggal memakai format ISO 8601 dalam UTC.
  • Kesalahan selalu berbentuk sama: status HTTP dan {"error": {"code": "…", "message": "…"}}; kesalahan validasi menambahkan field. Daftar kodenya ada di akhir halaman ini.
  • Batas laju: 600 permintaan per menit per kunci. Jika melebihinya, Anda menerima 429 dengan header Retry-After (dalam detik).

Autentikasi

Buat kunci di Pengaturan → API (pemilik akun atau admin, Enterprise). Sebuah kunci milik akun, dapat dibatasi ke satu profil merek, dan memiliki hingga tiga cakupan: read, write, dan stats. Kunci lengkap hanya ditampilkan sekali; daftar hanya menampilkan awalannya. Maksimal 20 kunci per akun; kunci yang dicabut langsung berhenti berfungsi.

Authorization: Bearer pw_…

Sebuah kunci bertindak untuk satu akun. GET /api/me menjelaskan apa yang dapat dilihat kunci tersebut: akun beserta batas paketnya, profil-profil akun itu, profil tempat kunci bertindak (actor), dan kunci itu sendiri beserta cakupannya. Endpoint ini tidak pernah mengembalikan email pemilik kunci atau akun-akun lain miliknya.

Endpoint

Metode dan pathCakupanFungsi
GET /api/mereadAkun, profil, dan cakupan kunci
GET /api/toursreadMenampilkan daftar tur akun (limit ≤ 50, cursor, profileId)
GET /api/tours/{id}readSatu tur beserta adegan, hotspot, dan pengaturannya
GET /api/tours/{id}/eventsreadProgres pemrosesan sebagai aliran server-sent event
POST /api/tourswriteMembuat tur ({"title": "…"})
PATCH /api/tours/{id}writeMengubah judul, deskripsi, kategori, lokasi, tag, slug (alamat yang mudah dibaca), urutan adegan, adegan awal, nama adegan
POST /api/tours/{id}/sceneswriteMengunggah gambar 360° sebagai isi mentah
POST /api/content/{id}/visibilitywriteMemublikasikan tur atau proyek, menjadikannya hanya dengan tautan, atau melindunginya dengan kata sandi
GET /api/projectsreadMenampilkan daftar proyek akun (limit, cursor, profileId)
GET /api/projects/{id}readSatu proyek beserta tur, gambar, video, dan denahnya
GET /api/stats/{contentId}statsTayangan sebuah tur atau proyek (range dalam hari)
GET /api/stats/{contentId}/export.csvstatsData yang sama dalam CSV (table = daily, scenes, atau referrers)

Semua endpoint lain menjawab 403 api_key_forbidden jika dipanggil dengan kunci. Akun, tim, penagihan, kunci API, dan webhook dikelola di browser.

Tur

Daftar. GET /api/tours?limit=50 mengembalikan {"items": […], "next": "…", "usage": {…}}. Kirim kembali next sebagai cursor untuk halaman berikutnya; usage berisi jumlah adegan dan batas akun. Setiap item memiliki id, title, visibility, publishedAt, createdAt, updatedAt, profil, dan jumlah adegan.

Baca. GET /api/tours/{id} mengembalikan tur lengkap: title, description, category, location, tags, slug, visibility (public, link, atau password), hasPassword, publishedAt, profile, projectId, startScene, coverScene, revision, scenes sesuai urutan, hotspots, settings, audio, dan links (player adalah alamat yang dapat dibagikan, post adalah halaman publik setelah dipublikasikan).

Sebuah adegan memiliki id, name, status (queued, processing, ready, atau error), createdAt, secara opsional view (arah tampilan awal: yaw, pitch, dan fov dalam radian), north (radian; 0 adalah bagian tengah gambar, bertambah ke kanan), serta stage dan pct selama sedang diproses. Adegan yang sudah siap membawa meta berisi level tile dan root media-nya.

Buat. POST /api/tours dengan {"title": "Harbor View — Unit 4"} mengembalikan tur baru. Tanpa judul, tur diberi nama “Tur tanpa judul”.

Perbarui. PATCH /api/tours/{id} menerima kolom mana pun berikut ini dan mengembalikan tur:

  • title, description, category, location, tags (array string), slug (alamat publik, berupa huruf kecil, angka, dan tanda hubung), commentsEnabled;
  • order: array ID adegan sesuai urutan yang Anda inginkan; adegan yang tidak Anda cantumkan tetap berada setelah adegan yang Anda cantumkan;
  • startScene: ID adegan; adegan ini dipindahkan ke depan (adegan pertama adalah adegan awal);
  • coverScene: ID adegan, atau null untuk adegan awal;
  • scenes: objek dengan ID adegan sebagai kunci, berisi name, view ({"yaw", "pitch", "fov"}), dan north (derajat).

Kirim If-Match: "<revision>" dengan revision yang terakhir Anda baca agar penulisan di atas perubahan orang lain ditolak: jawabannya kemudian 409 revision_conflict dengan tur terkini di error.tour. Tanpa If-Match, penulisan terakhir yang berlaku.

Mengunggah adegan

POST /api/tours/{id}/scenes dengan file gambar sebagai isi mentah. Header:

  • Content-Type: image/jpeg, image/png, image/tiff, atau image/webp;
  • x-file-name: nama file, dalam bentuk URL-encoded (encodeURIComponent); adegan diberi nama sesuai nama file, sehingga 01-living-room.jpg menjadi “01 living room”;
  • x-pw-upload-batch dan x-pw-upload-index (opsional): saat Anda mengunggah beberapa file dari satu pilihan secara paralel, beri semuanya ID batch yang sama (huruf, angka, -, dan _, hingga 32 karakter) serta indeksnya dalam pilihan; server kemudian mempertahankan urutan itu, file mana pun yang selesai lebih dulu. Tanpa header ini, adegan ditambahkan sesuai urutan kedatangan.

Gambar yang diterima: panorama equirectangular 2:1 hingga lebar maksimal paket (8K di Gratis, 16K di Pro ke atas), atau panorama stereo top-bottom 1:1 di Pro ke atas (mata kiri di atas), hingga 1 GiB. Jawabannya berupa adegan (status: "queued"). Pemrosesan berjalan dalam beberapa tahap: adegan tampil lebih dulu (tile pratinjau), lalu tile resolusi penuh menyusul (“penajaman”), begitu pula tekstur VR di Pro ke atas; keduanya berjalan berdampingan dan mana pun bisa selesai lebih dulu. meta.pending pada adegan, aliran event, dan webhook memberi tahu Anda tahap mana yang masih berjalan.

Kesalahan: 400 unsupported_format (bukan JPG, PNG, TIFF, atau WebP), 400 unsupported_ratio (bukan 2:1, atau 1:1 top-bottom), 400 unreadable_image (file rusak), 402 plan_required (16K atau stereo pada paket yang tidak menyediakannya), 402 quota_exceeded (batas adegan akun), 413 file_too_large.

Progres pemrosesan

GET /api/tours/{id}/events adalah aliran server-sent event (text/event-stream). Event: hello saat terhubung, queue (posisi antrean adegan yang menunggu dan ringkasan tur, setiap beberapa detik selama ada proses yang berjalan), scene (status, stage, pct, atau error), dan tour (tur berubah; baca ulang tur tersebut). Untuk integrasi antarserver, sebaiknya gunakan webhook di bawah ini.

Publikasi dan visibilitas

POST /api/content/{id}/visibility berlaku untuk tur dan proyek, dan mengembalikan kontennya:

  • {"visibility": "link"}: hanya dapat dibuka lewat alamatnya (bawaan setiap tur baru);
  • {"visibility": "public", "rightsAccepted": true}: tampil di profil, di Jelajahi, dan dapat diindeks; category wajib diisi (atur dulu dengan PATCH), dan Anda menyatakan bahwa Anda berhak memublikasikan gambar-gambar tersebut. Untuk proyek, tambahkan "tourIds": [...] untuk memublikasikan tur bersama proyeknya;
  • {"visibility": "password", "password": "…"}: Pro ke atas; hilangkan password untuk mempertahankan kata sandi saat ini.

Tur di dalam proyek yang dilindungi kata sandi tidak bisa menjadi publik atau memiliki kata sandi sendiri (409 in_password_project); kata sandi proyeklah yang menjadi gerbangnya.

Proyek

Saat ini, proyek hanya dapat dibaca melalui API. GET /api/projects menampilkan daftarnya dengan id, title, slug, visibility, category, coverUrl, tourCount, imageCount, videoCount, dan tanggal; GET /api/projects/{id} menambahkan description, location, tags, urls (public dan tautan privat), tours beserta adegannya, serta images, videos, dan floorplans galeri beserta pin-nya. Buat proyek dan tambahkan media di studio.

Statistik

GET /api/stats/{contentId}?range=30 mengembalikan tayangan sebuah tur atau proyek. Data yang Anda dapatkan bergantung pada paket: total sepanjang waktu di Gratis; deret daily yang diisi nol (from, to, hingga 90 hari) di Pro; hingga 365 hari ditambah sources (halaman, sematan, langsung), devices (ponsel, desktop, headset VR), scenes, dan referrers penyemat di Office dan Enterprise. …/export.csv?range=30&table=daily memberikan tabel harian, table=scenes tayangan per adegan, dan table=referrers situs yang menyematkan. Tayangan dihitung per alamat pengunjung dan konten, sekali setiap 30 menit; tidak ada data pribadi yang disimpan.

Webhook

Tambahkan hingga lima webhook di Pengaturan → API. Kami mengirim POST bertanda tangan dengan isi JSON:

{"eventId": "evt_…", "eventType": "scene.ready", "occurredAt": "2026-10-22T09:12:03.000Z",
 "data": {"tourId": "…", "sceneId": "…", "status": "ready", "pending": ["refine", "vr"]}}
EventKapanData
scene.readyAdegan sudah tampil (tile pratinjau)pending: tahap yang masih berjalan—refine (tile resolusi penuh) dan vr (tekstur headset); [] jika pratinjau sudah final
scene.sharpenedTile resolusi penuh sudah terpasangstage: "refine", ok (false jika tahap ini dibatalkan dan adegan tetap pada kualitas pratinjau), pending
scene.vr_readyTekstur VR sudah terpasangstage: "vr", ok, pending
scene.failedPemrosesan gagal secara permanenerror beserta alasannya
pingTombol “Kirim tes”kosong

Header: Prewalk-Signature: ts=<unix seconds>;h1=<hex>, dengan h1 adalah HMAC-SHA256 dari ts + ":" + body menggunakan secret webhook Anda (dihitung atas byte persis yang Anda terima), ditambah Prewalk-Event-Id dan Prewalk-Event-Type. Selama rotasi secret berlangsung, header ini membawa dua nilai h1 (ts=…;h1=<new>;h1=<old>) sampai secret sebelumnya kedaluwarsa: terima pengiriman jika salah satunya lolos verifikasi. Verifikasi tanda tangan, tolak timestamp yang lebih lama dari beberapa menit, dan hapus duplikat berdasarkan eventId: pengiriman diulang sampai endpoint Anda menjawab 2xx (sepuluh percobaan, 30 detik lalu terus berlipat ganda, total sekitar empat jam), dan isi yang dikirim ulang identik hingga ke tingkat byte. Setelah 20 pengiriman gagal berturut-turut, webhook dinonaktifkan dan pemilik akun menerima email. Endpoint harus berupa https di alamat publik; pengalihan tidak diikuti. Secret dapat dirotasi; secret sebelumnya tetap berlaku selama 24 jam.

Contoh langkah demi langkah

# 1. create a tour
curl -s https://prewalk.co/api/tours -H "Authorization: Bearer $PW_KEY" \
  -H "Content-Type: application/json" -d '{"title":"Harbor View — Unit 4"}'

# 2. upload two scenes in order
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. set a category and publish
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. views of the last 30 days
curl -s "https://prewalk.co/api/stats/$TOUR?range=30" -H "Authorization: Bearer $PW_KEY"

Penyematan

Penyematan tidak memerlukan kunci: setiap tur memiliki https://prewalk.co/embed/{id}, dan embed.js mengatur ukuran bingkai serta membukanya dalam layar penuh di halaman Anda. Situs web mana yang boleh menampilkan sematan Anda diatur di Pengaturan → Identitas merek. Panduan penyematan berisi detailnya.

Kode kesalahan

StatusKodeArti
400invalid_requestSebuah kolom tidak ada atau tidak valid; field menyebutkan namanya
400unsupported_format, unsupported_ratio, unreadable_image, rights_required, category_required, project_needs_contentPrasyarat unggah atau publikasi (proyek memerlukan tur publik, gambar, atau video)
401unauthorized, invalid_api_keyTidak ada kunci sama sekali, atau kunci salah format atau sudah dicabut
402plan_required, quota_exceededPaket tidak menyediakan fitur tersebut, atau batas telah tercapai (feature atau limit menyebutkan yang mana)
403api_key_forbidden, api_scope_missingEndpoint tidak terbuka untuk kunci, atau kunci tidak memiliki cakupan yang diperlukan
404not_foundBukan milik Anda, sudah dihapus, atau ID tidak ada
409revision_conflict, slug_taken, in_password_projectPengeditan bersamaan (tur terkini disertakan), alamat sudah dipakai, aturan kata sandi proyek
413file_too_largeMelebihi batas ukuran
429rate_limitedTerlalu banyak permintaan; tunggu Retry-After detik
503maintenancePrewalk sedang diperbarui; coba lagi setelah satu menit

Perubahan

  • 10 Nov 2026: proyek kini bisa dipublikasikan atau dilindungi kata sandi hanya dengan gambar atau video. Proyek yang tidak punya apa pun untuk ditampilkan menjawab 400 project_needs_content, baik publik maupun dengan kata sandi; kode ini menggantikan project_needs_public_tour dan project_needs_tour, yang tidak lagi dikirim. GET /api/projects menambahkan videoCount.
  • 22 Okt 2026: scene.ready membawa pending; event baru scene.sharpened dan scene.vr_ready; header urutan unggah x-pw-upload-batch dan x-pw-upload-index; GET /api/me dengan kunci hanya menjelaskan akun milik kunci tersebut.

Ada pertanyaan atau endpoint yang belum tersedia? Tulis ke hello@prewalk.co.

Bagikan: Bagikan di X LinkedIn WhatsApp

  • Apa itu foto 360°?

    Apa itu foto 360°? Gambar 2:1 yang menampilkan semua arah dari satu titik (360° × 180°). Cara membuat dan melihatnya, serta bedanya dengan panorama.