SYNTHETIQ VISION API ユーザガイド

SYNTHETIQ VISION APIは入力映像中の顔画像がAI等により生成された顔画像であるかどうかを検出するDeepfake検出プログラムです。
この資料ではSYNTHETIQ VISION APIの利用方法を説明します。

processed movie

目次

はじめに

SYNTHETIQ VISION APIを利用するためには、SYNTHETIQ VISION APIサーバのURL、認証用APIトークンが必要になります。こちら2点の詳細および真贋検出を行う映像ファイルの条件は以下の通りです。

  • SYNTHETIQ VISION APIサーバのURL
    • SYNTHETIQ VISION APIのリクエスト先になります。
      • e.g. https://...
    • こちらはSYNTHETIQ VISION APIサーバの管理者に問い合わせください。
    • 本ページ中では<api-url>と表現します。
  • APIトークン
    • SYNTHETIQ VISION APIの使用時において、リクエストヘッダーに必要なトークンです。こちらAPIの認証に使用されます。
      • e.g. xxxx.xxxx.xxxx
    • こちらも同様にSYNTHETIQ VISION APIサーバの管理者に問い合わせ、トークンを入手してください。
    • 本ページ中では<your-api-token>と表現します。
  • 真贋検出を行う映像ファイルの条件

    • デフォルトの設定で利用可能な映像ファイルの条件は以下の通りです。

      Attribute Limit
      File size ~100 MB
      Duration ~3600 sec
      Width 360~4096 px
      Height 270~2160 px
      FPS 14~60 fps
    • 人の顔がはっきり大きく写っていること
      • もし顔が小さい／鮮明でない場合、検出されない可能性があります。

    • サポートされている映像のフォーマットおよびコーデックは以下の通りです。

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

用語

  • 真贋検出値
    • 投稿した動画を真贋検出した結果として得られる値
    • フレーム番号、顔領域、リアル/フェイク等の情報を含む。
  • 真贋動画
    • 投稿した動画に対して、真贋検出の結果をオーバーレイした動画。
      • 緑色のバウンディングボックス: リアルと検出された顔画像
      • 赤色のバウンディングボックス: フェイクと検出された顔画像
    • 真贋動画には音声は含まれません。

    • フォーマットおよびコーデックは、以下のいずれかになります。

      Format Codec Note
      webm vp9 [バグ] 真贋動画ファイルの拡張子が、正しくは.webmのところ.mp4と付与されます。
      fileコマンド等で、フォーマットをご確認ください。
      mp4 h264  
      • 動画再生時には、お使いの再生プレーヤーにデコーダー・コーデックをインストールください。
    • 真贋検出結果の例
      • processed movie
  • 真贋検出結果トークン
    • 投稿した動画について、その処理進捗の取得や、その真贋検出値および真贋動画を取得する際に使用します。

基本の流れ

  1. 動画の投稿
  2. 処理進捗の取得
  3. 真贋検出値の取得
  4. 真贋動画の取得
sequenceDiagram
  actor U as User
  participant API as SYNTHETIQ VISION API

  Note left of U: APIの利用には、常にAPIトークンが必要です。

  U->>+API: 動画の投稿 + 真贋動画要求=True/False
  API-->>-U: 真贋検出結果トークン

  Note left of U: 投稿した動画に関する以降のリクエストに、<br>ここで得た真贋検出結果トークンを使用します。

  U->>+API: 処理進捗の取得
  API-->>-U: 処理進捗の状態

  Note left of U: 以降のリクエストは、<br>ここで処理進捗の状態=完了である事が必要です。

  U->>+API: 真贋検出値の取得
  API-->>-U: 真贋検出値

  U->>+API: 真贋動画の取得
  alt 真贋動画要求=True
    API-->>U: 真贋動画
  else 真贋動画要求=False
    API-->>-U: 失敗
  end

以降で、各リクエストの実行方法を説明します。

基本の利用方法

SYNTHETIQ VISION APIの利用方法は以下の2種類があります。

  • curlコマンドによる実行
  • SYNTHETIQ VISION API用CLI synthetiq による実行

curlコマンドによる実行

注意点

  • もし以下のWarningが発生した場合は、curlコマンドを実行する際に--insecureオプションを追加すると実行可能になります。

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

      curl --insecure ...

