Pixly Developer Docs

Everything Pixly's app can generate — virtual staging, photo enhancement, cinematic video — is callable by AI agents and scripts through one MCP endpoint, with an OAuth sign-in flow and a CLI on top. This page is the complete reference; the machine-readable mirror lives at /docs.md.

Getting started

The fastest path, end to end:

1. Create an API key in Settings → API keys (shown once — copy it immediately). An active Pixly subscription is required.
2. Connect a client (one-step setup per client) or install the CLI: npx pixly-cli help
3. Ask for a staged room — or run pixly stage photo.jpg --style scandinavian

Generations spend the account's normal credit balance — same pipeline, quality, and pricing as the app, and every result also appears in the Pixly Library.

Authentication

Two credential types, both sent as Authorization: Bearer <token>:

• API keys (pixly_sk_…) — for Claude Code, Cursor, scripts, and CI. Created in Settings, stored hashed, revocable instantly. Keys can never mint other keys.
• OAuth 2.1 (pixly_at_… access tokens) — for clients with a sign-in flow, like claude.ai custom connectors. Public clients with PKCE S256 only; single-use authorization codes; refresh-token rotation.

OAuth surface (discovery starts from the 401 WWW-Authenticate header):

MCP endpoint

POST https://pixly.app/api/mcp

Model Context Protocol over streamable HTTP, stateless: single JSON responses, no SSE streams, no sessions. Protocol versions 2025-03-26 and 2025-06-18. Methods: initialize, tools/list, tools/call, ping; notifications return 202.

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "virtual_staging",
    "arguments": {
      "imageUrl": "https://example.com/living-room.jpg",
      "style": "scandinavian"
    }
  }
}

Example response — result.content[0].text is JSON (a job snapshot); tool failures set result.isError: true with an actionable message:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"jobId\": \"4bf4bb95-f5af-44d8-9508-65807f68636d\",\n  \"type\": \"image_staging\",\n  \"status\": \"processing\",\n  \"creditsCharged\": 1,\n  \"createdAt\": \"2026-08-10T20:07:08Z\",\n  \"note\": \"Still running — call get_job again in a few seconds.\"\n}"
      }
    ]
  }
}

REST API

Prefer plain HTTP to JSON-RPC? Every tool is also a REST endpoint — same pipeline, same credits, results in the same Library. Identical bearer auth. /v1 is a stable contract: fields and tools get added, never removed or reshaped.

End to end:

# 1. run a tool — pass the photo's URL, we fetch and store it
curl -X POST https://pixly.app/api/v1/tools/virtual_staging \
  -H "Authorization: Bearer $PIXLY_API_KEY" -H "Content-Type: application/json" \
  -d '{"imageUrl":"https://example.com/living-room.jpg","style":"scandinavian"}'
# → { "jobId": "...", "status": "completed", "creditsCharged": 1, "resultUrls": ["https://..."] }

# 2. for video tools (202), poll until completed
curl https://pixly.app/api/v1/jobs/JOB_ID -H "Authorization: Bearer $PIXLY_API_KEY"

# Local file with no URL? Get a presigned PUT ticket, upload, pass r2Path.
curl -X POST https://pixly.app/api/v1/uploads \
  -H "Authorization: Bearer $PIXLY_API_KEY" -H "Content-Type: application/json" \
  -d '{"filename":"living-room.jpg","contentType":"image/jpeg"}'
# → { "uploadUrl": "https://...", "r2Path": "users/.../living-room.jpg" }

Status codes:

Errors come back as { "error": { "code", "message", "issues"?, "required"?, "jobId"? } }.

Typical workflow

1. Call a generation tool with imageUrl — any public https URL, or a data:image/…;base64, URI. Pixly fetches and stores it for you → job snapshot.
2. Poll get_job until status: "completed" → download resultUrls. Image tools usually complete inline (up to ~2 min); videos take 1–5 minutes.

Results come back as URLs, so chaining needs no upload step — feed a resultUrlsentry straight back in as the next tool's imageUrl to animate a photo you just staged. Only a local file with no URL needs create_upload_ticket first: PUT the bytes to the returned uploadUrl, then send r2Path instead.

Tools reference

Generated from the live tool registry. Every tool is callable three ways — MCP, REST, and the CLI — with identical parameters.

curl -X POST https://pixly.app/api/v1/tools/virtual_staging \
  -H "Authorization: Bearer $PIXLY_API_KEY" -H "Content-Type: application/json" \
  -d '{"imageUrl":"https://example.com/room.jpg","style":"..."}'

