Safety & DetectionDeepfake Detection

Deepfake Detection

Analyze audio, images, and video for synthetic tampering. Submit media for detection and retrieve structured metrics and visualizations.

Media can be referenced by a public HTTPS url or by a media_token issued from the Secure Upload API. Use a secure upload when you prefer not to host the source file publicly — the API reads it once via the signed token, which expires 1 hour after issuance.

Request Schema

1interface DetectionRequest {
2  url?: string;          // publicly accessible media URL
3  media_token?: string;  // token from POST /secure_uploads (mutually exclusive with url)
4  callback_url?: string;
5  visualize?: boolean;
6  frame_length?: number;
7  start_region?: number;
8  end_region?: number;
9  max_video_secs?: number;
10  modality?: "audio" | "video" | "all"; // video only
11  face_only?: boolean;   // visual video analysis only; default false
12  intelligence?: boolean;
13  audio_source_tracing?: boolean;
14  use_reverse_search?: boolean; // image only
15  use_ood_detector?: boolean;
16  zero_retention_mode?: boolean;
17}

Face-only Video Analysis

Set face_only: true to focus visual video detection on faces by masking non-face regions before analysis. Face-only mode is effective only for video inputs that run visual analysis (modality: "all" or modality: "video"). Audio, image, and audio-only video requests are accepted, but their effective value is false.

Face-only mode does not disable audio analysis or select which video components run. Use modality for that. It also does not change billing or the structure of detection verdicts and reports. Detection responses expose the effective setting in face_only for auditing.

Response Shapes

1interface BaseDetectionResult {
2  success: true;
3  item: {
4    uuid: string;
5    created_at: string;
6    updated_at: string;
7    duration: string;
8    media_type: string;
9    status: string; // "processing" | "completed" | "failed"
10    face_only: boolean; // effective value for this detection
11    url?: string;
12    audio_url?: string; // alias of url
13    filename?: string;
14    zero_retention_mode: boolean;
15    file_deleted_at: string | null;
16    visualize?: boolean;
17    audio_source_tracing_enabled?: boolean;
18    use_ood_detector?: boolean;
19    extra_params?: object;
20    error_message?: string;
21    intelligence?: {
22      uuid?: string;
23      description: string | IntelligenceDetails | null;
24      created_at: string;
25      detect_uuid?: string;
26    } | null;
27    audio_source_tracing?: {
28      label: string;
29      error_message: string | null;
30    } | null;
31  };
32}
33
34interface AudioDetectionResult extends BaseDetectionResult {
35  item: BaseDetectionResult["item"] & {
36    metrics: {
37      label: string;
38      score: string[];
39      consistency: string;
40      aggregated_score: string;
41      image?: string;
42    };
43  };
44}
45
46interface ImageDetectionResult extends BaseDetectionResult {
47  item: BaseDetectionResult["item"] & {
48    image_metrics: {
49      type: string;
50      label: string;
51      image: string;
52      score: number;
53      children: any[];
54      ifl?: {
55        score: number;
56        heatmap: string;  // URL to heatmap visualization
57      };
58      reverse_image_search_sources?: Array<{ // present when use_reverse_search is enabled
59        url: string;
60        title: string;
61        reason: string;
62        verdict: string;  // e.g. "known_fake"
63        similarity: number;
64      }>;
65    };
66  };
67}
68
69interface VideoDetectionResult extends BaseDetectionResult {
70  item: BaseDetectionResult["item"] & {
71    metrics: AudioDetectionResult["item"]["metrics"];
72    video_metrics: {
73      label: string;
74      score: number;
75      certainty: number;
76      treeview?: string;
77      children: Array<{
78        type: string;
79        conclusion: string;
80        score: number;
81        certainty: number;
82        "certainty (%)": string;
83        children: Array<{
84          type: string;
85          conclusion: string;
86          score: number;
87          certainty: number;
88          "certainty (%)": string;
89          timestamp: number;
90          children: Array<{
91            type: string;
92            conclusion: string;
93            score: number;
94            certainty: number;
95            "certainty (%)": string;
96          }>;
97        }>;
98      }>;
99    };
100  };
101}
FieldTypeDescription
pipelinestring | nullDeprecated field that may appear on older image/video detects returned by the API. Ignored for new detections.

Use the endpoints below to submit jobs and retrieve detection results for each modality.