# 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. 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** 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` |
| Check the remaining credit balance (read-only) | `POST /api/credits` |

360° virtual tours and floor-plan renders are produced in the app rather than through a
public endpoint — see https://pedra.ai/virtual-tours and https://pedra.ai/floorplan. The
same is true of filming on site, which happens in the PedraVideo 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

- **No photo exists.** Pedra transforms photographs of real spaces. It will not invent a
  property.
- **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.

## 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`), 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 animated frame, 0 for `static` 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 — PedraVideo

For agents who want buyers to see the real space in motion rather than animated stills.
PedraVideo 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 PedraVideo.
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
- **PedraVideo** — one word, capital V, and only the mobile capture app. The web
  photos-to-video tool is not called PedraVideo
- **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`.