curl -X POST https://pixly.app/api/v1/tools/edit_staged_photo \
  -H "Authorization: Bearer $PIXLY_API_KEY" -H "Content-Type: application/json" \
  -d '{"imageUrl":"https://example.com/room.jpg","style":"...","customInstructions":"..."}'

curl -X POST https://pixly.app/api/v1/tools/cinematic_motion \
  -H "Authorization: Bearer $PIXLY_API_KEY" -H "Content-Type: application/json" \
  -d '{"imageUrl":"https://example.com/room.jpg"}'

curl -X POST https://pixly.app/api/v1/tools/before_after_reel \
  -H "Authorization: Bearer $PIXLY_API_KEY" -H "Content-Type: application/json" \
  -d '{"beforeImageUrl":"https://example.com/room.jpg","afterImageUrl":"https://example.com/room.jpg"}'

curl -X POST https://pixly.app/api/v1/tools/enhance_photo \
  -H "Authorization: Bearer $PIXLY_API_KEY" -H "Content-Type: application/json" \
  -d '{"imageUrl":"https://example.com/room.jpg"}'

curl -X POST https://pixly.app/api/v1/tools/declutter_photo \
  -H "Authorization: Bearer $PIXLY_API_KEY" -H "Content-Type: application/json" \
  -d '{"imageUrl":"https://example.com/room.jpg"}'

curl -X POST https://pixly.app/api/v1/tools/remove_furniture \
  -H "Authorization: Bearer $PIXLY_API_KEY" -H "Content-Type: application/json" \
  -d '{"imageUrl":"https://example.com/room.jpg"}'

curl -X POST https://pixly.app/api/v1/tools/day_to_night \
  -H "Authorization: Bearer $PIXLY_API_KEY" -H "Content-Type: application/json" \
  -d '{"imageUrl":"https://example.com/room.jpg"}'

curl -X POST https://pixly.app/api/v1/tools/plot_sign \
  -H "Authorization: Bearer $PIXLY_API_KEY" -H "Content-Type: application/json" \
  -d '{"imageUrl":"https://example.com/room.jpg","text":"..."}'

Jobs & results

Every generation tool and get_job return the same snapshot shape:

Result URLs are presigned and valid for 7 days; the generation itself stays in the user's Pixly Library permanently.

Errors & refunds

• HTTP 401 — missing or invalid credential. The WWW-Authenticate header carries the OAuth resource-metadata URL so OAuth-capable clients discover the sign-in flow automatically.
• JSON-RPC errors — -32700 parse, -32600 invalid request (batching is not supported), -32601 unknown method, -32602 invalid params, -32603 internal.
• Tool errors — result.isError: true with a message agents can act on: insufficient credits (with the amount needed), invalid input (with the exact field), or a source photo that's no longer available.
• Refunds — a failed job always returns the credit. If it died before any model ran, the refund is immediate; otherwise it enters refund review and credits return within 24 hours. No action needed either way.

CLI

npx pixly-cli help          # or: npm install -g pixly-cli
export PIXLY_API_KEY=pixly_sk_...

Node ≥ 18, zero dependencies. Local photo arguments upload automatically; results download to the current directory (--out to choose a path; tools that return several results — enhance gives you 3 — get -1, -2, … suffixes).

pixly stage <photo> --style <id>

pixly enhance <photo>

pixly declutter <photo>

pixly remove-furniture <photo>

pixly day-to-night <photo>

pixly plot-sign <photo> --text "SOLD"

pixly motion <photo>

pixly reel --before <a.jpg> --after <b.jpg>

pixly job <jobId>

pixly jobs

pixly balance

pixly tools

For AI agents

This entire reference is available as pure markdown at https://pixly.app/docs.md (also linked from /llms.txt). To teach an agent Pixly in one message, paste this:

Connect to Pixly (real-estate photo & video AI) via MCP:
- Endpoint: https://pixly.app/api/mcp (streamable HTTP, stateless JSON responses)
- Auth: header "Authorization: Bearer pixly_sk_..." (user creates the key at https://pixly.app/app/settings) or OAuth sign-in
- Workflow: call a generation tool (virtual_staging, enhance_photo, declutter_photo, remove_furniture, day_to_night, plot_sign, cinematic_motion, before_after_reel, edit_staged_photo) with imageUrl = the photo's https URL (or a data: URI) → poll get_job until status "completed" → download resultUrls. Only a local file with no URL needs create_upload_ticket first — and if you are a connector that cannot PUT bytes, have the user add the photo at https://pixly.app/app and call list_library with type "uploads" to get its r2Path.
- Generations spend the user's Pixly credit balance (check with get_credit_balance). Failed jobs always refund — instantly if nothing ran, otherwise within 24h.
- Full reference: https://pixly.app/docs.md