docs/api.md

API Reference — Verify Backend

Base URL : http://localhost:8000

Swagger interactif : http://localhost:8000/docs

Endpoints transverses

Méthode	Route	Description
GET	/	Liste de tous les modules et leurs endpoints
GET	/health	Status global (tous les modules)
GET	/docs	Swagger UI (OpenAPI 3)

Endpoints par module

Toutes les routes d'analyse retournent du JSON. Les réponses contiennent un champ verdict (texte court, ex: "FAKE"/"REAL"/"MISLEADING"), un champ confidence_pct (entier 0-100), une explanation en anglais clair, et un sous-objet xai avec des heatmaps en base64 PNG.

io1 — Fake Media Detection

GET  /api/io1/health
POST /api/io1/analyze/image       # multipart: image=<file>, mode=auto|deepfake|ai
POST /api/io1/analyze/video       # multipart: video=<file>

Modes :

• auto (défaut) : détecte un visage et route vers deepfake ; sinon vers AI-image
• deepfake : force la détection face-deepfake (refuse si aucun visage trouvé)
• ai : force la détection AI-image (whole image), avec escalation 2-détecteurs

Réponse (extrait) :

{
  "verdict": "FAKE",
  "verdict_label": "AI-generated image",
  "confidence_pct": 97,
  "prob_fake": 0.97, "prob_real": 0.03,
  "task": "image_ai_generated",
  "face_detected": true, "face_box": [x, y, w, h],
  "model_used": "io1_resnet50.pth + AI-image consensus",
  "xai": { "gradcam_overlay": "<base64 PNG>", "face_crop": "<base64>" },
  "explanation": "Two independent AI-image classifiers agree...",
  "narrative": { "headline": "AI-generated image", "summary": "...", "signals": [...] }
}

io2 — Visual Manipulation / Persuasion

GET  /api/io2/health
POST /api/io2/analyze/image       # multipart: image=<file>
POST /api/io2/analyze/video       # multipart: video=<file>  (analyse la 1ère frame)

Verdicts : AUTHENTIC · SUSPECT · MANIPULATIVE · HIGHLY MANIPULATIVE

Réponse (extrait) :

{
  "score_global": 0.73,
  "label": "MANIPULATIVE", "label_color": "#F97316",
  "scores_modules": { "nlp": 0.85, "clickbait": 0.61, "urgence": 0.95, "manipnet": 0.73 },
  "texte": { "extrait": "LIMITED TIME ONLY", "tone": "alarmist", "label_nlp": "Manipulator" },
  "techniques": ["limited-time", "percent-off", "fomo"],
  "bounding_boxes": [{"class": "limited-time", "score": 0.9, "box": [120, 30, 280, 70]}],
  "xai": { "bbox_overlay": "<base64>", "gradient_saliency": "<base64>" }
}

io3 — Image↔Caption Coherence

GET  /api/io3/health
POST /api/io3/analyze/image       # multipart: image=<file>, text=<caption>
POST /api/io3/analyze/video       # multipart: video=<file>, text=<caption>

Verdicts : COHERENT (≥0.25) · SUSPECT (0.15-0.25) · INCOHERENT (<0.15)

Réponse (extrait) :

{
  "verdict": "INCOHERENT",
  "score_global": 0.11,
  "scores": { "clip": 0.18, "sam": 0.22, "whisper": 0.5, "yolo": 0.0, "ocr": 0.0 },
  "objects_detected": ["dog", "person"],
  "ocr_text": "Welcome to the park",
  "xai": { "gradcam_base64": "<...>", "waterfall_base64": "<...>", "shap": { ... } }
}

io4 — Image Tampering (Photoshop forensics)

GET  /api/io4/health
POST /api/io4/analyze/image       # multipart: image=<file>
POST /api/io4/analyze/compare     # multipart: image=<suspect>, reference=<original>

Verdicts : AUTHENTIC · FAKE (sous-classe : Inpainting · Copy-move · Splicing · Enhancement)

Réponse (extrait) :

{
  "verdict": "FAKE", "verdict_class": "Splicing",
  "predicted_class": "Splicing", "max_confidence": 0.78,
  "region": "top right",
  "ela_score": 0.67, "noise_score": 0.55, "jpeg_ghost_score": 0.42,
  "fused_score": 0.61, "signals_agreement": 2,
  "clues": ["ELA shows a compact bright patch", "JPEG ghost detected at quality 75"],
  "xai": { "tamper_mask_overlay": "<base64>", "gradcam_overlay": "<base64>" }
}

io5 — Caption Fidelity

GET  /api/io5/health
POST /api/io5/analyze             # multipart: file=<image>, text=<caption>

Verdicts : FAITHFUL · PARTIAL · MISLEADING

Réponse (extrait) :

{
  "verdict": "MISLEADING", "verdict_color": "#E53E3E",
  "score": 0.21, "confidence": 0.92,
  "raw_clip_similarity": 0.13, "calibrated_similarity": 0.14,
  "ocr_overlap": 0.0, "tone_gap": 0.55,
  "phrase_breakdown": [
    {"phrase": "UFO landing white house", "score": 0.08, "supported": false}
  ],
  "unsupported_phrases": ["UFO landing white house", "Breaking news"],
  "xai": { "clip_saliency": "<base64>" }
}

io6 — Cosmetic Ads Fact-Check

GET  /api/io6/health
POST /api/io6/analyze/video       # multipart: video=<file>  (vidéo MP4 d'une pub cosmétique)

Verdicts : RELIABLE (trust_score≥50) · MISLEADING (<50)

Réponse (extrait) :

{
  "global_verdict": "MISLEADING", "trust_score": 32.4,
  "transcript": "L'Oréal Revitalift reduces wrinkles by 40% in 7 days...",
  "language": "en",
  "claims": [
    {
      "claim": "reduces wrinkles by 40% in 7 days",
      "verdict": "FALSE", "confidence": 0.9, "severity": "high",
      "evidence": [
        {"source": "Decisive_PostProcessor", "rule_type": "FAUX_pattern",
         "description": "Time-bound claim without substantiation", "eu_article": "EU 655/2013 art. 4.4"}
      ],
      "eu_articles": ["EU 655/2013 art. 4.4", "EU 655/2013 art. 4.2"]
    }
  ],
  "stats": { "total": 8, "n_true": 3, "n_false": 4, "n_to_verify": 1 },
  "eu_articles_cited": ["EU 655/2013 art. 4.2", "EU 655/2013 art. 4.4"]
}

Codes HTTP

Code	Sens
200	OK — réponse JSON
400	Bad request — input manquant ou format invalide (ex: io5 sans text)
500	Erreur interne du pipeline — détails dans le message
503	Module pas encore prêt (en cours de chargement initial)

CORS

L'API autorise tous les origines (Access-Control-Allow-Origin: *) pour faciliter le développement avec Live Server. En production, restreindre à votre domaine via le middleware FastAPI.