ProbeTruth ドキュメント（日本語）

API Reference（日本語）

ProbeTruth API Reference の日本語版です。ディープフェイク検出機能をアプリケーションへ統合するための、 REST APIの仕様（エンドポイント、認証、リクエスト/レスポンス例、注意点）をまとめています。

Base URL

すべてのAPIエンドポイントは、次のベースURLの配下にあります。

https://app.probetruth.ai/api/v1.0

Quick Start Workflow（最短の流れ）

代表的な分析フロー（アップロード→解析→ステータス確認→レポート取得）は次の通りです。

Upload Media: POST /media/upload → referenceId を取得
Start Analysis: POST /deepfake/start（bodyに referenceId） → status が queued
Poll Status: GET /deepfake/<referenceId>/status → status が done になるまで確認
Download Report: statusレスポンスの reportUrl からPDFをダウンロード

Python（フル例）:

import requests
import hashlib
import time

API_TOKEN = "<your_api_token_here>"
BASE_URL = "https://app.probetruth.ai/api/v1.0"

def analyze_media(file_path):
    """Complete workflow: Upload → Analyze → Poll → Download Report"""

    # Step 1: Calculate file hash
    sha256_hash = hashlib.sha256()
    with open(file_path, "rb") as f:
        for byte_block in iter(lambda: f.read(4096), b""):
            sha256_hash.update(byte_block)
    file_hash = sha256_hash.hexdigest()

    # Step 2: Upload media
    print("📤 Uploading media...")
    with open(file_path, "rb") as f:
        upload_response = requests.post(
            f"{BASE_URL}/media/upload",
            headers={"Authorization": f"Bearer {API_TOKEN}"},
            files={"file": f},
            data={"fileHash": file_hash}
        )

    if upload_response.status_code != 200:
        print(f"❌ Upload failed: {upload_response.text}")
        return

    reference_id = upload_response.json()["data"]["referenceId"]
    print(f"✅ Uploaded successfully! Reference ID: {reference_id}")

    # Step 3: Start analysis
    print("🔍 Starting analysis...")
    start_response = requests.post(
        f"{BASE_URL}/deepfake/start",
        headers={
            "Authorization": f"Bearer {API_TOKEN}",
            "Content-Type": "application/json"
        },
        json={"referenceId": reference_id}
    )

    if start_response.status_code != 200:
        print(f"❌ Start failed: {start_response.text}")
        return

    print("✅ Analysis started!")

    # Step 4: Poll for status
    print("⏳ Waiting for analysis to complete...")
    while True:
        status_response = requests.get(
            f"{BASE_URL}/deepfake/{reference_id}/status",
            headers={"Authorization": f"Bearer {API_TOKEN}"}
        )

        if status_response.status_code != 200:
            print(f"❌ Status check failed: {status_response.text}")
            return

        status_data = status_response.json()["data"]
        status = status_data["status"]
        print(f"   Status: {status}")

        if status == "done":
            print("✅ Analysis complete!")
            report_url = status_data["reportUrl"]
            report_hash = status_data.get("reportFileHash")

            # Step 5: Download report
            print("📥 Downloading report...")
            report_response = requests.get(f"{report_url}?apiToken={API_TOKEN}")

            if report_response.status_code == 200:
                with open("deepfake_report.pdf", "wb") as f:
                    f.write(report_response.content)

                # Verify report integrity
                actual_hash = hashlib.sha256(report_response.content).hexdigest()
                if actual_hash == report_hash:
                    print("✅ Report downloaded and verified!")
                else:
                    print("⚠️  Report downloaded but hash mismatch!")
            else:
                print(f"❌ Report download failed: {report_response.text}")

            break

        elif status in ["failed", "stopped"]:
            print(f"❌ Analysis {status}: {status_data.get('reason', 'No reason provided')}")
            break

        time.sleep(5)  # Poll every 5 seconds

# Usage
analyze_media("/path/to/your/video.mp4")

API Endpoints Summary（一覧）

利用可能なエンドポイントの概要です。

Method	Endpoint	説明
`POST`	/media/upload	解析対象メディアをアップロード
`POST`	/deepfake/start	ディープフェイク解析を開始
`GET`	/deepfake/:id/status	単一タスクのステータスを確認
`GET`	/deepfake/status	複数タスクのステータスをまとめて確認
`POST`	/deepfake/stop	実行中（または待機中）の解析を停止
`GET`	/reports/:filename	レポート（PDF）を取得

Response Format（レスポンス形式）

APIレスポンスは一貫して次の構造を取ります。

{
  "statusCode": 0,      // 0 = success, negative number like -9999 = error
  "data": { ... }       // Response payload
}

エラー時は message に説明文が入ります。

