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": {
      "r2Path": "users/<your-user-id>/staging/1754820000000-living-room.jpg",
      "style": "scandinavian",
      "numImages": 1
    }
  }
}

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}"
      }
    ]
  }
}

Typical workflow

1. Get the photo in: create_upload_ticket (local bytes — PUT to the returned uploadUrl) or upload_image_from_url. Both return an r2Path.
2. Call a generation tool with that r2Path → job snapshot.
3. Poll get_job until status: "completed" → download resultUrls. Image tools usually complete inline (up to ~2 min); videos take 1–5 minutes.

Tools reference

Generated from the live tool registry — this is exactly what tools/list returns.

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 job that fails after the charge enters refund review automatically; credits return within 24 hours. No action needed.

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; multiple variations get -1, -2, … suffixes).

pixly stage <photo> --style <id>

pixly enhance <photo>

pixly declutter <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: create_upload_ticket (local file) or upload_image_from_url → returns r2Path → call a generation tool (virtual_staging, enhance_photo, declutter_photo, day_to_night, plot_sign, cinematic_motion, before_after_reel, edit_staged_photo) → poll get_job until status "completed" → download resultUrls.
- Generations spend the user's Pixly credit balance (check with get_credit_balance). Failed jobs auto-refund within 24h.
- Full reference: https://pixly.app/docs.md