Introduction

The DeepID API provides powerful tools for detecting deepfakes in images, videos, and audio files. This guide will walk you through the process of authenticating, uploading files, processing them, and retrieving results using curl commands. By following this guide, you'll be able to integrate deepfake detection capabilities into your own applications or workflows.

Prerequisites

Before you begin, ensure you have:

• A DeepID account and API key

• curl installed on your system (version 7.68.0 or later recommended)

• A media file (image, video, or audio) to analyze

• Basic familiarity with command-line interfaces and RESTful APIs

Authentication

Every API request to DeepID requires authentication using the HTTP Bearer scheme with your API token. This ensures that only authorized users can access the API and helps maintain the security of the service.

First, let's set your API key as an environment variable for easy access:

# Set your API key as an environment variable
export DEEPID_API_KEY="your_api_key_here"

Replace "your_api_key_here" with the actual API key you obtained from the DeepID dashboard. By setting it as an environment variable, you can easily reference it in subsequent curl commands without exposing it directly in your scripts.

For enhanced security, DeepID allows you to generate a short-lived session token. This token is valid for 1 hour and can be used instead of your main API key for temporary access:

curl -X GET "https://api.deepidentify.ai/user/token/session" \
     -H "Authorization: Bearer $DEEPID_API_KEY"

This command will return a session token. You should store this token securely and use it for subsequent requests within the next hour.

If your session token expires, you can refresh it using the following command:

curl -X POST "https://api.deepidentify.ai/user/token/refresh" \
     -H "Authorization: Bearer $DEEPID_API_KEY"

This will provide you with a new session token, extending your ability to make API calls without using your main API key.

Fetching Available Models

Before processing any files, it's crucial to understand which detection models are available and their capabilities. DeepID offers various models optimized for different types of media and detection scenarios.

To retrieve the list of available models, use the following command:

curl -X GET "https://api.deepidentify.ai/models" \
     -H "Authorization: Bearer $DEEPID_API_KEY"

This request will return a JSON response containing detailed information about each available model, including:

• Model ID: A unique identifier for the model

• Supported modalities: The types of media the model can analyze (e.g., audio, video, image, text)

• Description: A brief explanation of the model's capabilities and best use cases

• Version: The current version of the model

Review this information carefully to choose the most appropriate model for your specific use case. Some models might be optimized for speed, while others prioritize accuracy or specialize in certain types of deepfakes.

Uploading Files

Before you can analyze media for deepfakes, you need to upload the files to DeepID's servers. This is done using a multipart/form-data POST request to the /file/uploadS3 endpoint.

Here's how to upload a file:

curl -X POST "https://api.deepidentify.ai/file/uploadS3" \
     -H "Authorization: Bearer $DEEPID_API_KEY" \
     -H "Content-Type: multipart/form-data" \
     -F "file=@/path/to/your/file.mp4"

Replace /path/to/your/file.mp4 with the actual path to the file you want to analyze. This command will:

1. Authenticate your request using your API key

2. Set the correct content type for file uploading

3. Send the file as form data to the DeepID servers

After a successful upload, the API will respond with a JSON object containing the uploaded file's filename. This filename is crucial as you'll need it in the next step to process the file. Make sure to note it down or store it in a variable.

For example, the response might look like this:

{
  "filename": "uploaded_1234567890.mp4"
}

Processing Files

Once your file is uploaded, you can submit it for deepfake analysis. DeepID offers both synchronous and asynchronous processing options. For this guide, we'll use the asynchronous method, which is better suited for larger files or when you're processing multiple files.

To initiate the processing of an uploaded file, use the following command:

curl -X POST "https://api.deepidentify.ai/v2/file/process" \
     -H "Authorization: Bearer $DEEPID_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "modalities": ["video"],
           "mode": "async",
           "s3Location": "uploaded_filename.mp4"
         }'

Let's break down the components of this request:

• modalities: An array specifying which aspects of the file to analyze. Options include "video", "audio", "image", and "text".

• mode: Set to "async" for asynchronous processing.

• s3Location: The filename returned from the upload step.

You can customize this request further by specifying additional parameters such as:

• modelId: To use a specific detection model (if omitted, DeepID will use the default model)

• callbackEmail: An email address to receive notifications when processing is complete

• visualize: Set to true to generate visual representations of the detection results

The API will respond with a JSON object containing a unique file ID. This ID is crucial for tracking the processing status and retrieving results. The response might look like this:

{
  "id": "1234abcd5678efgh"
}

Store this ID securely as you'll need it to check the processing status and retrieve results.

Tracking Processing Status and Retrieving Results

After submitting a file for processing, you need to periodically check its status until the analysis is complete. Follow these steps to track the status and retrieve the results:

1. Use the /file/status/{file_id} endpoint to check the status

   bashCopy code
   curl -X GET "https://api.deepidentify.ai/file/status/{file_id}" \
        -H "Authorization: Bearer $DEEPID_API_KEY"

   Replace {file_id} with the ID you received from the processing step.
   
   

2. Interpret the status response

   • "QUEUED" or "PROCESSING": The analysis is not yet complete. Wait and check again in a few minutes.

   • "ERROR": An error occurred. Check your input and try processing the file again.

   • "RESULTS" or "PROCESSED": The analysis is complete, and results are available.
     
     

3. If the status is "RESULTS" or "PROCESSED"

   The JSON response will include the deepfake detection results. Here's an example:

   {
     "status": "RESULTS",
     "results": {
       "image": 0.057647853404910014
     }
   }

   
   

4. Analyze the result

   • The value associated with "image" (or the relevant modality you processed) represents the probability of the media being a deepfake.

   • This probability is a float between 0 and 1, where values closer to 0 indicate a lower likelihood of manipulation, and values closer to 1 indicate a higher likelihood.
     
     

5. Interpret the probability

   • Low probability (e.g., < 0.3): The media is likely authentic.

   • Medium probability (e.g., 0.3 - 0.7): Exercise caution; the media might have been manipulated.

   • High probability (e.g., > 0.7): Consider the media likely to be a deepfake.

Remember: Once you receive a "RESULTS" or "PROCESSED" status, the analysis is complete. There's no need to keep checking the status for this file ID. You can now use these results in your application or proceed to analyze another file.

By following these steps, you'll efficiently track the processing status and retrieve the final results of your deepfake analysis.

Next Steps

Congratulations on making your first DeepID API requests! You've taken the first step towards leveraging advanced deepfake detection in your projects. Here's how you can build on this foundation:

1. Explore Advanced Features

   • Experiment with different modalities and detection settings to fine-tune your results.

   • Try processing various types of media (images, videos, audio) to understand the API's capabilities fully.

   • Explore the batch processing endpoint (/file/process/batch) for efficiently handling multiple files.
     
     

2. Enhance Your Implementation

   • Implement robust error handling in your API calls to manage rate limits, network issues, and other potential problems.

   • Develop a logging system to track your API usage and monitor the performance of your deepfake detection processes.

   • Create scripts or a simple application to automate the entire process from upload to result analysis.
     
     

3. Integrate and Innovate

   • Incorporate DeepID API results into your existing applications or workflows. For example, you could build a content moderation system that uses deepfake detection as part of its verification process.

   • Develop new tools or services based on deepfake detection capabilities, such as a browser extension that analyzes images and videos on social media platforms.

   • Combine DeepID's results with other AI services or datasets to create more comprehensive media analysis solutions.

Remember, the world of deepfake detection is rapidly evolving. By staying curious and continuing to experiment, you'll be at the forefront of this exciting technology. Your innovative applications of the DeepID API could play a crucial role in combating the spread of misinformation and protecting digital media integrity.