API
The server exposes three endpoints. The contract is stable and shared by the web app and the Android app.
| Method | Path | Notes |
|---|---|---|
| GET | /api/health | status, checkpoint, max_upload_bytes |
| POST | /api/predict?stage=0 | multipart field file (PNG, JPG, TIFF, max 20 MB). stage 0 to 4. |
| GET | /api/report | evaluation.json, or 404 when no evaluation has been run |
Response fields
| Field | Description |
|---|---|
prediction | Shape and Gram labels with confidence values |
stage_index, stage_name, stage_title | The selected stage |
stage_names | The five stage keys in order |
panel | The selected stage as a base64 PNG |
panels | All five stages as base64 PNGs |
notes_text | English notes about the result |
disclaimer | The fixed low-confidence warning |
failed_stages | Stages that could not be produced |
Examples
curl -X POST "$API/api/predict?stage=3" \
-F "file=@sample.png"import requests
with open("sample.png", "rb") as f:
r = requests.post("http://localhost:8000/api/predict", params={"stage": 3}, files={"file": f})
r.raise_for_status()
data = r.json()
print(data["prediction"]["shape_label"], data["prediction"]["gram_label"])const form = new FormData();
form.append("file", fileInput.files[0]);
const res = await fetch("http://localhost:8000/api/predict?stage=3", { method: "POST", body: form });
const data = await res.json();Browsers can only call the API from origins listed in CORS_ORIGINS. Calls from curl or from a server are not affected.
Errors
Errors return JSON with a detail field. 400 invalid file or stage, 413 file too large, 415 unsupported file type, 429 too many requests (rate limit, see the Retry-After header), 500 unexpected failure, 503 model not ready.