SYNTHETIQ VISION API ユーザガイド

SYNTHETIQ VISION APIは入力したメディアファイル中の顔画像が、AI等により生成された顔画像であるかどうかを検出するディープフェイク検出プログラムです。
この資料では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
- 静止画ファイル
  - デフォルトの設定で利用可能な静止画ファイルの条件は以下の通りです。
    
    Attribute Limit
    
    File size ~50 MB
    
    Width 360~4096 px
    
    Height 270~2160 px
  - サポートされている静止画のフォーマットは以下の通りです。
    
    Format
    
    JPEG (.jpg, .jpeg)
    
    PNG (.png)

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

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

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

用語

真贋検出値
- 投稿したメディアファイルを真贋検出した結果として得られる値
- 顔領域、リアル/フェイク等の情報を含む。動画の場合、フレーム番号などの時系列情報を含む。
真贋動画
- 投稿した動画に対して、真贋検出の結果をオーバーレイした動画。
  - 緑色のバウンディングボックス: リアルと検出された顔画像
  - 赤色のバウンディングボックス: フェイクと検出された顔画像
- 真贋動画には音声は含まれません。
- フォーマットおよびコーデックは、以下のいずれかになります。
  
  Format Codec
  
  webm vp9
  
  mp4 h264
  - 動画再生時には、お使いの再生プレーヤーにデコーダー・コーデックをインストールください。
- 真贋検出結果の例
真贋検出結果トークン
- 投稿したメディアファイルについて、その処理進捗の取得や、その真贋検出値および真贋動画を取得する際に使用します。

Format	Codec
webm	vp9
mp4	h264

基本の流れ

動画の場合

動画の投稿
処理進捗の取得
真贋検出値の取得
真贋動画の取得

画像の場合

画像の投稿
処理進捗の取得
真贋検出値の取得

動画の場合

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

画像の場合

sequenceDiagram
  actor U as User
  participant API as SYNTHETIQ VISION API

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

  U->>+API: 画像の投稿
  API-->>-U: 真贋検出結果トークン

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

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

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

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

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

基本の利用方法

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. 以下のコマンドでリクエストを送信することで、動画を投稿できます。
```
 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
処理進捗の取得
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"
 }
```
真贋検出値の取得
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トークン
真贋動画の取得
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トークン

画像の場合

画像の投稿
1. 以下のコマンドでリクエストを送信することで、画像を投稿できます。
```
 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>'
```
  - プレースホルダー
    - <api-url>: SYNTHETIQ VISION APIサーバのURL
    - <your-api-token>: APIトークン
    - <image-file-path>: 投稿する画像ファイルのパス
    - <type>: 投稿する画像ファイルのタイプ
      - 画像の形式に合わせて、設定してください。
      - e.g. jpegの場合、type=image/jpeg、pngの場合、type=image/png
2. 正常に投稿が完了した場合、以下の真贋検出結果トークン（json）をレスポンスとして取得します。この情報は以降のリクエストで使用します。
```
 {
   "hash_": <hash-of-the-image>,
   "pub_fake_detection_process_event_id": <pub-fake-detection-process-event-id-of-the-image>
 }
```
  - <hash-of-the-image>: 真贋検出結果トークンのハッシュ値
  - <pub-fake-detection-process-event-id-of-the-image>: 公開真贋処理イベントID
処理進捗の取得
1. 以下のコマンドでリクエストを送信することで、投稿した画像の処理進捗の状態をレスポンスとして確認できます。
```
 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>'
```
  - プレースホルダー
    - <api-url>: SYNTHETIQ VISION APIサーバのURL
    - <pub-fake-detection-process-event-id-of-the-image>: 公開真贋処理イベントID
    - <hash-of-the-image>: 真贋検出結果トークンのハッシュ値
    - <your-api-token>: APIトークン
2. レスポンスが以下のようにfinishedとなっていれば、真贋検出処理が完了しており、以降のコマンドで検出結果を取得できます。
```
 {
   "progress": "finished"
 }
```
真贋検出値の取得
1. 以下のコマンドで真贋検出値の取得をリクエストできます。
```
 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>'
```
  - プレースホルダー
    - <api-url>: SYNTHETIQ VISION APIサーバのURL
    - <pub-fake-detection-process-event-id-of-the-image>: 公開真贋処理イベントID
    - <hash-of-the-image>: 真贋検出結果トークンのハッシュ値
    - <your-api-token>: APIトークン
  - 注意: 画像の場合、処理済み画像をダウンロードするエンドポイントは提供されていません。真贋検出値のみ取得可能です。

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トークン
真贋検出結果トークン

SYNTHETIQ VISION API ユーザガイド

目次

はじめに

用語

基本の流れ

動画の場合

画像の場合

動画の場合

画像の場合

基本の利用方法

curlコマンドによる実行

注意点

使用方法

画像の場合

APIの詳細

FAQ