Spaces:
Running
Running
File size: 4,060 Bytes
ff55461 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 | # BitCheck Image Verification API Integration Guide
This document outlines the endpoints available in the BitCheck Image Verification API to help backend engineers integrate the image analysis features.
## Base URL
The API is typically hosted at `http://localhost:8000` locally, or the appropriate production URL (e.g., your Hugging Face Space URL).
---
## Endpoints
### 1. Verify Image
Analyze an uploaded image for AI generation, forensics, and metadata/provenance.
**Endpoint:** `POST /verify/image`
**Content-Type:** `multipart/form-data`
**Request Parameters (Form Data):**
- `file` **(Required)**: The image file to analyze (e.g., `.jpg`, `.png`, `.webp`).
- `user_email` *(Optional)*: Email address of the user who owns this image and report. Useful for retrieving reports later.
- `run_explainability` *(Optional, Default: true)*: Generate a Grad-CAM heatmap showing which parts of the image influenced the AI prediction.
- `run_ocr` *(Optional, Default: true)*: Run OCR to detect visible AI tool watermarks.
- `run_forensics` *(Optional, Default: true)*: Run lightweight forensic analysis (noise, blur, edge inconsistencies).
- `run_c2pa` *(Optional, Default: true)*: Analyze C2PA provenance data (Content Credentials).
- `threshold` *(Optional)*: Override the default confidence threshold for the classifier model.
**cURL Example:**
```bash
curl -X POST "http://localhost:8000/verify/image" \
-H "accept: application/json" \
-H "Content-Type: multipart/form-data" \
-F "file=@/path/to/your/image.jpg" \
-F "user_email=user@example.com"
```
**Success Response (200 OK):**
Returns a comprehensive `VerificationReport` JSON object containing:
- `verification_id`: A unique ID for this report.
- `status`: Verification status (`completed`, `error`).
- `trust`: The final trust score and classification (e.g., `real`, `ai_generated`).
- Sections for `input`, `filename_analysis`, `metadata`, `provenance`, `visible_watermark_ocr`, `visible_watermark_template`, `classifier`, `forensics`, and `explainability`.
---
### 2. Retrieve a Specific Report
Fetch a previously generated verification report by its ID.
**Endpoint:** `GET /reports/{verification_id}`
**Path Parameters:**
- `verification_id` **(Required)**: The unique ID returned from the `/verify/image` endpoint.
**cURL Example:**
```bash
curl -X GET "http://localhost:8000/reports/b8f9e..." \
-H "accept: application/json"
```
**Success Response (200 OK):**
Returns the same `VerificationReport` JSON object generated during the upload.
---
### 3. List Reports
Retrieve a list of past verification reports, optionally filtered by user email.
**Endpoint:** `GET /reports`
**Query Parameters:**
- `user_email` *(Optional)*: Filter the reports by the user's email address.
**cURL Example:**
```bash
curl -X GET "http://localhost:8000/reports?user_email=user@example.com" \
-H "accept: application/json"
```
**Success Response (200 OK):**
```json
{
"count": 1,
"reports": [
{
"verification_id": "...",
"user_email": "user@example.com",
"filename": "image.jpg",
"status": "completed",
"trust": {
"final_decision": "real",
"trust_score_out_of_100": 95,
...
},
"processing_time_ms": 1205.4
}
]
}
```
---
### 4. Health Check
Check if the API and its underlying services (OCR, C2PA, AI Models) are running correctly.
**Endpoint:** `GET /health`
**cURL Example:**
```bash
curl -X GET "http://localhost:8000/health" \
-H "accept: application/json"
```
**Success Response (200 OK):**
```json
{
"status": "ok",
"service": "BitCheck Image Verification API",
"classifier_loaded": true,
"ocr_available": true,
"c2pa_available": true,
"device": "cpu"
}
```
---
## Static Assets (Explainability & Forensics)
If `run_explainability` or `run_forensics` are true, the JSON response will include URLs to generated images (e.g., heatmaps or annotated images). These are served via the static `/outputs/` directory.
Example: `http://localhost:8000/outputs/b8f9e..._gradcam_overlay.jpg`
|