Documentation

Introduction

Floor Plan API runs a U-Net++ wall-segmentation model on the file you upload and returns the binary mask as a PNG. Foreground pixels (255) mark walls; background pixels (0) mark everything else. For a raster input the mask matches its resolution exactly, so it lines up pixel-for-pixel with the image you sent. For a PDF you name the page (page, 1-based, default 1); it is rasterised at 200 DPI (longest edge capped at 8192 px) and the mask matches that raster; the size comes back in X-Mask-Width / X-Mask-Height.

Two ways to call the API, both fully supported and documented end-to-end:

• Python library — pip install floorplan-api. Typed sync and asyncio clients, automatic retries, image and PDF input. See Python library.
• REST API — plain HTTP from any language or HTTP client (curl, Node fetch, Go, Ruby, …). See REST API.

Quickstart

1. Get an API key

Create an account, then generate a key from the dashboard. Test keys (fp_test_…) use the same model but aren't billed.

2. Make your first request

pip install floorplan-api

# in Python:
from floorplan_api import Client

client = Client(api_key="fp_test_...")
mask_png = client.extract("plan.png")

with open("walls.png", "wb") as fh:
    fh.write(mask_png)

print(f"{mask_png.width}x{mask_png.height} mask, {len(mask_png)} bytes")

3. Inspect the response

On success the response body is a single-channel PNG withContent-Type: image/png. Useful headers:

HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 18432
X-Mask-Width: 1024
X-Mask-Height: 768
X-Job-Id: job_abc123
X-Request-Id: req_def456

Mask output

The output of every successful inference call is a single PNG. Knowing exactly what's in it makes the rest of the docs simpler.

See Working with the mask for Python recipes that overlay the mask on the original image, count wall pixels, or convert it to other formats.

What happens to your file

Images and PDFs leave your machine differently. Be aware of the difference before you rely on either.

The API server never touches pixels either: it checks the declared type, size and page, stores the bytes as uploaded, and the GPU worker decodes them once, like this:

• Rasters (PNG, JPEG, WEBP) are decoded with OpenCV in colour mode. Alpha is dropped without compositing, so flatten transparent PNGs onto white before uploading; grayscale is expanded to three channels; 16-bit depth becomes 8-bit; JPEG EXIF orientation is applied, so the mask aligns with the image as displayed; ICC profiles are ignored. The mask is on the decoded image's own pixel grid.
• Very large rasters (longer edge above 8192 px) are processed downscaled to that bound and the mask is resized back to the input size: still pixel-aligned, with less detail.
• PDF pages are rendered at 200 DPI onto white (transparent regions composite onto white), reduced so the longer edge is at most 8192 px. A 24 × 36 in sheet becomes 4800 × 7200 px. Everything on the page is rendered: linework, hatching, text, dimensions. The mask has the rendered size (X-Mask-Width / X-Mask-Height). To map it back to PDF coordinates use px = pt × width_px / page_width_pt; the Python client does this for you via MaskBytes.pdf_scale.
• Inference is a two-stage U-Net++: the whole sheet at a shortest side of 1024 px, then a crop refiner at native resolution in 512 px tiles. No test-time augmentation, no ensembling.
• Failures at this stage (undecodable bytes, a password-protected PDF, a page past the end) fail the job with inference_error and are not retried: the same file would fail again.

Authentication

Every request must carry an API key in the Authorization header:

Authorization: Bearer fp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Python library

The official client — typed, with retries built in — in a synchronous flavour (Client, on requests) and an asyncio flavour (AsyncClient, on httpx). Works on Python 3.9+.

Install

pip install floorplan-api              # Client (requests)
pip install "floorplan-api[async]"     # + AsyncClient (httpx)

Runtime dependencies are requests and pypdf (pure Python, used to cut the requested page out of a PDF before upload); the async extra adds httpx. PIL / OpenCV / NumPy are optional and only needed if you want to process the returned mask in Python.

Initialise the client

from floorplan_api import Client

