SYNTHETIQ VISION API User Guide

The SYNTHETIQ VISION API is a deepfake detection program that determines whether face images in input media files are generated by AI or other technology.
This document describes how to use the SYNTHETIQ VISION API.

Contents

• Introduction
• Glossary
• Basic flow
• Basic usage methods
  • Running the API using the curl command
    • Note
    • Usage method
• Details of the API
• FAQ

Introduction

Using the SYNTHETIQ VISION API requires the URL of the SYNTHETIQ VISION API server and the API token for authentication. Details of these two things and the conditions for media files subject to fake detection are as follows.

• URL of the SYNTHETIQ VISION API server
  • A SYNTHETIQ VISION API request is sent to this URL.
    • e.g. https://...
  • To find out the URL, contact the administrator of the SYNTHETIQ VISION API server.
  • In this document, it is expressed as <api-url>.
• API token
  • This token needs to be included in the request header when the SYNTHETIQ VISION API is used. The token is used for API authentication.
    • e.g. xxxx.xxxx.xxxx
  • To obtain the token, contact the administrator of the SYNTHETIQ VISION API server, as you do with the URL.
  • In this document, it is expressed as <your-api-token>.

• Conditions for media files subject to fake detection
  • The human face in the media must be clear and large enough.
    • The face may fail to be detected if it is too small or unclear.
  • Video files
    • Note: Each of the limitations in this system has been individually tested. However, it has not been evaluated in combination with all the limitations. Depending on the combination, it may not be possible to process the video.

    • The video file conditions that can be used as defaults are shown below.

      Attribute	Limit
      File size	~100 MB
      Duration	~3600 sec
      Width	360~4096 px
      Height	270~2160 px
      FPS	14~60 fps

    • The supported video formats and codecs are as follows.

      Format	Codec
      mp4	h264
      mp4	hevc
      webm	vp9
      avi	h264
      avi	mpeg4

  • Image files

    • The image file conditions that can be used as defaults are shown below.

      Attribute	Limit
      File size	~50 MB
      Width	360~4096 px
      Height	270~2160 px

    • The supported image formats are as follows.

      Format
      JPEG (.jpg, .jpeg)
      PNG (.png)

Glossary

• Fake detection value
  • Any of the values obtained as a result of running fake detection on a posted media file.
  • For videos: These include a frame index, a face region, and information about whether the video is real or fake.
  • For images: These include a face region and information about whether the image is real or fake.
• Fake detected video
  • A posted video with fake detection results overlaid on it.
    • Green bounding box: Face image found to be real
    • Red bounding box: Face image found to be fake
  • A fake detected video contains no audio.

  • The format and codec are respectively one of the following.

    Format	Codec
    webm	vp9
    mp4	h264

    • To play the video, install the decoder and codec to your video player.
  • Examples of the fake detection result
    • 
• Fake detection result token
  • This token is used to get the progress of the processing of a posted media file, as well as its fake detection values and fake detected video.

Basic flow

For videos

1. Post a video.
2. Get the progress of processing.
3. Get fake detection values.
4. Get the fake detected video.

For images

1. Post an image.
2. Get the progress of processing.
3. Get fake detection values.

For videos

sequenceDiagram
  actor U as User
  participant API as SYNTHETIQ VISION API

  Note left of U: To use the API, an API token is always necessary.

  U->>+API: Post a video and request a fake detected video = True/False
  API-->>-U: Fake detection result token

  Note left of U: Use the fake detection result token obtained here <br>when you make subsequent requests concerning the posted video.

  U->>+API: Get the progress of processing.
  API-->>-U: Progress of processing

  Note left of U: For the subsequent requests, <br>the progress of processing obtained here needs to be complete.

  U->>+API: Get fake detection values.
  API-->>-U: Fake detection value

  U->>+API: Get the fake detected video.
  alt Request a fake detected video = True
    API-->>U: Fake detected video
  else Request a fake detected video = False
    API-->>-U: Fail
  end

