API_USAGE.md

# 🔌 API Usage Guide - Hugging Face Spaces

Sur Hugging Face Spaces, **seul Gradio est exposé publiquement**. L'API FastAPI (port 8000) n'est pas accessible depuis l'extérieur.

**Mais Gradio expose automatiquement une API REST native!** 🎉

## 📡 Accéder à l'API depuis l'extérieur

### Option 1: API Gradio Native (Recommandé)

Gradio expose automatiquement une API REST à l'endpoint `/api/predict`.

#### Python avec `gradio_client`:

```python
from gradio_client import Client

# Remplacez par votre Space URL
client = Client("AI-DrivenTesting/CU1-X")

# Appeler l'API
result = client.predict(
    "screenshot.png",           # image (filepath or PIL Image)
    0.35,                       # confidence_threshold (float)
    2,                          # thickness (int)
    True,                       # enable_clip (bool)
    True,                       # enable_ocr (bool)
    False,                      # enable_blip (bool)
    False,                      # ocr_only (bool)
    "Only image & button",      # blip_scope (str)
    False,                      # preprocess (bool)
    "RF-DETR Optimized (Recommended)",  # preprocess_mode (str)
    "standard",                 # preprocess_preset (str)
    api_name="/predict"
)

# Résultat: (annotated_image, summary, detections_json)
annotated_image, summary, detections_json = result
print(detections_json)
```

#### REST API (curl):

```bash
# Pour un Space public
curl -X POST "https://AI-DrivenTesting-CU1-X.hf.space/api/predict" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      "screenshot.png",  # Base64 encoded image or URL
      0.35,
      2,
      true,
      true,
      false,
      false,
      "Only image & button",
      false,
      "RF-DETR Optimized (Recommended)",
      "standard"
    ]
  }'
```

**Note:** Pour les images, vous devez soit:
- Utiliser une URL publique vers l'image
- Encoder l'image en base64
- Utiliser `gradio_client` qui gère ça automatiquement

#### REST API avec Python `requests`:

```python
import requests
import base64
from PIL import Image
import io

# Encoder l'image en base64
def image_to_base64(image_path):
    with open(image_path, "rb") as f:
        return base64.b64encode(f.read()).decode()

# Appeler l'API
url = "https://AI-DrivenTesting-CU1-X.hf.space/api/predict"
image_b64 = image_to_base64("screenshot.png")

response = requests.post(
    url,
    json={
        "data": [
            f"data:image/png;base64,{image_b64}",
            0.35,
            2,
            True,
            True,
            False,
            False,
            "Only image & button",
            False,
            "RF-DETR Optimized (Recommended)",
            "standard"
        ]
    },
    timeout=120
)

result = response.json()
print(result)
```

### Option 2: API FastAPI (Interne uniquement)

L'API FastAPI sur le port 8000 **n'est PAS accessible depuis l'extérieur** du Space HF.

Elle fonctionne uniquement:
- ✅ En local (`python app.py`)
- ✅ Entre les processus internes du Space
- ❌ **PAS depuis l'extérieur du Space**

## 🔑 Authentification

### Spaces Publics
- Aucune authentification requise
- API accessible directement

### Spaces Privés
- Nécessite un token Hugging Face
- Ajoutez le header: `Authorization: Bearer <HF_TOKEN>`

```python
from gradio_client import Client

client = Client(
    "AI-DrivenTesting/CU1-X",
    hf_token="your_hf_token_here"  # Pour les Spaces privés
)
```

## 📊 Paramètres de l'API

| Paramètre | Type | Description | Valeur par défaut |
|-----------|------|-------------|-------------------|
| `image` | file/str | Image à analyser | - |
| `confidence_threshold` | float | Seuil de confiance (0.1-0.9) | 0.35 |
| `thickness` | int | Épaisseur des boîtes (1-6) | 2 |
| `enable_clip` | bool | Activer classification CLIP | False |
| `enable_ocr` | bool | Activer extraction OCR | True |
| `enable_blip` | bool | Activer descriptions BLIP | False |
| `ocr_only` | bool | Mode OCR seul (skip detection) | False |
| `blip_scope` | str | Portée BLIP ("Only image & button" ou "All elements") | "Only image & button" |
| `preprocess` | bool | Activer preprocessing | False |
| `preprocess_mode` | str | Mode preprocessing | "RF-DETR Optimized (Recommended)" |
| `preprocess_preset` | str | Preset preprocessing | "standard" |

## 📝 Format de Réponse

```json
{
  "annotated_image": "base64_encoded_image",
  "summary": "Markdown summary text",
  "detections_json": {
    "success": true,
    "detections": [...],
    "total_detections": 10,
    "image_size": {"width": 1080, "height": 1920},
    "parameters": {...},
    "type_distribution": {...}
  }
}
```

## 🚀 Exemples Complets

### Exemple 1: Détection Simple

```python
from gradio_client import Client

client = Client("AI-DrivenTesting/CU1-X")

result = client.predict(
    "screenshot.png",
    0.35, 2, False, True, False, False, "Only image & button",
    False, "RF-DETR Optimized (Recommended)", "standard",
    api_name="/predict"
)

annotated_image, summary, detections = result
print(f"Found {detections['total_detections']} elements")
```

### Exemple 2: Détection Complète avec CLIP

```python
result = client.predict(
    "screenshot.png",
    0.35, 2, True, True, False, False, "Only image & button",
    False, "RF-DETR Optimized (Recommended)", "standard",
    api_name="/predict"
)
```

### Exemple 3: OCR Seulement

```python
result = client.predict(
    "screenshot.png",
    0.35, 2, False, True, False, True, "Only image & button",
    False, "RF-DETR Optimized (Recommended)", "standard",
    api_name="/predict"
)
```

## ⚠️ Limitations HF Spaces

1. **Timeout:** 60 secondes par défaut (peut être augmenté dans Settings)
2. **Mémoire:** Limite selon le hardware choisi
3. **CPU/GPU:** Performance dépend du hardware sélectionné
4. **API FastAPI:** Non accessible depuis l'extérieur

## 🔗 Liens Utiles

- [Gradio Client Docs](https://www.gradio.app/guides/getting-started-with-the-python-client)
- [HF Spaces API Docs](https://huggingface.co/docs/hub/spaces-sdks-gradio#api-tab)
- [HF Authentication](https://huggingface.co/docs/hub/security-tokens)

## 💡 Tips

- Utilisez `gradio_client` pour une meilleure gestion des images
- Pour les gros fichiers, utilisez des URLs publiques
- Activez le preprocessing pour des résultats cohérents sur différents devices
- Mode OCR-only est plus rapide si vous voulez juste le texte