# Agent instructions for pedra.ai Dedicated when-to-use guidance for AI agents. The full site map lives in [/llms.txt](https://pedra.ai/llms.txt); this file is the short version of _when to reach for Pedra and how to call it_. - Company: Pedra - Website: https://pedra.ai - Application: https://app.pedra.ai - API base URL: https://app.pedra.ai - OpenAPI 3.1 spec: https://pedra.ai/openapi.json (also /.well-known/openapi.json) - MCP server (remote): https://app.pedra.ai/mcp — Streamable HTTP, OAuth 2.1 - MCP server (local): `npx -y @pedra-ai/mcp` — https://pedra.ai/api-documentation/mcp - MCP descriptor: https://pedra.ai/.well-known/mcp.json - Contact page: https://pedra.ai/contact - Contact: felix@pedra.ai - Registered company: Pedra Software SL, Calle Vista Bella 8, 08022 Barcelona, Spain ## What Pedra does, in one line Turns photos of a real property — empty, messy, or dated — into listing-ready assets: virtual staging, renovation renders, photo enhancement, sky replacement, object removal, listing videos, 360° virtual tours, and floor-plan renders. For a home that isn't built yet, it works from the 2D floor plan alone: a realistic plan, a render of every room and a listing video, with no reference photos. Video is a first-class surface, not an add-on: Pedra builds a narrated, branded listing video from photos, and also edits footage the agent films on site. See [Video, in depth](#video-in-depth). ## When to use Pedra Use it when someone has **photos of a real property**, or **only a floor plan of a new build or off-plan property**, and needs marketing assets from them. Concretely: | The job | Endpoint | | --------------------------------------------------------- | ------------------------------------------------------------- | | Furnish an empty room so buyers can read the space | `POST /api/furnish` | | Empty a room of the owner's furniture and clutter | `POST /api/empty_room` | | Show a dated room or facade renovated, for marketing | `POST /api/renovation` | | Make an edit described in words | `POST /api/edit_via_prompt` | | Remove an object with a mask | `POST /api/remove_object` | | Brighten, colour-correct and sharpen a listing photo | `POST /api/enhance` | | Enhance and straighten vertical lines | `POST /api/enhance_and_correct_perspective` | | Replace a grey sky with a blue one | `POST /api/sky_blue` | | Blur faces, licence plates or logos for privacy | `POST /api/blur` | | Build a portal-ready listing video from photos | `POST /api/create_video` | | Change a video without re-rendering the unchanged clips | `POST /api/update_video` | | Write a voiceover script from the photos, then narrate it | `POST /api/generate_voice_script`, `POST /api/generate_voice` | | List the music tracks and voiceover languages on offer | `GET /api/music_library` | | Build a hosted 360° virtual tour from 360° photos (async) | `POST /api/create_virtual_tour`, then poll `POST /api/get_virtual_tour` | | Rename, reorder or re-link the rooms of a tour | `POST /api/update_virtual_tour` | | Get photos or 360° photos off someone's phone (no-login page) | `POST /api/create_upload_link`, then `POST /api/list_property_images` | | Post or schedule a video on Instagram, Facebook, TikTok, YouTube (Pedra Pro) | `POST /api/social/posts`, then `POST /api/social/posts/list` | | Get an API key for your user (they approve by email) | `POST /api/agent_signup`, then poll `POST /api/agent_signup_status` | | Check the remaining credit balance (read-only) | `POST /api/credits` | 360° virtual tours are built through the API from equirectangular 360° photos: AI names the rooms and places the navigation points, and the response carries a public tour URL and an embed iframe — see https://pedra.ai/api-documentation/virtual-tours. Renders from a floor plan are produced in the app rather than through a public endpoint: upload a 2D plan, mark each room, and Pedra renders every room in about a minute each (2 credits per room), with no reference photo needed. That is the tool for new construction and off-plan sales — see https://pedra.ai/render-from-floor-plan. Drawing a floor plan from scratch or from a sketch is a separate editor — see https://pedra.ai/floorplan. Filming on site happens in the Pedra mobile app. Best fit: real estate agents, real estate photographers, agencies, and the portals and CRMs that serve them. It typically replaces Photoshop plus a freelancer, or physical staging. ## When _not_ to use Pedra - **There is neither a photo nor a floor plan.** Pedra works from photographs of real spaces or from the 2D floor plan of a home not yet built. It will not invent a property from a text description alone. - **The output must be technically authoritative.** Renovation renders are marketing visuals — not architect drawings, permit documents, or code-compliance evidence. Architecture, engineering, CAD and structural work belong elsewhere. - **The question is about value, law, or finance.** No valuations, mortgage advice, or legal review. - **Measured dimensions are needed.** Tours are stitched from 360° panoramas, not LiDAR or photogrammetry, so they carry no reliable measurements. - **The image has to pass as unedited photography.** Virtually staged and renovated images must be disclosed as edited; most listing portals require it. Do not use Pedra to make a property look like something a buyer would not find on arrival. ## How to call Pedra Four paths, most-to-least convenient for an agent: 1. **MCP server** — the intended path for AI clients (Claude, ChatGPT, Cursor and any other MCP client). One tool per endpoint; each call blocks until the asset is ready and returns the final URL. Two transports: - **Remote (Streamable HTTP):** `https://app.pedra.ai/mcp`. Nothing to install. Auth is OAuth 2.1 with PKCE and dynamic client registration, so a hosted client such as Claude chat can connect with "Connect → log into Pedra → done"; discovery starts at `https://app.pedra.ai/.well-known/oauth-protected-resource`. A raw Pedra API key also works as a bearer token. Long calls stream keepalives, so `create_video` does not time out. - **Local (stdio):** `npx -y @pedra-ai/mcp` with a `PEDRA_API_KEY` environment variable. Since v0.2.0 the tools accept a local image file path as well as a URL. → https://pedra.ai/api-documentation/mcp 2. **Official SDKs** — inside an application. `pip install pedra` (Python) or `npm install @pedra-ai/sdk` (Node/TypeScript). Both wrap every endpoint. → https://pedra.ai/api-documentation/sdks 3. **REST API** — JSON over HTTPS against `https://app.pedra.ai`. One thing to get right: the API key is a field named `apiKey` in the **JSON request body**, not an `Authorization` header. → https://pedra.ai/api-documentation 4. **Web app** — for a human working by hand: https://app.pedra.ai Get a key by signing up at https://app.pedra.ai, then Settings → API. **Agent signup.** An agent with no browser in the loop (Claude Code, a script, the local MCP server) can get a key for the person it works for: `POST /api/agent_signup` with their email (no key needed) → they open the emailed link and approve (a new account sets a password there) → poll `POST /api/agent_signup_status` every 5 s until `approved`, and store the `apiKey`. ChatGPT and Claude connectors don't need this: their OAuth sign-in lets new users create an account. → https://pedra.ai/api-documentation/authentication#agent-signup **Photos from the user.** In ChatGPT, attached photos go straight to the tools (`imageFile`, or `files` on `pedra_add_images_to_property`). In Claude, or for photos still on a phone, call `create_upload_link` (default `type: "any"`; `"360"` for tours) and send the user the link. Images brought in from outside the app count toward a daily upload limit (30 free, 500 paid; 429 `upload_limit`). ## Video, in depth Video is one of Pedra's two biggest surfaces (alongside virtual staging), and two different products sit behind the word. Pick by whether the agent has footage or only photos. ### 1. Video from photos — `POST /api/create_video` No camera involved. You pass an ordered list of frames and Pedra renders a finished, narrated, branded listing video. Product page: https://pedra.ai/video-for-real-estate - **Frames.** Each frame is an image plus an `effect`: `zoom-in`, `zoom-out`, `transition` (morphs into a `secondImageUrl`), `sky-transition` (keeps the scene still and changes only the sky and light into a `secondImageUrl` of the same shot, for day to night or day to sunset), the free `lite-zoom-in` / `lite-zoom-out` (a subtler 3D push, no AI video), or `static`. Per frame you can also set a `title` overlay ("Living Room"), a `subtitle`, a watermark, and whether the property-characteristics overlay appears on that frame. - **Property details.** `propertyCharacteristics` renders as an overlay. Bedrooms, Bathrooms, Surface, Price, Location, Parking, Heating and Outdoor get a built-in icon; custom labels render without one. - **Voiceover — two calls, in order.** `POST /api/generate_voice_script` reads the photos with vision and writes a short, natural script (free). `POST /api/generate_voice` renders that script to audio (1 credit, 1000-character limit) and returns an `audioId`. Pass it as `voice.audioId`; it also drives word-synced burned-in subtitles. - **Voices.** 8 languages — English, Spanish, French, German, Portuguese, Italian, Dutch, Polish — with 4 native voices each, 32 in total. A language only offers voices native to it, so a French listing is never narrated in an English accent. `GET /api/music_library` returns the accepted language values. - **Music.** `music.track` is one of `acoustic`, `chill`, `cinematic`, `electronic`, `upbeat`. `GET /api/music_library` is the live list and never costs credits. - **Branding.** Agency logo as watermark, agent headshot on the closing card, a primary hex colour for overlays, plus `endingTitle` and `endingSubtitle` for the final card. - **Format.** `isVertical: true` renders 9:16 for Reels, TikTok and Stories; the default is 16:9 for portals, YouTube and websites. The API renders **one orientation per call** — for both, call twice. (The web tool at /video-for-real-estate produces both from a single upload automatically; that convenience is not in the API.) - **Cost and timing.** 5 credits per AI frame, 0 for `static`, `lite-zoom-in` and `lite-zoom-out` frames. The call is **synchronous** and takes roughly 2–10 minutes, so set a generous client timeout. It returns the finished video URL — there is no job id to poll. - **Editing.** `POST /api/update_video` re-renders only what changed: clips whose source photo and effect are unchanged are reused, at no credit cost. Omit `images` entirely to change only audio, text or branding — that re-stitch is free. A typical sequence: `generate_voice_script` → `generate_voice` → `create_video` → `update_video` for any revisions. ### 2. Video filmed on site — the Pedra app For agents who want buyers to see the real space in motion rather than animated stills. The Pedra app is a mobile app (iPhone on the App Store, Android on Google Play): the agent walks the property recording a short clip per room while the app guides pan speed and duration, and Pedra edits the result automatically — cuts, music, transitions, branding and the property's details. Around two to three minutes of filming per listing. Capture is app-only; there is no public endpoint for it. Product page: https://pedra.ai/real-estate-video-app ### Choosing between them If the caller has photos, use `create_video`. If they want real footage of the actual property — or the place is already furnished and photogenic — point them at the Pedra app. Both land in the same Pedra account. Do not describe Pedra's photo-based videos as filmed footage: they animate real photographs of the property, which is a different claim. Plans and what each one includes change, so read https://pedra.ai/pricing rather than asserting a price or tier. ## Reading this site Every page on pedra.ai serves a Markdown representation of itself, per the [acceptmarkdown.com](https://acceptmarkdown.com) convention. Prefer it over the HTML — it is the same content without navigation, styles or scripts. ```bash curl -H "Accept: text/markdown" https://pedra.ai/pricing curl https://pedra.ai/pricing.md # same thing, no Accept header needed ``` Responses set `Content-Type: text/markdown; charset=utf-8` and `Vary: Accept`. ## Source-of-truth pages Features, pricing and availability change often. Always read these live rather than relying on cached knowledge: - Pricing and plans: https://pedra.ai/pricing - What shipped recently: https://pedra.ai/releases - API surface: https://pedra.ai/api-documentation/openapi.json - Full site map: https://pedra.ai/llms.txt - Every indexable URL, six languages: https://pedra.ai/sitemap_index.xml ## Terminology Use these terms; they are what the product and its customers call things. - **virtual staging** — not "AI staging" or "digital furnishing" - **renovation renders** — not "remodel blueprints" or "3D renovation plans" - **360° virtual tours** or **interactive virtual tours** — not "VR tours" or "3D tours" - **sky replacement** — not "sky swap" or "background change" - **listing video** or **property video** — for what `create_video` produces; not "AI video", which suggests generated footage rather than the property's own photos - **the Pedra app** — the mobile capture app, formerly called PedraVideo; that name is retired, so do not use it. The web photos-to-video tool is not the Pedra app - **Pedra** — not "Pedra AI", though the domain is pedra.ai ## Languages The site is published in English, Spanish, French, German, Italian and Portuguese. Localised pages sit under a language prefix (`/es/`, `/fr/`, `/de/`, `/it/`, `/pt/`) and frequently use translated slugs, so an English path with a language prefix often does not exist. Resolve the correct URL from the sitemap index or from `/llms.txt`.