# PropertyPixel - **Get started** - [Overview](/docs): Use PropertyPixel from ChatGPT, Claude or your own code. - Quickstart - [Quickstart: ChatGPT](/docs/quickstart/chatgpt): Edit listing photos inside a ChatGPT conversation. - [Quickstart: Claude](/docs/quickstart/claude): Add PropertyPixel to Claude as a custom connector. - [Quickstart: REST](/docs/quickstart/rest): Enhance a listing from the command line with curl. - **Guides** - [Authentication](/docs/authentication): OAuth for AI assistants and apps, API keys for scripts. Every credential is bound to one workspace. - [Credits and quotes](/docs/credits-and-quotes): How spending works, what things cost, and how to confirm a spend. - [Uploading photos](/docs/uploading-photos): Four ways to get listing photos into a project. - [Jobs and polling](/docs/jobs): How edits run in the background and how to wait for results. - [Webhooks](/docs/webhooks): Get notified when jobs finish and uploads arrive. - [Errors](/docs/errors): Every error code and what to do about it. - [Rate limits](/docs/rate-limits): Request limits per connection. - **Reference** - [MCP tools](/docs/mcp-tools): Every tool the PropertyPixel MCP server exposes. - API reference - [API reference](/docs/api): Every REST endpoint, generated from the same operations as the MCP tools. - Account: The workspace this credential is connected to, its plan and credit balance. - [Get account](/docs/api/account/get_account): Get the connected PropertyPixel account: the workspace and the user's role in it, whether this connection can make changes, the credit balance (100 credits = one photo enhancement), the plan, and whether results are watermarked (trial). Call this before spending to check the balance, or when the user asks about their credits or plan. Works with view-only access. - Projects: Properties. Each project holds the photos and results for one listing. - [List projects](/docs/api/projects/list_projects): List the property projects in the connected workspace, newest first by default. Each project groups the photos of one listing. Use `search` to find a project by name or address before asking the user for an ID. Returns project IDs, photo counts, a cover image and a Studio link; page with `next_cursor`. Works with view-only access. - [Create a project](/docs/api/projects/create_project): Create a new, empty project for one property listing. Name it after the address or listing so the user can find it later. Then add photos with add_photos or create_upload_link. Requires a connection with edit access. - [Get a project](/docs/api/projects/get_project): Get one project with all its photos (IDs, room types, signed preview URLs) and the status of its most recent upload link (waiting, receiving, done or expired). Use the photo IDs with enhance_photos, stage_photos or create_video. To see finished edits, call show_results instead. Works with view-only access. - [Delete a project](/docs/api/projects/delete_project): Delete a project with all its photos and edited results. Only do this when the user explicitly asks to delete that project; confirm the project name with them first. It disappears from the Studio immediately. Requires a connection with edit access. - [Show results](/docs/api/projects/show_results): Show a project's edited results: what is still processing, the newest finished version of each photo and each video, and the versions the user picked. Use this when the user wants to see or review their results. Result URLs are signed for 1 hour. Works with view-only access. - Photos: Source photos in a project. - [Add photos to a project](/docs/api/photos/add_photos): Add photos to a project from public https image URLs (`image_urls`) or from files the user attached in ChatGPT (`files`). Up to 25 photos per call; a project holds at most 100. Each file must be JPEG, PNG, WebP, HEIC or HEIF and at most 25 MB. Dropbox and Google Drive share links work if they are shared publicly. HEIC is converted to JPEG and large photos are downscaled to a 2048px long edge, like the web app. Returns the new photos (use their IDs with enhance_photos, stage_photos or create_video) and a `failed` list with a reason per source; report failures to the user rather than retrying blindly. If the user has photos on their phone or computer and no links, call create_upload_link instead. Requires a connection with edit access. - [Delete photos](/docs/api/photos/delete_photos): Delete photos from a project, together with every edit, staging and video made from them. Only do this when the user explicitly asks to remove those photos; confirm which ones first. All IDs must belong to the project, otherwise nothing is deleted. Returns the deleted IDs; call get_project to see what remains. Requires a connection with edit access. - Uploads: Signed uploads from a script, and no-login upload links for a phone. - [Start a signed upload](/docs/api/uploads/create_upload): Reserve room in a project for up to 25 photos and get one signed URL per file. PUT each file's raw bytes to its upload_url with exactly the returned headers, then call POST /uploads/{id}/complete with the storage_path, filename, size and content_type of every file that uploaded. Files must be JPEG, PNG, WebP, HEIC or HEIF, at most 25 MB each; a project holds at most 100 photos. The reservation expires at expires_at (about 15 minutes); complete before then. Files are stored exactly as sent, except HEIC/HEIF, which is converted to JPEG on completion. Downscale large images yourself (the web app uses a 2048px long edge). Requires a connection with edit access. - [Complete a signed upload](/docs/api/uploads/complete_upload): Finish a signed upload: verifies each stored file (size, type and content) and adds it to the project as a photo. List every file that uploaded; files left out are discarded and their reserved room released. HEIC/HEIF files are converted to JPEG. Returns the new photos and a `failed` list with a reason per file. Requires a connection with edit access. - [Create an upload link](/docs/api/uploads/create_upload_link): Create a private link (with a QR code) the user opens on their phone or computer to add photos to a project, with no login. Use it when the user needs to send photos you can't receive directly, such as photos on their phone. Share the url, or show the QR code, and tell the user the link works for 2 hours. Photos appear in the project as they upload. To follow progress, call get_project and read upload_link.status and upload_link.photos_received until status is done (the user tapped Done), or simply ask the user to tell you when they've finished. Requires a connection with edit access. - Edit options: The enhancement types, design styles and video settings you can request. - [List edit options](/docs/api/edit-options/list_edit_options): List every edit PropertyPixel can make, with the exact keys to pass to other tools: enhancement types for enhance_photos (combinable, e.g. blue_skies + improve_lighting), design styles and variation limits for stage_photos, room types, Photo to Video settings for create_video (1–9 photos; one makes a clip, several make a Listing Tour), the Ultra HD add-on, and credit prices. Call this when the user asks what you can do, or before choosing keys you are unsure of. Works with view-only access. - Editing: Photo enhancement and virtual staging. Spends credits. - [Enhance photos](/docs/api/editing/enhance_photos): Apply AI edits (lighting, declutter, blue skies, day to dusk, furniture removal, and more) to listing photos. Costs 100 credits per photo, plus 100 per photo with ultra_hd. All enhancement_types are combined into one result per photo. Select photos with photo_ids, or project_id + all_photos: true. Defaults: ultra_hd false; edits start from the original photo unless versions names a prior result. Spends credits in two steps. Call without quote_id first: you get a quote (cost, balance after, warnings) and nothing is spent. Show the cost to the user and wait for a yes, then call again with the same arguments plus quote_id. The quote lasts 10 minutes and only matches identical arguments. Results are asynchronous: this returns job IDs right away (status pending). Poll get_job_status with the job IDs, waiting poll_after_ms between calls, until each job is completed or failed. Failed jobs are refunded automatically. Requires a connection with edit access. Spends credits. Without `quote_id` it returns 409 `quote_required` with a quote and spends nothing. Resend with `quote_id` to run, or send `auto_confirm: true` to skip the quote. - [Virtually stage photos](/docs/api/editing/stage_photos): Virtually stage rooms: furnish empty rooms or restyle furnished ones in a design_style. Costs 100 credits per variation per photo, plus 100 per variation with ultra_hd. Select photos with photo_ids, or project_id + all_photos: true. Defaults: variations 1, ultra_hd false; staging starts from the original photo unless versions names a prior result (e.g. a decluttered one). Spends credits in two steps. Call without quote_id first: you get a quote (cost, balance after, warnings) and nothing is spent. Show the cost to the user and wait for a yes, then call again with the same arguments plus quote_id. The quote lasts 10 minutes and only matches identical arguments. Results are asynchronous: this returns job IDs right away (status pending). Poll get_job_status with the job IDs, waiting poll_after_ms between calls, until each job is completed or failed. Failed jobs are refunded automatically. Requires a connection with edit access. Spends credits. Without `quote_id` it returns 409 `quote_required` with a quote and spends nothing. Resend with `quote_id` to run, or send `auto_confirm: true` to skip the quote. - Video: Photo to Video clips and Listing Tours. Spends credits. - [Create a video](/docs/api/video/create_video): Turn listing photos into a video. One photo makes a Photo to Video clip; 2–9 photos make a Listing Tour, in the order given. Costs 400 credits per photo. Defaults: clip_seconds 3, aspect_ratio "auto"; each photo uses its original unless versions names an enhanced result. Spends credits in two steps. Call without quote_id first: you get a quote (cost, balance after, warnings) and nothing is spent. Show the cost to the user and wait for a yes, then call again with the same arguments plus quote_id. The quote lasts 10 minutes and only matches identical arguments. Results are asynchronous: this returns job IDs right away (status pending). Poll get_job_status with the job IDs, waiting poll_after_ms between calls, until each job is completed or failed. Failed jobs are refunded automatically. Videos take a few minutes. Requires a connection with edit access. Spends credits. Without `quote_id` it returns 409 `quote_required` with a quote and spends nothing. Resend with `quote_id` to run, or send `auto_confirm: true` to skip the quote. - Recommendations: Suggested edits for each photo (free), and applying them (spends credits). - [Get edit recommendations](/docs/api/recommendations/get_recommendations): Free. Ask PropertyPixel's AI which corrective edits each photo needs (e.g. improve_lighting, clean_and_tidy, straighten_and_reframe). Select photos with photo_ids, or project_id + all_photos: true. Returns the Recommendations that already exist and starts analysis for photos that have none. Analysis is asynchronous: photos in pending_photo_ids are still being analysed, so call again after poll_after_ms to see them. A daily analysis limit applies; photos over it are listed in skipped_photo_ids. To run the suggestions, pass the ready Recommendation IDs to apply_recommendations (paid). Requires a connection with edit access. - [Apply recommendations](/docs/api/recommendations/apply_recommendations): Run ready Recommendations from get_recommendations as enhancement jobs: one job per photo with all its suggested edits. Costs 100 credits per Recommendation. Only status ready can be applied. Spends credits in two steps. Call without quote_id first: you get a quote and nothing is spent. Show the cost to the user and wait for a yes, then call again with the same arguments plus quote_id (valid 10 minutes). Results are asynchronous: poll get_job_status with the returned job IDs, waiting poll_after_ms between calls. Failed jobs are refunded automatically. Requires a connection with edit access. Spends credits. Without `quote_id` it returns 409 `quote_required` with a quote and spends nothing. Resend with `quote_id` to run, or send `auto_confirm: true` to skip the quote. - Jobs: Status, results and picks of enhancement, staging and video jobs. - [Check job status](/docs/api/jobs/get_job_status): Check progress of up to 100 jobs returned by enhance_photos, stage_photos, apply_recommendations or create_video. Returns status (pending, processing, completed, failed, cancelled), progress, result URLs (signed for 1 hour) and a poll_after_ms hint. Photo edits usually finish in under a minute and videos in a few minutes; wait poll_after_ms between checks instead of calling in a tight loop. Failed jobs are refunded automatically. Works with view-only access. - [Get a job](/docs/api/jobs/get_job): Get one job's status, progress and result URL (signed for 1 hour). Works with view-only access. - [Pick a result](/docs/api/jobs/pick_results): Mark a finished photo or video version as a pick (picked: true) or remove the mark (picked: false). Picks are the versions the user wants to keep; get_download_link with picks_only downloads them together. Picks are shared by the workspace and never change or delete the versions themselves. Only completed enhancement, staging and video jobs can be picked. Works with view-only access. - Downloads: Signed download links and zip archives. - [Get a download link](/docs/api/downloads/get_download_link): Get download links for finished results. Pass job_ids (1–100 completed versions from one project), or project_id to download that project's picks (picks_only defaults to true; false downloads every finished version, up to 100). One version returns a signed link immediately. Several photos start a zip: status is processing, so call get_download with the returned id after poll_after_ms. If any videos are included you get one signed link per file in `files` instead of a zip. Links last 1 hour; trial accounts get watermarked files. Works with view-only access. - [Check a zip download](/docs/api/downloads/get_download): Check a zip started by get_download_link. While status is processing, wait poll_after_ms and call again; when ready, url is the zip (valid for 1 hour). If it failed, call get_download_link again. Works with view-only access. - Quotes: Price a spending request before running it. - [Create a quote](/docs/api/quotes/create_quote): Price a spending request without running it. Pass the returned id as quote_id to the operation within 10 minutes. Requires a connection with edit access. - [Changelog](/docs/changelog): Changes to the PropertyPixel API and MCP server.