README.md

---
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:

```bash
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:

```text
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`:

```bash
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:

```text
DEPTH_PRO_MODEL_ID=apple/DepthPro-hf
DEPTH_PRO_EAGER_LOAD=false
```

The Space URL is:

```text
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:

```bash
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:

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