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:

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

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

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>

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

{
  "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

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

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

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
• HF Spaces API Docs
• HF Authentication

💡 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