README.md

metadata

title: SpatialThings Depth Pro API
sdk: docker
app_port: 8000

SpatialThings Hosted Depth Pro API

This directory packages a Hugging Face hosted Depth Pro server that preserves the Android API contract used by SpatialThings.

Deployment choice

Use a Hugging Face Inference Endpoint custom container as the primary production path. The endpoint should select apple/DepthPro-hf as the model repository so Hugging Face mounts the model at /repository, while the Docker image contains only this FastAPI server and Python dependencies.

Use a Docker Space only as a fallback. Free Spaces sleep when idle, so they do not satisfy the always-available requirement. Paid Spaces can run indefinitely, but Inference Endpoints have the cleaner production deployment and autoscaling controls.

API contract

• GET /health
• POST /estimate-depth
• Request Content-Type: image/jpeg
• Response Content-Type: application/octet-stream
• Response body: contiguous float32 little-endian depth map
• Response headers:
  • X-Depth-Width
  • X-Depth-Height
  • X-Depth-Scale: metric_meters
  • X-Process-Time-Sec

The server returns the predicted_depth tensor from apple/DepthPro-hf after post_process_depth_estimation(..., target_sizes=[(image.height, image.width)]). It does not normalize the output.

Cost and availability

For always-on production, configure the endpoint with:

• min replicas: 1
• max replicas: 1 to start, increase only after measuring traffic
• scale-to-zero: disabled
• hardware: start with 1x Nvidia L4; T4 can be cheaper but has less GPU memory

As of 2026-07-02 from Hugging Face pricing docs:

• Inference Endpoint AWS T4 x1: $0.50/hr, about $365/month at 730 hours
• Inference Endpoint AWS L4 x1: $0.80/hr, about $584/month
• Inference Endpoint GCP L4 x1: $0.70/hr, about $511/month
• Space T4 small: $0.40/hr, Space T4 medium: $0.60/hr, Space L4 x1: $0.80/hr

Do not enable scale-to-zero for the Android production URL. Hugging Face documents cold starts, temporary 503 responses while a replica initializes, and multi-minute scale-up time depending on the model. That behavior conflicts with an always-available mobile backend.

Build and push the container

From the repository root:

docker build --platform linux/amd64 \
  -f deploy/hf_depth_pro/Dockerfile.gpu \
  -t <registry-user>/spatialthings-depth-pro:0.1.0 \
  deploy/hf_depth_pro

docker push <registry-user>/spatialthings-depth-pro:0.1.0

--platform linux/amd64 matters on Apple Silicon Macs because Hugging Face Endpoint infrastructure expects x86_64 container images.

Create the Inference Endpoint

Use the Inference Endpoints UI when deploying a custom container:

1. Create a new endpoint.
2. Model repository: apple/DepthPro-hf.
3. Custom container image: <registry-user>/spatialthings-depth-pro:0.1.0.
4. Container port: 8000.
5. Hardware: 1x Nvidia L4 recommended for the first production deployment.
6. Autoscaling: min replicas=1, max replicas=1, scale-to-zero disabled.
7. Visibility:
   • Public keeps the current Android contract with no auth header, but exposes the endpoint to abuse.
   • Protected requires adding Authorization: Bearer ... in the Android client.

After the endpoint reaches Running, set the Android Depth Pro base URL to:

https://<endpoint-id>.<region>.endpoints.huggingface.cloud

Space fallback

For the free CPU test path, create a Docker Space without --flavor and without --sleep-time -1:

hf repos create <user-or-org>/spatialthings-depth-pro \
  --type space \
  --space-sdk docker \
  --public \
  --exist-ok

hf upload <user-or-org>/spatialthings-depth-pro deploy/hf_depth_pro . \
  --type space

For Space fallback, set this runtime variable:

DEPTH_PRO_MODEL_ID=apple/DepthPro-hf
DEPTH_PRO_EAGER_LOAD=false

The Space URL is:

https://<user-or-org>-spatialthings-depth-pro.hf.space

This free Space uses CPU Basic. It is suitable for cold-start and rough latency checks only. It can sleep when idle, and Depth Pro CPU inference is expected to be much slower than a paid GPU endpoint.

For a paid always-on Space fallback, recreate or upgrade it with GPU hardware and --sleep-time -1.

Local development fallback

Local execution is only for development validation:

cd deploy/hf_depth_pro
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

DEPTH_PRO_MODEL_ID=apple/DepthPro-hf \
DEPTH_PRO_DEVICE=auto \
uvicorn main:app --host 0.0.0.0 --port 8000

Smoke-test the Android contract:

python smoke_test.py \
  --base-url http://127.0.0.1:8000 \
  --image ../../data/tmp_inputs/cat_fallback.jpg