Authentication（認証）

ProbeTruth API の全リクエストは、トークンベース認証 により保護されています。保護対象のエンドポイントを呼び出す際は、AuthorizationヘッダにAPIトークンを設定します。

認証フロー概要

クライアントがサーバに認証し、APIトークン（api token）を取得します。
以後のリクエストで、Authorizationヘッダにトークンを付与します。
API Gateway がトークンを検証してバックエンドへ転送します。

アクセス取得（Getting Access）

ProbeTruthでサブスクリプションアカウントを作成
ダッシュボードで API Keys セクションへ移動
APIキーを作成（名前、IP/ドメイン制限は任意）
発行直後にトークンを控える（後から全文を再表示できない想定）

Note: 環境（production/staging）別に複数キーを作成し、IP/ドメイン制限で防御を強化できます。

Authorizationヘッダ

すべてのAPIリクエストで次の形式を使います。

Authorization: Bearer <your_api_token_here>

例（Python）

import requests

API_TOKEN = 'your_api_token_here'
API_URL = 'https://app.probetruth.ai/api/v1.0/deepfake/68ee18fbbf286d24fd9bdbdc/status'

headers = {
  'Authorization': f'Bearer {API_TOKEN}'
}

response = requests.get(API_URL, headers=headers)

if response.ok:
  print("Success:", response.json())
else:
  print("Error:", response.status_code, response.text)

セキュリティのベストプラクティス

トークンをフロントエンドに埋め込まない（公開JS/リポジトリに出さない）
定期的にローテーションする
SecurityScorecard等のツールでセキュリティ状態を継続評価する

Upload Media（メディアのアップロード）

POST api/v1.0/media/upload は、動画・音声・画像ファイルをアップロードしてフォレンジック解析（ディープフェイク検出）を行うための入口です。

対象は video / audio / image です。

Endpoint

POST https://app.probetruth.ai/api/v1.0/media/upload

Authentication

AuthorizationヘッダにAPIキーを設定します（トークンは失効させるまで有効、という記載）。

Authorization: Bearer YOUR_API_KEY

Supported Media Types（対応形式）

Video .mp4 .mkv .avi .mov .wmv .flv .webm
Audio .mp3 .wav .aac .flac
Image .jpg .jpeg .png .bmp .tiff

Headers

Key	Value
Authorization	Bearer <your_api_key_here>
Content-Type	multipart/form-data

Request Body

Field	Type	Required	説明
file	file	Yes	解析対象のメディアファイル
fileHash	string	Yes	アップロードするバイト列に一致するSHA-256ハッシュ（整合性検証用）

Code Example

cURL

curl -X POST https://app.probetruth.ai/api/v1.0/media/upload \
  -H "Authorization: Bearer <your_api_token_here>" \
  -F "file=@/path/to/your/video.mp4" \
  -F "fileHash=<sha256_hash_of_the_file>"

Success Response

{
  "statusCode": 0,
  "data": {
    "referenceId": "692a9390e18c3d5e423c5cb8"
  }
}

Error Responses

代表的なエラー例です（原文の例を踏襲）。

400 Bad Request

{
  "statusCode": -9999,
  "message": "Unsupported file extension. Allowed extensions: .mp4, .mkv, .avi, .mov, .wmv, .flv, .webm, .mp3, .wav, .aac, .flac, .jpg, .jpeg, .png, .bmp, .tiff"
}

403 Forbidden

{
  "statusCode": -9999,
  "message": "User not found"
}

400 Bad Request

{
  "statusCode": -9999,
  "message": "File size exceeds the limit for image"
}

Next Step

アップロード後は、返ってきた referenceId を使って解析を開始します。

POST api/v1.0/deepfake/start

Developer Notes

サーバ側設定により、大容量ファイルはアップロードが失敗することがあります。
対応形式はバックエンドで検証されます。必要に応じてアップロード前にクライアント側でも検証してください。
アップロード後に返る referenceId は、その後の start/status/report 等で共通に使います。

Media Inspection（解析の開始・ステータス確認）

Upload Media が成功したら、Media Inspectionエンドポイントでフォレンジック解析（ディープフェイク検出）を開始できます。

原文には「ファイルのハッシュとフォレンジックレポートのみを保存し、メディア本体はサーバ設定の一定期間後に削除される」と記載があります。

解析開始は、アップロードで得た referenceId をリクエストボディに指定して行います。

アップロード済みメディアに対して解析を開始するためのエンドポイントがあります。

1. Initiate Media Inspection（解析開始）

POST api/v1.0/deepfake/start は、アップロード済みメディアに対して解析パイプラインを起動します。

Endpoint

POST https://app.probetruth.ai/api/v1.0/deepfake/start

