README.md

---
title: SW Fish Identifier
emoji: 🐟
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
pinned: false
---

# SW Fish Identifier

Upload a photo and SWClassifier will detect every fish in it, segment their outline,
and identify the species — returning both the common name and scientific name.

## Pipeline

| Step | Model | Notes |
|---|---|---|
| Detection | YOLO v8 nano | Bounding boxes |
| Segmentation | FPN ResNet-18 | Per-fish polygon mask |
| Classification | BEiT v2 Base + FAISS kNN | 775 species |

## API

The Space exposes a REST API alongside the web UI.

### Identify fish in an image

```
POST /api/v1/predict
X-API-Key: <your-key>
Content-Type: multipart/form-data

file=<image>
```

**Response**

```json
{
  "detections": [
    {
      "bbox": { "x1": 120, "y1": 45, "x2": 380, "y2": 290, "confidence": 0.91 },
      "polygon": [[120, 180], [135, 170], "..."],
      "predictions": [
        { "name": "Wahoo", "taxon": "Acanthocybium solandri", "accuracy": 0.87, "species_id": "..." }
      ]
    }
  ],
  "image_size": { "width": 1280, "height": 720 },
  "timing": { "detect_ms": 210, "segment_ms": 85, "classify_ms": 430, "total_ms": 730 }
}
```

Full interactive docs available at `/api/docs`.

## Configuration (Space Secrets)

| Secret | Description |
|---|---|
| `SW_API_KEYS` | Comma-separated list of valid API keys |
| `SW_ADMIN_KEY` | Key required to create / revoke API keys via `/api/v1/keys` |

Set these under **Settings → Variables and Secrets** in the Space dashboard.
If not set, keys are auto-generated at startup (lost on container restart).