SYNTHETIQ API ユーザガイド

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

目次

• はじめに
• 用語
• 基本の流れ
• 基本の利用方法
  • curlコマンドによる実行
  • SYNTHETIQ専用CLIコマンドsynthetiqによる実行
• FAQ

はじめに

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

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

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

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

  • ただし顔が小さくはっきり映っていない場合には顔画像部が検出されない可能性があります。

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

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

用語

• 真贋動画
  • 投稿した動画に対して、真贋判定の結果をオーバーレイした動画。
    • 緑色のバウンディングボックス: リアルと判定された顔画像
    • 赤色のバウンディングボックス: Deepfakeと判定された顔画像
  • 真贋動画には音声は含まれません。

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

    Format	Codec	Note
    webm	vp9	[バグ] 真贋動画ファイルの拡張子が、正しくは.webmのところ.mp4と付与されます。 fileコマンド等で、どちらのフォーマットかをご確認下さい。
    mp4	h264

    • 動画再生時には、お使いの再生プレーヤーにデコーダ・コーデックをインストール下さい。
  • 真贋判定結果の例
    • 
• 真贋動画トークン
  • 投稿した動画について、その処理の進捗確認や、その真贋動画を得る際に使用します。

基本の流れ

1. 動画を投稿（Post movie）
2. 処理状況確認（Get progressing progress）
3. 真贋動画取得（Get processed movie）

sequenceDiagram
  actor U as User
  participant API as SYNTHETIQ API

  U->>API: Post movie
  API-->>U: 真贋動画トークン

  U->>API: Get processing progress
  API-->>U: 処理の進捗状態

  U->>API: Get processed movie
  alt Progress status == finished
    API-->>U: 真贋動画
  else Progress status != finished
    API-->>U: 取得失敗
  end

以下ではステップそれぞれの実行方法を説明します。

基本の利用方法

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

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

curlコマンドによる実行

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 ...
    

1. 動画を投稿（Post movie）
   • 以下コマンドのSYNTHETIQ APIサーバのURL(<api-url>)、SYNTHETIQ APIトークン(<your-api-token>)、投稿する動画(<movie-file-name>)を指定し、リクエストを送信することで動画を投稿できます。

     • コマンド例

         curl -X 'POST' \
           '<api-url>/api/v1/movies/' \
           -H 'accept: application/json' \
           -H 'Api-Token: <your-api-token>' \
           -H 'Content-Type: multipart/form-data' \
           -F 'movie_file=@<movie-file-name>'
       

   • 正常に投稿が完了した場合、以下の真贋動画トークン(json)をレスポンスとして取得します。こちら2項目は以降の処理状況確認および真贋動画取得を行う際に使用します。

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

     • hash_: 真贋動画トークンのハッシュ値
     • pub_fake_detection_process_event_id: 公開真贋動画イベントID
2. 処理状況確認（Get progressing progress）
   • 以下のコマンドの<api-url>、<your-api-token>に加えて、操作1のレスポンスで取得した<hash-of-the-movie>および<pub-fake-detection-process-event-id-of-the-movie>を指定し、リクエストを送信することで投稿した動画の処理状況をレスポンスとして確認できます。

     • コマンド例

           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>'
       

   • レスポンスが以下のように「finished」となっていれば、真贋動画の作成が完了しているため、操作3によって真贋動画を取得できます。

     {
       "progress": "finished"
     }
     

3. 真贋動画取得（Get processed movie）

   • 操作2のレスポンスが「finished」であれば、操作2と同様に以下のコマンドの<api-url>、<your-api-token>、操作1のレスポンスで取得した<hash-of-the-movie>および<pub-fake-detection-process-event-id-of-the-movie>を指定し、リクエストを送信することで真贋動画のダウンロードが開始され、コマンド実行ディレクトリに保存されます。

     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で確認できます。

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

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

SYNTHETIQ専用CLIコマンドsynthetiqによる実行

CLIとは、簡易クライアントソフトのことです。 このSYNTHETIQ専用CLIコマンド synthetiq を活用することで、SYNTHETIQ APIトークン・真贋動画トークンをファイルで扱い、コマンド入力を簡略化した上でAPIによる実行と同様の真贋判定を実行できます。基本の流れの３ステップおよび実行前の準備については以下の通りです。

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

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

• CLIによる実行の事前準備

  • まず、SYNTHETIQ APIサーバの管理者より、CLI実行ファイル(synthetiq.exe)およびCLI設定ファイル(.synthetiq.yaml)を受け取ります。
  • CLI設定ファイルを自身のホームディレクトリに設置してください。
  • 以上が事前準備となり、基本の流れの3STEPが実行可能になります。
  • 以降のコマンド例はCLI実行ファイルのあるディレクトリもしくは環境変数等により”synthetiq”という形でのコマンド入力例になります。パスを入力し、CLI実行ファイルを指定する形でも実行可能です。
  • 各ファイル詳細
    • CLI実行ファイル
      • このソフトで設定されているコマンドによって対応した処理が行われるソフトファイルになります。
    • CLI設定ファイル
      • SYNTHETIQ APIサーバのURL(<api-url>)、SYNTHETIQ APIトークン(<your-api-token>)が設定されており、CLI実行ファイルが自動で読み込むため、curlによる実行方法のようにSYNTHETIQ APIトークン等をコマンドに入力する必要がなくなります。

1. 動画を投稿（Post movie）
   • 以下コマンドの投稿する動画のファイルパス(<movie-file-path>)、真贋動画トークンファイル(jsonファイル)の出力先パス(<token-json-path>)を指定し、実行することで動画を投稿できます。

     • コマンド例

         synthetiq upload <movie-file-path> -o <token-json-path>
       

   • CLI実行ファイルがレスポンスを受け取ると指定していた<token-json-path>に真贋動画トークンファイルを取得します。
   • 真贋動画トークンファイルとは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">
         #}
       

2. 処理状況確認（Get progressing progress）
   • 以下コマンドの<token-json-path>に操作1で取得したファイルのパスを指定し、実行することで動画の処理状況が出力・確認できます。

     • コマンド例

           synthetiq progress <token-json-path>
       

   • 出力された内容が以下のように「finished」となっていれば、真贋動画の作成が完了しているため、操作3によって真贋動画を取得できます。

     • 出力例

         {
           "progress": "finished"
         }
       

3. 真贋動画取得（Get processed movie）
   • 操作2のレスポンスが「finished」であれば、操作2と同様に以下のコマンドの<token-json-path>に操作1で取得したファイルのパスを指定し、実行することで真贋動画のダウンロードが開始され、カレントディレクトリに保存されます。

     • コマンド例

         synthetiq download <token-json-path>
       

   • SYNTHETIQ専用CLIコマンド synthetiq その他仕様確認方法
     • CLIにて設定してあるコマンドオプション等は、以下で確認ください。
       • CLI同梱のドキュメント

       • helpオプション

         synthetiq --help
         synthetiq upload --help
         synthetiq download --help
         synthetiq progress --help
         

FAQ

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

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

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

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

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

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

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

  Good	Bad
  .synthetiq.yaml	synthetiq.yaml

• Macの場合、OSのセキュリティ設定で使用許可をする必要があります。詳細は下記のリンク先をご参考下さい。
  • 開発元が未確認のMacアプリケーションを開く
  • Mac で App を安全に開く
• お使いのセキュリティソフトで使用許可をする必要があります。詳細はお使いのソフトのマニュアルをご参照下さい。

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

    syntehtiq --version