For images

sequenceDiagram
  actor U as User
  participant API as SYNTHETIQ VISION API

  Note left of U: To use the API, an API token is always necessary.

  U->>+API: Post an image
  API-->>-U: Fake detection result token

  Note left of U: Use the fake detection result token obtained here <br>when you make subsequent requests concerning the posted image.

  U->>+API: Get the progress of processing.
  API-->>-U: Progress of processing

  Note left of U: For the subsequent requests, <br>the progress of processing obtained here needs to be complete.

  U->>+API: Get fake detection values.
  API-->>-U: Fake detection value

The following pages describe how to execute these requests.

Basic usage methods

Running the API using the curl command

Note

• If the warning shown below appears, add the --insecure option to the curl command when you execute it, and you will be able to run the API.

    # Warning
    curl: (60) SSL certificate problem: self signed certificate More details here: https://curl.haxx.se/docs/sslcerts.html
  

    curl --insecure ...
  

Usage method

The steps of the basic flow of running the API using the curl command are described below.

1. Post a video.

   1. You can post a video by sending a request with the command shown below.

       curl -X 'POST' \
         '<api-url>/api/v1/movies?is_processed_movie_file_requested=<true-or-false>' \
         -H 'accept: application/json' \
         -H 'Api-Token: <your-api-token>' \
         -H 'Content-Type: multipart/form-data' \
         -F 'movie_file=@<movie-file-path>;type=video/<type>'
      

      • Placeholders
        • <api-url>: URL of the SYNTHETIQ VISION API server
        • <true-or-false>: Fake detected video request
          • true: You can get the fake detected video.
          • false: The creation of a fake detected video is not requested.
        • <your-api-token>: API token
        • <movie-file-path>: Path to the video file to be posted
        • <type>: Type of the video file to be posted
          • Set the type as appropriate for the video format.
          • Available types: iana / Media Types / video
          • For example, when the video format is mp4, set type=video/mp4.

   2. If the video is successfully posted, you will get the fake detection result token (JSON) shown below as the response. This information will be used in subsequent requests.

       {
         "hash_": <hash-of-the-movie>,
         "pub_fake_detection_process_event_id": <pub-fake-detection-process-event-id-of-the-movie>
       }
      

      • <hash-of-the-movie>: Hash value of the fake detection result token
      • <pub-fake-detection-process-event-id-of-the-movie>: Event ID of the public fake detection process
2. Get the progress of processing.

   1. You can get the progress of the processing of your posted video as a response, by sending a request with the command shown below.

       curl -X 'GET' \
         '<api-url>/api/v1/movies/progress?pub_fake_detection_process_event_id=<pub-fake-detection-process-event-id-of-the-movie>&hash_=<hash-of-the-movie>' \
         -H 'accept: application/json' \
         -H 'Api-Token: <your-api-token>'
      

      • Placeholders
        • <api-url>: URL of the SYNTHETIQ VISION API server
        • <pub-fake-detection-process-event-id-of-the-movie>: Event ID of the public fake detection process
        • <hash-of-the-movie>: Hash value of the fake detection result token
        • <your-api-token>: API token

   2. If the response is finished, as shown below, the fake detection is complete and you can get the detection result with the following command.

       {
         "progress": "finished"
       }
      

3. Get fake detection values.

   1. You can make a request to get fake detection values with the command shown below.

       curl -X 'GET' \
         '<api-url>/api/v1/movies/values?pub_fake_detection_process_event_id=<pub-fake-detection-process-event-id-of-the-movie>&hash_=<hash-of-the-movie>' \
         -H 'accept: application/json' \
         -H 'Api-Token: <your-api-token>'
      

      • Placeholders
        • <api-url>: URL of the SYNTHETIQ VISION API server
        • <pub-fake-detection-process-event-id-of-the-movie>: Event ID of the public fake detection process
        • <hash-of-the-movie>: Hash value of the fake detection result token
        • <your-api-token>: API token