client = Client(
    api_key="fp_live_...",
    timeout=60.0,
    max_retries=3,
    retry_backoff=0.5,
)

extract()

Synchronous wall segmentation. Accepts a path, raw bytes, or a binary file-like object holding a PNG, JPEG, WEBP or PDF. Returns MaskBytes: the PNG mask as bytes, with width, height, job_id, request_id and mode attached, plus page_size_pt / pdf_scale for a PDF.

from pathlib import Path

# any of these works:
mask = client.extract("plans/floor1.png")            # path
mask = client.extract(Path("plans/set.pdf"), page=3) # PDF: page 3 (1-based; default 1)
mask = client.extract(image_bytes)                   # raw bytes (format is sniffed)
with open("plan.jpg", "rb") as fp:
    mask = client.extract(fp)                        # file-like

mask.width, mask.height     # from X-Mask-Width / X-Mask-Height
mask.job_id                 # from X-Job-Id
open("walls.png", "wb").write(mask)   # it is still bytes

# PDF input: map the mask back to the page (the client measured it before upload)
mask = client.extract("plans/set.pdf", page=3)
mask.page_size_pt           # (1728.0, 2592.0) points, /Rotate honoured
mask.pdf_scale              # mask px per PDF pt  ->  x_px = x_pt * mask.pdf_scale
mask.pdf_dpi                # the DPI actually rendered (200, or less past the 8192 px cap)

# Per-call timeout override:
mask = client.extract("plan.png", timeout=120.0)

The client identifies the format from the file's leading bytes (PNG, JPEG, WEBP and PDF signatures), falling back to the extension, and raises InvalidRequestError for anything else before making a request. An image is uploaded byte for byte. A PDF is not: the client rewrites it locally into a single-page PDF holding only the requested page (see What happens to your file), so a 40-page drawing set costs one page of upload and the server never holds the rest; a page that does not exist (or a password-protected file) is rejected before any request. page other than 1 is an error for raster input. Max inline upload size 10 MB. The returned bytes are a single-channel PNG (see Mask output).

analyze()

Currently produces the same wall mask as extract(). Costs 2 credits per call. Kept distinct so future capabilities (per-room classification, symbol detection) can attach to analyze without changing extract's contract.

mask_png = client.analyze("plan.png")

Large files (presigned uploads)

The inline extract() / analyze() path streams the bytes through the API server, which caps the request at 10 MB. For larger files, the client uploads directly to object storage via a presigned URL the API hands back, then submits the job by storage key — the API server never holds the bytes.

upload_then_extract() is the one-shot helper. Files smaller than threshold_bytes (default 10 MiB) go through the inline path; larger files switch to the presigned flow automatically.

# Same return value as extract() — MaskBytes (the PNG mask).
# For a PDF the size check runs on the selected page, not the whole file.
mask_png = client.upload_then_extract("big_floor_plan.pdf", page=2)

# Force the presigned path even for small files (e.g. CI smoke tests):
mask_png = client.upload_then_extract("plan.png", threshold_bytes=0)

If you need finer control — say, you already have the bytes in S3 and just want to extract — use the two-step API:

# 1. Reserve a slot. Returns {upload_url, key, expires_at, content_type}.
#    content_type: image/png | image/jpeg | image/webp | application/pdf
slot = client.create_upload(content_type="image/png")

# 2. PUT the bytes (any HTTP client; we use the built-in session here).
import requests
with open("plan.png", "rb") as fp:
    res = requests.put(
        slot["upload_url"],
        data=fp,
        headers={"Content-Type": slot["content_type"]},
    )
    res.raise_for_status()

# 3. Or, with the helper that wraps create_upload + PUT. For a PDF, page=
#    cuts that page out first, so the stored object is a single-page PDF.
upload_key = client.upload("plan.png")

# 4. Run extract by storage key (no bytes flow through the API server).
#    analyze() and analyze_async() take upload_key= the same way. If the
#    stored object is a multi-page PDF you uploaded yourself, add page=N and
#    the server renders that page.
mask = client.extract(upload_key=upload_key)

