Deepfake Detection

interface DetectionRequest {
  url?: string;          // publicly accessible media URL
  media_token?: string;  // token from POST /secure_uploads (mutually exclusive with url)
  callback_url?: string;
  visualize?: boolean;
  frame_length?: number;
  start_region?: number;
  end_region?: number;
  max_video_secs?: number;
  modality?: "audio" | "video" | "all"; // video only
  face_only?: boolean;   // visual video analysis only; default false
  intelligence?: boolean;
  detect_watermark?: boolean; // single-file audio/image/video only; default false
  audio_source_tracing?: boolean;
  use_reverse_search?: boolean; // image only
  use_ood_detector?: boolean;
  zero_retention_mode?: boolean;
}

interface DetectIntelligenceResult {
  uuid: string;
  status: "processing" | "completed" | "failed";
  error_message: string | null;
  description: string | IntelligenceDetails | null;
  created_at: string;
  detect_uuid: string;
}
interface DetectWatermarkResult {
  status: "pending" | "processing" | "completed" | "failed";
  metrics?: object;       // Resemble detector metrics plus optional synthid boolean
  error_message?: string; // present only when the watermark analysis failed
}
interface BaseDetectionResult {
  success: true;
  item: {
    uuid: string;
    created_at: string;
    updated_at: string;
    duration: string;
    media_type: string;
    status: string; // "processing" | "completed" | "failed"
    face_only: boolean; // effective value for this detection
    url?: string;
    audio_url?: string; // alias of url
    filename?: string;
    zero_retention_mode: boolean;
    file_deleted_at: string | null;
    visualize?: boolean;
    audio_source_tracing_enabled?: boolean;
    use_ood_detector?: boolean;
    extra_params?: object;
    error_message?: string;
    // GET /detect/{uuid}?experts=true returns an array; other responses use one result.
    intelligence?: DetectIntelligenceResult | DetectIntelligenceResult[] | null;
    // Present only when detect_watermark=true was requested.
    watermark?: DetectWatermarkResult;
    audio_source_tracing?: {
      label: string;
      error_message: string | null;
    } | null;
  };
}
interface AudioDetectionResult extends BaseDetectionResult {
  item: BaseDetectionResult["item"] & {
    metrics: {
      label: string;
      score: string[];
      consistency: string;
      aggregated_score: string;
      image?: string;
    };
  };
}
interface ImageDetectionResult extends BaseDetectionResult {
  item: BaseDetectionResult["item"] & {
    image_metrics: {
      type: string;
      label: string;
      image: string;
      score: number;
      children: any[];
      ifl?: {
        score: number;
        heatmap: string;  // URL to heatmap visualization
      };
      reverse_image_search_sources?: Array<{ // present when use_reverse_search is enabled
        url: string;
        title: string;
        reason: string;
        verdict: string;  // e.g. "known_fake"
        similarity: number;
      }>;
    };
  };
}
interface VideoAttackType {
  code: string;  // e.g. "F1"
  name: string;  // e.g. "Face swap"
  prob: number;  // 0-1; the entries in one list sum to 1
}
interface VideoDetectionResult extends BaseDetectionResult {
  item: BaseDetectionResult["item"] & {
    metrics: AudioDetectionResult["item"]["metrics"];
    video_metrics: {
      label: string;
      score: number;
      certainty: number;
      treeview?: string;
      children: Array<{        // VideoResult
        type: string;
        conclusion: string;
        score: number;
        certainty: number;
        "certainty (%)": string;
        attack?: VideoAttackType[]; // only when scored fake; highest prob first
        children: Array<{      // VideoChunkResult, one per analyzed window
          type: string;
          conclusion: string;
          score: number;
          certainty: number;
          "certainty (%)": string;
          chunk_index: number;
          start_time: number;  // seconds
          end_time: number;    // seconds
          attack?: VideoAttackType[]; // only when this chunk is scored fake
          children: Array<{    // VideoFrameResult
            type: string;
            conclusion: string;
            score: number;
            certainty: number;
            "certainty (%)": string;
            timestamp: number;
            children?: Array<{
              type: string;
              conclusion: string;
              score: number;
              certainty: number;
              "certainty (%)": string;
            }>;
          }>;
        }>;
      }>;
    };
  };
}