Authentication

AuthorizationヘッダにAPIキーを設定します。

Authorization: Bearer YOUR_API_KEY

Request Body

Field	Type	Required	説明
`referenceId`	string	Yes	アップロード済みメディアの一意ID

Content-Type: application/json

Code Example

cURL

curl -X POST https://app.probetruth.ai/api/v1.0/deepfake/start \
  -H "Authorization: Bearer <your_api_token_here>" \
  -H "Content-Type: application/json" \
  -d '{"referenceId": "68ee18fbbf286d24fd9bdbdc"}'

Success Response（解析開始）

{
  "statusCode": 0,
  "data": {
    "status": "queued"
  }
}

Missing referenceId

{
  "statusCode": -9999,
  "message": "referenceId should not be empty"
}

Invalid referenceId

{
  "statusCode": -9999,
  "message": "Media not found"
}

Unauthorized Token

{
  "statusCode": -9999,
  "message": "Invalid API token"
}

2. Check Inspection Status（ステータス確認）

解析の進捗確認には用途に応じて複数のステータスAPIが用意されています。

2.1 Single Task Status（単一）

referenceId を指定して単一タスクのステータスを取得します。

GET https://app.probetruth.ai/api/v1.0/deepfake/<referenceId>/status

Authentication:

Authorization: Bearer <your_api_token_here>

Example Request:

curl -X GET "https://app.probetruth.ai/api/v1.0/deepfake/692a8a6aec7dd33fcf9feb52/status" \
  -H "Authorization: Bearer <your_api_token_here>"

Success Response

{
  "statusCode": 0,
  "data": {
    "referenceId": "692a8a6aec7dd33fcf9feb52",
    "status": "done",
    "reportUrl": "https://app.probetruth.ai/api/v1.0/reports/39f39266-6deb-48e4-924d-21d12d76fc06.pdf",
    "reportFileHash": "50f0737dbebc69861353a6000c94ddd56029938c9c117df7abc4a1645d8abab0",
    "result": "Analysis completed successfully",
    "reason": null,
    "mimeType": "image/png",
    "originalName": "avatar.png",
    "createdAt": "2025-11-29T05:53:46.782Z",
    "updatedAt": "2025-11-29T05:59:15.561Z"
  }
}

2.2 Bulk Status Check（複数まとめて）

複数の referenceId をカンマ区切りで指定して一括取得します。

GET https://app.probetruth.ai/api/v1.0/deepfake/status?referenceIds=<id1>,<id2>,<id3>

Query Parameters:

Parameter	Type	Required	説明
referenceIds	string	Yes	referenceId のカンマ区切りリスト

Example Request:

curl -X GET "https://app.probetruth.ai/api/v1.0/deepfake/status?referenceIds=692a8a6aec7dd33fcf9feb52,692a9390e18c3d5e423c5cb8" \
  -H "Authorization: Bearer <your_api_token_here>"

Success Response（配列）

{
  "statusCode": 0,
  "data": [
    {
      "referenceId": "692a8a6aec7dd33fcf9feb52",
      "status": "done",
      "reportUrl": "https://app.probetruth.ai/api/v1.0/reports/39f39266-6deb-48e4-924d-21d12d76fc06.pdf",
      "reportFileHash": "50f0737dbebc69861353a6000c94ddd56029938c9c117df7abc4a1645d8abab0",
      "result": "Analysis completed successfully",
      "reason": null,
      "mimeType": "image/png",
      "originalName": "avatar.png",
      "createdAt": "2025-11-29T05:53:46.782Z",
      "updatedAt": "2025-11-29T05:59:15.561Z"
    },
    {
      "referenceId": "692a9390e18c3d5e423c5cb8",
      "status": "processing",
      "reportUrl": null,
      "reportFileHash": null,
      "result": null,
      "reason": null,
      "mimeType": "video/mp4",
      "originalName": "sample_video.mp4",
      "createdAt": "2025-11-29T06:12:30.123Z",
      "updatedAt": "2025-11-29T06:12:35.456Z"
    }
  ]
}

3. Stop Running Task（解析の停止）

queued / processing の解析タスクをキャンセルします。

POST https://app.probetruth.ai/api/v1.0/deepfake/stop

Authentication:

Authorization: Bearer <your_api_token_here>

Request Body:

Field	Type	Required	説明
referenceId	string	Yes	停止したいタスクの referenceId

Example Request:

curl -X POST "https://app.probetruth.ai/api/v1.0/deepfake/stop" \
  -H "Authorization: Bearer <your_api_token_here>" \
  -H "Content-Type: application/json" \
  -d '{"referenceId": "692a9390e18c3d5e423c5cb8"}'