4. Get the fake detected video.

   1. You can make a request to get the fake detected video with the command shown below.

       # In this case, the fake detected video file is saved in the current directory.
       curl -OJ -X 'GET' \
         '<api-url>/api/v1/movies?pub_fake_detection_process_event_id=<pub-fake-detection-process-event-id-of-the-movie>&hash_=<hash-of-the-movie>' \
         -H 'accept: video/mp4' \
         -H 'Api-Token: <your-api-token>'
      

      • Placeholders
        • <api-url>: URL of the SYNTHETIQ VISION API server
        • <pub-fake-detection-process-event-id-of-the-movie>: Event ID of the public fake detection process
        • <hash-of-the-movie>: Hash value of the fake detection result token
        • <your-api-token>: API token

For images

1. Post an image.

   1. You can post an image by sending a request with the command shown below.

       curl -X 'POST' \
         '<api-url>/api/v1/images' \
         -H 'accept: application/json' \
         -H 'Api-Token: <your-api-token>' \
         -H 'Content-Type: multipart/form-data' \
         -F 'image_file=@<image-file-path>;type=image/<type>'
      

      • Placeholders
        • <api-url>: URL of the SYNTHETIQ VISION API server
        • <your-api-token>: API token
        • <image-file-path>: Path to the image file to be posted
        • <type>: Type of the image file to be posted
          • Set the type as appropriate for the image format.
          • For example, for JPEG images use type=image/jpeg, for PNG images use type=image/png.

   2. If the image is successfully posted, you will get the fake detection result token (JSON) shown below as the response. This information will be used in subsequent requests.

       {
         "hash_": <hash-of-the-image>,
         "pub_fake_detection_process_event_id": <pub-fake-detection-process-event-id-of-the-image>
       }
      

      • <hash-of-the-image>: Hash value of the fake detection result token
      • <pub-fake-detection-process-event-id-of-the-image>: Event ID of the public fake detection process
2. Get the progress of processing.

   1. You can get the progress of the processing of your posted image as a response, by sending a request with the command shown below.

       curl -X 'GET' \
         '<api-url>/api/v1/images/progress?pub_fake_detection_process_event_id=<pub-fake-detection-process-event-id-of-the-image>&hash_=<hash-of-the-image>' \
         -H 'accept: application/json' \
         -H 'Api-Token: <your-api-token>'
      

      • Placeholders
        • <api-url>: URL of the SYNTHETIQ VISION API server
        • <pub-fake-detection-process-event-id-of-the-image>: Event ID of the public fake detection process
        • <hash-of-the-image>: Hash value of the fake detection result token
        • <your-api-token>: API token

   2. If the response is finished, as shown below, the fake detection is complete and you can get the detection result with the following command.

       {
         "progress": "finished"
       }
      

3. Get fake detection values.

   1. You can make a request to get fake detection values with the command shown below.

       curl -X 'GET' \
         '<api-url>/api/v1/images/values?pub_fake_detection_process_event_id=<pub-fake-detection-process-event-id-of-the-image>&hash_=<hash-of-the-image>' \
         -H 'accept: application/json' \
         -H 'Api-Token: <your-api-token>'
      

      • Placeholders
        • <api-url>: URL of the SYNTHETIQ VISION API server
        • <pub-fake-detection-process-event-id-of-the-image>: Event ID of the public fake detection process
        • <hash-of-the-image>: Hash value of the fake detection result token
        • <your-api-token>: API token
      • Note: For images, there is no endpoint to download a processed image. Only fake detection values can be retrieved.

Details of the API

• For details, go to the URLs shown below by using your browser.

  <api-url>/docs
  <api-url>/redoc
  

  • /docs, /redoc
    • Interactive API documentation and exploration web user interfaces.
    • /docs: Swagger UI
    • /redoc: Redoc

FAQ

Q: The API cannot be used.

A: Send the following information to the administrator and seek advice.

• curl command executed to use the API
• Error message
• Video file
• API token
• Fake detection result token