使用方法

curlコマンドによる基本の流れの各ステップの実行方法は以下の通りです。

  1. 動画の投稿

    1. 以下のコマンドでリクエストを送信することで、動画を投稿できます。

       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>'
      • プレースホルダー
        • <api-url>: SYNTHETIQ VISION APIサーバのURL
        • <true-or-false>: 真贋動画要求
          • true: 真贋動画の取得が可能になります
          • false: 真贋動画の作成を要求しません。
        • <your-api-token>: APIトークン
        • <movie-file-path>: 投稿する動画ファイルのパス
        • <type>: 投稿する動画ファイルのタイプ
          • 動画の形式に合わせて、設定してください。
          • typeの種類：iana / Media Types / video
          • e.g. mp4の場合、type=video/mp4

    2. 正常に投稿が完了した場合、以下の真贋検出結果トークン（json）をレスポンスとして取得します。この情報は以降のリクエストで使用します。

       {
   "hash_": <hash-of-the-movie>,
   "pub_fake_detection_process_event_id": <pub-fake-detection-process-event-id-of-the-movie>
 }
      • <hash-of-the-movie>: 真贋検出結果トークンのハッシュ値
      • <pub-fake-detection-process-event-id-of-the-movie>: 公開真贋動画イベントID
  2. 処理進捗の取得

    1. 以下のコマンドでリクエストを送信することで、投稿した動画の処理進捗の状態をレスポンスとして確認できます。

       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>'
      • プレースホルダー
        • <api-url>: SYNTHETIQ VISION APIサーバのURL
        • <pub-fake-detection-process-event-id-of-the-movie>: 公開真贋動画イベントID
        • <hash-of-the-movie>: 真贋検出結果トークンのハッシュ値
        • <your-api-token>: APIトークン

    2. レスポンスが以下のようにfinishedとなっていれば、真贋検出処理が完了しており、以降のコマンドで検出結果を取得できます。

       {
   "progress": "finished"
 }
  3. 真贋検出値の取得

    1. 以下のコマンドで真贋検出値の取得をリクエストできます。

       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>'
      • プレースホルダー
        • <api-url>: SYNTHETIQ VISION APIサーバのURL
        • <pub-fake-detection-process-event-id-of-the-movie>: 公開真贋動画イベントID
        • <hash-of-the-movie>: 真贋検出結果トークンのハッシュ値
        • <your-api-token>: APIトークン
  4. 真贋動画の取得

    1. 以下のコマンドで真贋動画の取得をリクエストできます。

       # この場合、真贋動画ファイルはカレントディレクトリに保存されます。
 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>'
      • プレースホルダー
        • <api-url>: SYNTHETIQ VISION APIサーバのURL
        • <pub-fake-detection-process-event-id-of-the-movie>: 公開真贋動画イベントID
        • <hash-of-the-movie>: 真贋検出結果トークンのハッシュ値
        • <your-api-token>: APIトークン

SYNTHETIQ VISION API用CLI synthetiq による実行

SYNTHETIQ VISION API用CLI synthetiq とは

  • SYNTHETIQ VISION API用の簡易クライアントソフトのことです。
  • CLI実行ファイルであるsynthetiqにより、APIトークンと真贋検出結果トークンをファイルで扱い、簡単なコマンドでAPIを使用する事ができます。

CLIの対応OSとアーキテクチャ

OS Arch e.g.
darwin amd64 macOS 11 64bit
darwin arm64 macOS 12 Apple Silicon
linux amd64 Ubuntu 20.04 64bit
windows amd64 Windows 10 64bit

使用準備

  1. まず、SYNTHETIQ VISION APIサーバの管理者より、以下の2点を受け取ります。
    1. CLI実行ファイル
      • ファイル名
        • Windows用: synthetiq.exe
        • その他用: synthetiq
      • この実行ファイルを用いて、APIにリクエストを送ります。
    2. CLI設定ファイル
      • ファイル名
        • .synthetiq.yaml
      • CLI実行ファイルが自動で本ファイルを読み込み、使用します。
      • 以下の情報を含みます。
        • SYNTHETIQ VISION APIサーバのURL: <api-url>
        • APIトークン: <your-api-token>
  2. CLI実行ファイルにPATHを通してください。
    • （参考）PATHの通し方: How to add a directory to the PATH? / ask ubuntu
    • 後述の使用方法では、PATHが通った状態でのコマンドsynthetiqで例示しています。
    • また以下の方法で実行する事も可能です。
      • CLI実行ファイルの絶対パスを指定。
      • CLI実行ファイルのディレクトリに移動した上で、synthetiqを実行
  3. CLI設定ファイルを、自身のホームディレクトリに設置してください。