AsyncClient (asyncio)

AsyncClient has the same methods as Client, every one a coroutine, on top of httpx. Install with pip install "floorplan-api[async]". Use it as an async context manager so the connection pool is closed, or pass your own httpx.AsyncClient as client= (proxies, HTTP/2) and it is left open.

import asyncio
from floorplan_api import AsyncClient

async def main() -> None:
    async with AsyncClient() as client:          # FLOORPLAN_API_KEY from env
        masks = await asyncio.gather(
            client.extract("plans/a.pdf", page=2),
            client.extract("plans/b.png"),
            client.upload_then_extract("plans/huge.pdf"),
        )
        for mask in masks:
            print(mask.size, mask.job_id)

asyncio.run(main())

Retries, error classes, MaskBytes and the job helpers below behave identically in both clients; only close() becomes await aclose().

Background jobs

For batches or longer-running analyses, submit a job and poll for completion, then download the mask. Three calls cover the full lifecycle (available on both clients):

Complete walkthrough:

from floorplan_api import Client, FloorPlanError

with Client() as client:
    job = client.analyze_async("plan.png")
    print(f"Submitted {job.id} (status={job.status})")

    final = client.wait_for_job(
        job.id,
        poll_interval=2.0,    # seconds between polls
        timeout=300.0,        # raise TimeoutError after 5 min
    )
    print(f"Final status: {final.status}")

    if final.status != "completed" or final.result is None:
        raise FloorPlanError(final.error["message"] if final.error else "no result")

    print(f"Mask is {final.result.width}x{final.result.height}px")
    mask_png = client.download_mask(final.id)

    with open("walls.png", "wb") as fh:
        fh.write(mask_png)

Or poll yourself with custom logic:

import time

job = client.analyze_async("plan.png")
while not job.is_terminal:
    time.sleep(1.0)
    job = client.get_job(job.id)

Working with the mask

The bytes you get back are a standard PNG, so any image library works. A few common patterns:

from io import BytesIO
from PIL import Image

mask_png = client.extract("plan.png")

# Decode the PNG and inspect it.
mask_img = Image.open(BytesIO(mask_png))
print(mask_img.size)        # (width, height) — same as the input image
print(mask_img.mode)        # "L" — single-channel 8-bit grayscale

# Save somewhere else, convert format, etc.
mask_img.save("walls.tiff")
mask_img.convert("1").save("walls_bw.png")     # 1-bit bitmap

Error handling

import time
from floorplan_api import (
    Client, FloorPlanError,
    AuthenticationError, RateLimitError, InvalidRequestError, NotFoundError,
    ServerError, ProcessingError, TimeoutError, ConnectionError,
)

client = Client()

try:
    mask = client.extract("plan.png")
except RateLimitError as exc:
    # Already retried max_retries times honouring Retry-After.
    time.sleep(exc.retry_after or 5.0)
    mask = client.extract("plan.png")
except TimeoutError as exc:
    # 504: the worker is still on it. Do not resubmit — finish the job.
    if exc.job_id is None:
        raise
    job = client.wait_for_job(exc.job_id)
    mask = client.download_mask(job.id)
except ProcessingError as exc:
    # The worker failed this file (undecodable, ...). Same input will fail again.
    print(f"cannot process: {exc.message} (job {exc.job_id})")
    raise
except AuthenticationError:
    print("Invalid or revoked API key")
    raise
except InvalidRequestError as exc:
    # 400 / 409 / 413 / 415, or rejected locally (unsupported bytes) — fix the input
    print(f"bad request: {exc.message}")
    raise
except FloorPlanError as exc:
    # Anything else — keep the request_id for support tickets.
    print(f"{exc.type}: {exc.message} (request_id={exc.request_id})")
    raise

