Skip to content

API.md

Latest commit

 

History

History
349 lines (272 loc) · 6.95 KB

API.md

File metadata and controls

349 lines (272 loc) · 6.95 KB

SPKIA API Documentation

Base URL

Development: http://localhost:8000
Production: https://api.spkia.org

Authentication

No authentication required. The service is publicly accessible.

Rate Limits

  • General API: 10 requests/second
  • Upload endpoint: 2 requests/second

Endpoints

1. Upload File for Verification

POST /api/verify

Upload a media file for authenticity verification.

Request:

  • Content-Type: multipart/form-data
  • Body: file (image or video file)

Response:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending"
}

Status Codes:

  • 200 OK: File accepted
  • 413 Payload Too Large: File exceeds 100MB limit
  • 400 Bad Request: Invalid file type
  • 500 Internal Server Error: Server error

cURL Example:

curl -X POST http://localhost:8000/api/verify \
  -F "file=@/path/to/image.jpg"

2. Verify URL

POST /api/verify-url

Verify a media file from a URL.

Request:

{
  "url": "https://example.com/image.jpg"
}

Response:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending"
}

Status Codes:

  • 200 OK: URL accepted
  • 400 Bad Request: Invalid URL or download failed
  • 413 Payload Too Large: File exceeds 100MB limit
  • 500 Internal Server Error: Server error

cURL Example:

curl -X POST http://localhost:8000/api/verify-url \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/image.jpg"}'

3. Get Verification Result

GET /api/verify/{job_id}

Retrieve verification results for a job.

Parameters:

  • job_id (path): Job identifier from upload response

Response (Processing):

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "reasons": [],
  "created_at": "2025-10-02T10:30:00Z",
  "updated_at": "2025-10-02T10:30:05Z"
}

Response (Completed - Authentic Camera):

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "label": "authentic_camera",
  "confidence": 0.95,
  "reasons": [
    "Valid sensor-PKI signature from Sony Alpha 7R V",
    "C2PA manifest verified"
  ],
  "details": {
    "c2pa": {
      "valid": true,
      "issuer": "Sony",
      "trust_chain_valid": true
    },
    "sensor_pki": {
      "valid": true,
      "manufacturer": "Sony",
      "camera_model": "Alpha 7R V",
      "sensor_id": "IMX989-12345",
      "signature_algorithm": "ES256"
    },
    "ml_detection": null
  },
  "created_at": "2025-10-02T10:30:00Z",
  "updated_at": "2025-10-02T10:30:08Z"
}

Response (Completed - AI Generated):

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "label": "likely_ai_generated",
  "confidence": 0.88,
  "reasons": [
    "ML classifiers indicate AI-generated (probability: 0.85)",
    "CNN detected high artifact probability",
    "PRNU pattern inconsistent with real camera"
  ],
  "details": {
    "c2pa": {
      "valid": false,
      "error": "No C2PA manifest found"
    },
    "sensor_pki": {
      "valid": false,
      "error": "No sensor-PKI signature found"
    },
    "ml_detection": {
      "ai_probability": 0.85,
      "cnn_score": 0.92,
      "prnu_score": 0.78,
      "metadata_anomaly_score": 0.65,
      "ensemble_confidence": 0.88,
      "detected_generator": "Stable Diffusion",
      "artifacts_found": [
        "CNN detected high artifact probability",
        "PRNU pattern inconsistent with real camera"
      ]
    }
  },
  "created_at": "2025-10-02T10:30:00Z",
  "updated_at": "2025-10-02T10:30:12Z"
}

Status Codes:

  • 200 OK: Results retrieved
  • 404 Not Found: Job not found
  • 500 Internal Server Error: Server error

cURL Example:

curl -X GET http://localhost:8000/api/verify/550e8400-e29b-41d4-a716-446655440000

Polling Recommendation: Poll every 2-3 seconds until status is completed or failed.

4. Delete Verification

DELETE /api/verify/{job_id}

Force immediate deletion of verification job and data.

Parameters:

  • job_id (path): Job identifier

Response:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "deleted": true,
  "message": "Job and associated data deleted successfully"
}

Status Codes:

  • 200 OK: Successfully deleted
  • 404 Not Found: Job not found
  • 500 Internal Server Error: Server error

cURL Example:

curl -X DELETE http://localhost:8000/api/verify/550e8400-e29b-41d4-a716-446655440000

5. Health Check

GET /health

Check service health status.

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2025-10-02T10:30:00Z",
  "database": "connected",
  "ml_models_loaded": true
}

Status Codes:

  • 200 OK: Service is healthy

cURL Example:

curl -X GET http://localhost:8000/health

6. Get Metrics

GET /api/metrics?days=7

Get aggregated anonymized metrics.

Parameters:

  • days (query, optional): Number of days to aggregate (default: 7)

Response:

{
  "total_verifications": 1523,
  "authentic_camera": 892,
  "authentic_c2pa": 245,
  "ai_generated": 312,
  "unknown": 74,
  "avg_processing_time": 1847.5
}

Status Codes:

  • 200 OK: Metrics retrieved

Data Models

VerificationStatus

type VerificationStatus = 'pending' | 'processing' | 'completed' | 'failed';

AuthenticityLabel

type AuthenticityLabel = 
  | 'authentic_camera'    // Sensor-PKI verified
  | 'authentic_c2pa'      // C2PA verified (no sensor-PKI)
  | 'likely_ai_generated' // ML detection > threshold
  | 'unknown'             // Inconclusive
  | 'error';              // Verification error

Confidence Score

  • Range: 0.0 to 1.0
  • Higher values indicate stronger confidence
  • authentic_camera typically: 0.95-0.98
  • authentic_c2pa typically: 0.85-0.92
  • likely_ai_generated typically: 0.70-0.95
  • unknown typically: 0.40-0.60

Error Responses

All error responses follow this format:

{
  "error": "Error message",
  "detail": "Detailed explanation (optional)",
  "job_id": "job_id (optional)"
}

Common Errors:

  • 400 Bad Request: Invalid request parameters
  • 404 Not Found: Resource not found
  • 413 Payload Too Large: File exceeds size limit
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server error

Best Practices

  1. Polling: Poll /api/verify/{job_id} every 2-3 seconds
  2. Cleanup: Call DELETE /api/verify/{job_id} after retrieving results
  3. File Size: Keep files under 100MB
  4. Rate Limiting: Respect rate limits (2 req/s for uploads)
  5. Error Handling: Implement retry logic with exponential backoff

Interactive API Documentation

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

Support