Success Response

{
  "statusCode": 0,
  "data": {
    "status": "stopped"
  }
}

4. Get User Statistics（統計）

アカウントの集計統計（総スキャン数、完了数、ステータス内訳など）を取得します。

GET https://app.probetruth.ai/api/v1.0/deepfake/stats

Authentication Note:

原文では、このエンドポイントは Authorizationヘッダに email を入れる必要があると記載されています（APIトークンはサポートされない旨）。

Authorization: Bearer your_email@example.com

Example Request:

curl -X GET "https://app.probetruth.ai/api/v1.0/deepfake/stats" \
  -H "Authorization: Bearer your_email@example.com"

Success Response

{
  "statusCode": 0,
  "data": {
    "totalScans": 125,
    "completedScans": 118,
    "queuedScans": 2,
    "processingScans": 1,
    "failedScans": 3,
    "stoppedScans": 1
  }
}

Security & Best Practices

APIトークンは（失効させるまで）有効という記載
メディア本体はサーバ側の保持期間経過後に自動削除されるという記載
恒久的に保存されるのは SHA-256 ハッシュと分析レポートという記載
reportFileHash でレポートの整合性を検証できます
ステータスのポーリング間隔は過度に短くせず（例: 5–10秒）
複数確認には bulk status を使うと効率的です

Generate Report（レポート取得）

解析が完了（status が done）すると、詳細なフォレンジックレポートをダウンロードできます。レポートには判定（real/fake）、confidence、技術分析の詳細、視覚的証拠などが含まれると記載されています。

Endpoint

GET https://app.probetruth.ai/api/v1.0/reports/<filename>?apiToken=<your_api_token_here>

解析完了時のstatus APIレスポンスに reportUrl が含まれます（filenameはそこに含まれる）。取得時はクエリにAPIトークンを付与します。

Authentication

ブラウザダウンロード等の用途として、Authorizationヘッダの代わりにクエリ apiToken を使う例が記載されています。

?apiToken=<your_api_token_here>

Code Example

cURL - Download Report

curl -X GET "https://app.probetruth.ai/api/v1.0/reports/f3a1754b-3329-4851-8ec8-10df78beac2a.pdf?apiToken=<your_api_token_here>" \
  -H "Accept: application/pdf" \
  -o report.pdf

Response

Success (200 OK)

レポートファイル（通常PDF）がバイナリとして返ります。レスポンスには次が含まれます。

Content-Type: application/pdf
Content-Length
Content-Disposition: inline; filename="..."

%PDF-1.7
...binary PDF data...
%%EOF

Error Responses

HTTP Status Code	Response Body (JSON)	説明
`400 Bad Request`	`{"statusCode":-9999,"message":"Either email or apiToken query parameter is required"}`	認証に失敗。apiToken を付与してください。
`403 Forbidden`	`{"statusCode":-9999,"message":"File not found or access denied"}`	指定ファイルが存在しない、または権限がない（ユーザー所有ではない）可能性。
`500 Internal Server Error`	`{ "error": "Internal Server Error", "message": "Failed to generate report." }`	サーバ側で予期せぬエラーが発生。

Developer Notes

保持期間経過後、メディア本体は削除され、SHA-256ハッシュとレポートのみ保存されるという記載
ダウンロード後は reportFileHash で整合性確認することが推奨されています
レポートには判定、confidence、分析の詳細が含まれます

Common Error Codes

Status Code	Error Message	対応
400	Authorization header is required	`Authorization: Bearer <token>` を付与
400	File hash mismatch	SHA-256を「アップロードするバイト列」に対して再計算
400	Unsupported file extension	対応形式（mp4/png/jpg/mp3等）を使用
400	File size exceeds the limit	圧縮/リサイズなどでファイルサイズを削減
401	Invalid API token	ダッシュボードで新しいトークンを作成
403	User not found	トークンが登録ユーザーに紐付くか確認
403	File not found or access denied	ファイル存在/所有者（アカウント）を確認
404	Media not found	referenceId を確認
409	Task already in progress	完了まで待つ／先に stop する
500	Internal server error	リトライ、継続する場合はサポートへ

Best Practices for API Integration（推奨事項）

ローカルで事前検証: アップロード前に形式/サイズをチェック
ハッシュ計算を厳密に: アップロードするバイト列に対してSHA-256を計算
バックオフを実装: ステータスのポーリングは指数バックオフを検討
ステータスコードを網羅: 各HTTPステータスに応じたエラー処理
referenceId を保存: 後続のstatus/report取得に必要
レポート整合性: reportFileHash を必ず検証
bulk endpoint を活用: 複数タスクを効率的に確認
トークン管理: クライアントに露出させず安全に保管