API Documentation

Complete guide to integrate FrameSentinel fraud detection

Quick Start

1. Get Your API Key

env

"color: #79c0ff">API_KEY=your-api-key-here
"color: #79c0ff">API_URL=https://framesentinel-341068003893.europe-west3.run.app

2. Install SDK

TypeScript/JavaScript:

bash

npm install @framesentinel/sdk

Python:

bash

pip install framesentinel

3. Basic Usage

typescript

import { FrameSentinelClient } from ' @framesentinel/sdk';

const client = new FrameSentinelClient({
  apiKey: ' your-api-key',
  apiUrl: ' https://framesentinel-341068003893.europe-west3.run.app'
});

// Create verification session
const session = await client.createSession(' user-123');

// Upload video
await client.uploadVideo(session.session_id, videoFile);

// Get results
const result = await client.pollUntilComplete(session.session_id);

console.log(' Risk Level:', result.risk_level);
console.log(' Score:', result.authenticity_score);

API Endpoints

POST/api/v1/sessions

Create a new verification session

Request:

json

{
  "user_id": "user-123",
  "metadata": {
    "ip_address": "192.168.1.1"
  }
}

Response:

json

{
  "session_id": "sess_abc123",
  "state": "PENDING",
  "created_at": "2024-01-15T10:30:00Z"
}

POST/api/v1/sessions/{id}/upload

Upload video for analysis

Request:

json

multipart/form-data with video file

Response:

json

{
  "session_id": "sess_abc123",
  "state": "PROCESSING",
  "upload_complete": true
}

GET/api/v1/sessions/{id}/result

Get verification results

Request:

json

No body required

Response:

json

{
  "session_id": "sess_abc123",
  "state": "COMPLETED",
  "authenticity_score": 0.95,
  "risk_level": "VERIFIED",
  "detection_flags": {
    "deepfake_detected": false,
    "replay_detected": false,
    "injection_detected": false,
    "face_swap_detected": false,
    "metadata_anomaly": false
  }
}

Authentication

All API requests require authentication using your API key in the header:

http

#79c0ff">X-API-Key: your-api-key-here

Keep your API key secure. Never expose it in client-side code or public repositories.

Risk Scoring & Decision Logic

FrameSentinel analyzes videos through 5 parallel detection modules and calculates an authenticity score (0-100%). The system automatically categorizes results into risk levels to guide your decision-making.

Risk Levels

85-100%

VERIFIED

Approve

Video is authentic with high confidence. All detection modules passed. Safe to proceed with verification.

70-84%

REVIEW

Manual Review

Minor anomalies detected. Requires human analyst review before making final decision.

50-69%

SUSPICIOUS

Likely Reject

Multiple fraud indicators detected. High probability of manipulation. Recommend rejection unless strong evidence suggests otherwise.

0-49%

REJECTED

Reject

Strong fraud signals detected across multiple modules. Video is likely fake or manipulated. Reject verification immediately.

Detection Modules

Each video is analyzed by 5 specialized AI modules running in parallel:

Deepfake Detection

Identifies AI-generated or synthetically modified faces using deep learning models

Replay Attack Detection

Detects videos recorded from screens or pre-recorded content being played back

Injection Detection

Identifies videos injected into the camera stream via virtual cameras or software

Face Swap Detection

Detects face replacement techniques and morphing attacks

Metadata Integrity

Analyzes video file metadata for signs of tampering or manipulation

How Scores Are Calculated

Frame Analysis: System extracts up to 15 frames evenly distributed across the video
Parallel Detection: All 5 modules analyze each frame simultaneously (2-4 seconds total)
Detection Rate: Calculates percentage of frames flagged by each module
Score Reduction: Each detection reduces the authenticity score proportionally
Final Score: Combines all module results into single authenticity score (0-100%)

Example Response

json

{
  "session_id": "sess_abc123",
  "state": "COMPLETED",
  "authenticity_score": 0.42,  // 42% - REJECTED
  "risk_level": "REJECTED",
  "detection_flags": {
    "deepfake_detected": true,   // AI-generated face detected
    "replay_detected": false,
    "injection_detected": true,  // Virtual camera detected
    "face_swap_detected": false,
    "metadata_anomaly": true     // File metadata tampered
  },
  "frame_timeline": [
    {
      "frame_number": 5,
      "timestamp": 0.167,
      "flags": ["deepfake", "injection"],
      "confidence": 0.89
    }
  ],
  "processed_at": "2024-01-15T10:30:45Z"
}

Error Codes

400

Bad Request

Invalid request parameters

401

Unauthorized

Invalid or missing API key

403

Forbidden

API key lacks required permissions

404

Not Found

Session not found

413

Payload Too Large

Video exceeds 100MB limit

429

Too Many Requests

Rate limit exceeded (100 req/min)

500

Internal Server Error

Server error, contact support