Connection failures, 429 and transient 5xx responses are retried up to max_retries times with exponential backoff and jitter; a server Retry-After (sent on 429 and on 503 when the queue is at capacity) overrides the backoff, capped at 30 s per attempt. The upload body is rewound before every retry.

Two responses are deliberately not retried because the server has already queued the job: a 504 timeout_error (raised as TimeoutError with job_id set — the job is still running) and a 500 that carries a job_id (raised as ProcessingError — the worker failed that input). Retrying either would create a second job for the same file.

Configuration

Method reference

image can be a path (str / pathlib.Path), raw bytes, or any binary file-like object.

Types reference

class MaskBytes(bytes):          # returned by extract / analyze / upload_then_extract / download_mask
    width: int | None            # X-Mask-Width
    height: int | None           # X-Mask-Height
    job_id: str | None           # X-Job-Id
    request_id: str | None       # X-Request-Id
    mode: str | None             # X-Floorplan-Mode: "live" | "test"
    size: tuple[int, int] | None # (width, height) when both known
    page_size_pt: tuple[float, float] | None   # PDF input only: page size in points
    pdf_scale: float | None      # mask px per PDF pt (width / page_size_pt[0])
    pdf_dpi: float | None        # pdf_scale * 72

def pdf_page_size(data: bytes, page: int = 1) -> tuple[float, float]:
    """(width, height) in points of a PDF page as it renders (crop box, /Rotate applied)."""

@dataclass(frozen=True)
class MaskResult:
    result_url: str    # path on the API host (combine with base_url to GET)
    width: int         # pixels
    height: int        # pixels

@dataclass(frozen=True)
class Job:
    id: str
    status: Literal["queued","processing","completed","failed"]
    created_at: datetime
    completed_at: datetime | None
    result: MaskResult | None
    error: dict | None

    @property
    def is_terminal(self) -> bool: ...

# All exceptions derive from FloorPlanError:
class FloorPlanError(Exception):
    type: str | None
    message: str
    status_code: int | None
    request_id: str | None
    job_id: str | None           # set when the server had already queued a job
    response: dict | None

class AuthenticationError(FloorPlanError): ...   # 401 / 403
class InvalidRequestError(FloorPlanError): ...   # 400 / 409 / 413 / 415 / other 4xx, or rejected locally
class NotFoundError(FloorPlanError): ...         # 404
class RateLimitError(FloorPlanError):            # 429 (after retries)
    retry_after: float | None
class ServerError(FloorPlanError): ...           # 5xx (after retries)
class ProcessingError(ServerError): ...          # 500 with job_id: worker failed the job; not retried
class TimeoutError(FloorPlanError): ...          # client timeout, wait_for_job deadline, or 504 with job_id (not retried)
class ConnectionError(FloorPlanError): ...

REST API

All requests use HTTPS. The hosted base URL is https://api.floorplanapi.com. When developing locally, use http://localhost:3000. Each endpoint below shows the same call in cURL, raw Python (requests), and Node.js (fetch).

Base URL

Production:

https://api.floorplanapi.com

Local development:

http://localhost:3000

Authorization header

Authorization: Bearer fp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

POST /v1/uploads

Content-Type: application/json

{
  "content_type": "image/png"   // optional; defaults to "image/png"
                                // image/png | image/jpeg | image/webp | application/pdf
                                // — must match the Content-Type used on PUT
}

# 1. Reserve a slot.
curl -X POST https://api.floorplanapi.com/v1/uploads \
  -H "Authorization: Bearer fp_test_..." \
  -H "Content-Type: application/json" \
  -d '{"content_type":"image/png"}'

# Response:
# {"upload_url":"https://...","key":"uploads/<rand>.png","expires_at":"...","content_type":"image/png"}

# 2. PUT the bytes to upload_url with the same content_type.
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  --data-binary @big_plan.png

# 3. Submit the job by storage key.
curl -X POST https://api.floorplanapi.com/v1/extract \
  -H "Authorization: Bearer fp_test_..." \
  -F "upload_key=$KEY" \
  --output walls.png