使用方法

  1. 動画の投稿

    1. 以下のコマンドにより、動画を投稿できます。

       synthetiq upload <movie-file-path> -o <token-json-path> -r
      • プレースホルダー
        • <movie-file-path>: 投稿する動画のファイルパス
        • <token-json-path>: レスポンスとなる真贋検出結果トークンの、保存先ファイルパス（json）
      • オプション
        • -r: 真贋動画要求
          • このオプションにより、真贋動画の取得が可能になります
    2. レスポンスで得たjsonファイルを、真贋検出結果トークンファイルと呼びます。
      • curl編で紹介した真贋検出結果トークンと同じ情報です。

      • ファイルの内容

          cat <token-json-path>

  #{
  # "hash_": <hash-of-the-movie>,
  # "pub_fake_detection_process_event_id": <pub-fake-detection-process-event-id-of-the-movie">
  #}
    3. このファイルを使用し、以降のコマンドを実行します。
  2. 処理進捗の取得

    1. 以下のコマンドにより、投稿した動画の処理進捗を取得できます。

       synthetiq progress <token-json-path>
      • プレースホルダー
        • <token-json-path>: 真贋検出結果トークンファイルのパス

    2. レスポンスが以下のようにfinishedであれば、真贋動画の作成が完了しています。以降のコマンドで検出結果を取得可能な状態です。

      • レスポンス例

          {
    "progress": "finished"
  }
  3. 真贋検出値の取得

    1. 以下のコマンドにより、真贋検出値を取得できます。

       synthetiq get-values <token-json-path>
      • プレースホルダー
        • <token-json-path>: 真贋検出結果トークンファイルのパス
  4. 真贋動画の取得

    1. 以下のコマンドにより、真贋動画ファイルを取得できます。

       # この場合、ファイルはカレントディレクトリに保存されます。
 synthetiq download <token-json-path>
      • プレースホルダー
        • <token-json-path>: 真贋検出結果トークンファイルのパス

使用方法の詳細

  • CLIのコマンドオプション等は、以下で確認ください。
    • CLI同梱のドキュメント

    • helpオプション

      synthetiq --help
synthetiq upload --help
synthetiq download --help
synthetiq get-values --help
synthetiq progress --help

APIの詳細

  • ブラウザにより、以下のURLで確認できます。

    <api-url>/docs
<api-url>/redoc
    • /docs, /redoc
      • Interactive API documentation and exploration web user interfaces.
      • /docs: Swagger UI
      • /redoc: Redoc

FAQ

Q: APIが使用できません。

A: 以下の情報を、管理者に送付し相談を受けてください。

  • curlによるAPIの実行コマンド
  • エラーメッセージ
  • 動画ファイル
  • APIトークン
  • 真贋検出結果トークン

Q: CLIが使用できません。

A: まずAPIが使用可能かを確認してください。
APIが使用可能であるが、CLIが使用不能である時は、以下をご確認ください。

  • CLIが使用環境（OS, アーキテクチャ）と合っているか。
    • e.g. Windows 10 64bitの環境で、Linux用のCLIを使用した場合は動作しません。

  • CLI設定ファイル名の先頭のドットが抜けていないこと。

    Good Bad
    .synthetiq.yaml synthetiq.yaml
  • Macの場合、OSのセキュリティ設定で使用許可をする必要があります。詳細は下記のリンク先をご参照ください。
  • お使いのセキュリティソフトで使用許可をする必要があります。詳細はお使いのソフトのマニュアルをご参照ください。

  • 以上で解決しない場合、CLIのバージョンとCLI設定ファイルを管理者に送付し、相談を受けてください。

      syntehtiq --version
"Copyright (c) 2022-2023, National Institute of Informatics All rights reserved."