HTTP/1.1 200 OK
Content-Type: application/json

{
  "upload_url": "https://<bucket>.<account>.r2.cloudflarestorage.com/uploads/...?X-Amz-...",
  "key": "uploads/<48-hex>.png",
  "expires_at": "2026-04-28T13:15:00.000Z",
  "content_type": "image/png"
}

POST /v1/extract

# Inline (small files, ≤ 10 MB):
curl -X POST https://api.floorplanapi.com/v1/extract \
  -H "Authorization: Bearer fp_test_..." \
  -F "image=@plan.png" \
  --output walls.png

# By storage key (after POST /v1/uploads + PUT):
curl -X POST https://api.floorplanapi.com/v1/extract \
  -H "Authorization: Bearer fp_test_..." \
  -F "upload_key=uploads/<key>.png" \
  --output walls.png
# Page 3 of a PDF:
curl -X POST https://api.floorplanapi.com/v1/extract \
  -H "Authorization: Bearer fp_test_..." \
  -F "image=@drawing-set.pdf;type=application/pdf" \
  -F "page=3" \
  --output walls.png

HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 18432
X-Mask-Width: 1024
X-Mask-Height: 768
X-Job-Id: job_abc123
X-Request-Id: req_def456

<binary PNG bytes>

POST /v1/analyze

curl -X POST https://api.floorplanapi.com/v1/analyze \
  -H "Authorization: Bearer fp_test_..." \
  -F "image=@plan.png" \
  --output walls.png

curl -X POST https://api.floorplanapi.com/v1/analyze \
  -H "Authorization: Bearer fp_test_..." \
  -F "image=@plan.png" \
  -F "async=true"

{
  "success": true,
  "job_id": "job_abc123",
  "status": "queued",
  "created_at": "2026-04-28T13:00:00.000Z",
  "mode": "test"
}

GET /v1/status/{job_id}

curl https://api.floorplanapi.com/v1/status/job_abc123 \
  -H "Authorization: Bearer fp_test_..."

{
  "job_id": "job_abc123",
  "status": "completed",   // or "queued" | "processing" | "failed"
  "created_at": "2026-04-28T13:00:00.000Z",
  "completed_at": "2026-04-28T13:00:02.000Z",
  "result": {
    "result_url": "/v1/jobs/job_abc123/mask",
    "width": 1024,
    "height": 768
  },
  "error": null            // or { "type": "...", "message": "..." }
}

import time, requests

def wait(job_id, *, key, base="https://api.floorplanapi.com", timeout=300):
    deadline = time.monotonic() + timeout
    while True:
        res = requests.get(f"{base}/v1/status/{job_id}",
                           headers={"Authorization": f"Bearer {key}"})
        res.raise_for_status()
        job = res.json()
        if job["status"] in ("completed", "failed"):
            return job
        if time.monotonic() > deadline:
            raise TimeoutError(job_id)
        time.sleep(1.5)

GET /v1/jobs/{job_id}/mask

curl https://api.floorplanapi.com/v1/jobs/job_abc123/mask \
  -H "Authorization: Bearer fp_test_..." \
  --output walls.png

HTTP/1.1 200 OK
Content-Type: image/png
X-Mask-Width: 1024
X-Mask-Height: 768
X-Job-Id: job_abc123

<binary PNG bytes>

Response headers

Errors

Error responses always use Content-Type: application/json with a stable shape, even on endpoints whose success responses are PNG bytes. The Python client maps these onto typed exceptions.

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key."
  }
}

Rate limits & quotas

Rate limits are per API key per minute. Hitting the limit returns 429 with a Retry-After header. Monthly credit budgets apply separately and reset on the first day of the billing period.

Support

Have a question, found a bug, or want to ship something we don't expose yet?

• Contact us — for everything else.
• Include the X-Request-Id response header (or the request_id field on the FloorPlanError in Python) to speed things up.
• Dashboard — manage keys, view usage, change plan.