APIドキュメント

AI画像検出API

TruthScanのAI画像検出APIをアプリケーションに統合するための完全なドキュメントです。

コードを書かずに試すには、以下のFastAPIエンドポイントをご利用ください： https://detect-image.truthscan.com/docs

認証

TruthScanではAPIアクセスにAPIキーを使用します。APIキーは開発者ポータルのページ上部.

すべてのAPIリクエストにAPIキーを含める必要があります：

{
  "key": "YOUR API KEY GOES HERE"
}

YOUR API KEY GOES HERE を実際のAPIキーに置き換えてください。

AI画像検出

検出（3ステップ）

AI画像検出は以下の手順で実行されます：

署名付きアップロードURLを取得
画像をアップロード
画像を送信して検出

1. 署名付きアップロードURLを取得

APIから署名付きURLを取得し、安全に画像をアップロードします。

対応形式

JPG, JPEG, PNG, WebP, JFIF, HEIC, HEIF, AVIF, BMP, TIFF, TIF

重要

ファイル名にスペースを含めないでください。

GET https://detect-image.truthscan.com/get-presigned-url?file_name=example.jpg

リクエスト例

curl -X GET 'https://detect-image.truthscan.com/get-presigned-url?file_name=example.jpg' \
--header 'apikey: YOUR API KEY GOES HERE'

レスポンス例

{
  "status": "success",
  "presigned_url": "https://image-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg?...",
  "file_path": "uploads/example.jpg"
}

2. 画像をアップロード

presigned_url を使ってPUTでアップロードします。

重要

アップロード時もファイル名のスペースを削除してください。

リクエスト例

curl -X PUT 'https://image-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg?...' \
  --header 'Content-Type: image/<FILE_FORMAT - jpeg, jpg, png, webp, heic, heif, avif, bmp, tiff, tif>' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.jpg' # Attachment

サイズ制限

最小: 1KB
最大: 10MB

アップロード成功時にはステータス200が返されます。

3. 画像を送信して検出

file_path を使用してAI検出を実行します。

POST https://detect-image.truthscan.com/detect

リクエスト例

curl -X 'POST' \
  'https://detect-image.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/<FILE_PATH>",
  "generate_preview": false,
  "generate_analysis_details": true
}'

FILE_PATH は最初のステップで取得した値です。

任意パラメータ

generate_preview: プレビューURLを生成（デフォルト: false）
document_type: ドキュメントタイプ（デフォルト: Image）
email: 処理用メールアドレス
generate_analysis_details: 詳細AI分析を有効化（デフォルト: false）

レスポンス例

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "status": "pending"
}

レスポンスには追跡用画像IDが含まれます。

結果取得

画像IDを使用して結果とステータスを取得します。

POST https://detect-image.truthscan.com/query

リクエスト例

curl -X 'POST' \
  'https://detect-image.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "IMAGE-ID-GOES-HERE"
}'

レスポンス例

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "metadata": [
            "No Information Detected for Real/AI",
            "Could not find anything from ExifTool and Pillow metadata"
        ],
        "metadata_basic_source": "null",
        "ocr": [
            "OCR did not detect AI",
            0.0
        ],
        "ml_model": [
            "AI Generated",
            90.2371538185235
        ],
        "confidence": 90.2371538185235,
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/uploads/....",
        "analysis_results_status": "pending",
        "analysis_results": null
    },
    "preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/..."
}

結果の解釈

result: 1〜100のAI確率スコア
final_result: 判定結果（AI生成 / 実写など）
confidence: 信頼度スコア
detection_step: 検出ステップ
metadata: メタデータ情報
ocr: OCR分析結果
ml_model: MLモデル結果
preview_url: プレビューURL
heatmap_status: ヒートマップステータス
heatmap_url: ヒートマップURL
analysis_results_status: 詳細分析ステータス
analysis_results: 詳細分析結果

重要

ヒートマップ生成は非同期で行われます。

result が高いほどAI生成の可能性が高いことを示します。

詳細分析

generate_analysis_details を有効にすると追加分析が行われます。

初期結果

基本結果はすぐ利用可能ですが詳細分析は処理中です。

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "confidence": 90.2371538185235,
        "analysis_results_status": "pending",
        "analysis_results": null
    }
}

対応方法

必要に応じてポーリングしてください。

分析進行中

analysis_results_status を確認してください。

curl -X 'POST' \
  'https://detect-image.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769"
}'

分析完了

analysis_results に詳細結果が含まれます。

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "confidence": 90.2371538185235,
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/uploads/....",
        "analysis_results_status": "done",
        "analysis_results": {
            "agreement": "strong",
            "confidence": 92,
            "keyIndicators": [
                "Unnaturally smooth skin texture",
                "Consistent lighting anomalies"
            ],
            "detailedReasoning": "The image shows clear signs of AI generation with unnaturally smooth textures and consistent lighting patterns not typical of real photography.",
            "visualPatterns": [
                "Uniform noise pattern typical of diffusion models"
            ],
            "recommendations": [
                "Cross-reference with original source if available",
                "Check for metadata inconsistencies",
                "Compare with known AI generation patterns"
            ]
        }
    },
    "preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/..."
}

利用不可

詳細分析が提供されない場合があります。

{
    "status": "done",
    "result": 12.5,
    "result_details": {
        "analysis_results_status": "skipped",
        "analysis_results": null
    }
}

分析フィールド

analysis_results_status: ステータス
analysis_results.agreement: 一致度
analysis_results.confidence: 信頼度
analysis_results.keyIndicators: 異常検出
analysis_results.detailedReasoning: 説明
analysis_results.visualPatterns: パターン
analysis_results.recommendations: 推奨事項

クレジット確認

APIキーで残りクレジットを確認します。

GET https://detect-image.truthscan.com/check-user-credits

リクエスト例

curl -X 'GET' \
  'https://detect-image.truthscan.com/check-user-credits' \
  -H 'apikey: YOUR API KEY GOES HERE' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json'

レスポンス例

{
    "baseCredits": 10000,
    "boostCredits": 1000,
    "credits": 11000
}

ヘルスチェック

API状態を確認します。

GET https://detect-image.truthscan.com/health

リクエスト例

curl -X 'GET' \
  'https://detect-image.truthscan.com/health' \
  -H 'accept: application/json'

レスポンス例

{
    "status": "healthy",
    "timestamp": "2024-01-15T10:30:00Z"
}

正常時は 'healthy' が返されます。

エラー

多くのエラーは不正なリクエストによるものです。

主なエラーコード：

コード	内容
400	不正なリクエスト
403	認証エラーまたはクレジット不足
404	リソース未存在
429	リクエスト過多
500	サーバーエラー

よくある問題と対処

認証エラー

"User verification failed" (403)

原因: APIキーが無効または期限切れ

対処:

APIキーが正しいか確認してください
アカウントでAPIキーが有効か確認してください
APIキーを再発行してみてください

"Not enough credits" (403)

原因: 画像処理に十分なクレジットがありません

対処:

/check-user-credits で残りクレジットを確認してください
必要に応じてクレジットを追加購入してください
アップロード前に画像サイズを最適化し、消費クレジットを減らしてください

入力エラー

"Unsupported file format" (400)

原因: 未対応または無効な画像形式です

対処:

対応形式か確認してください（JPG、JPEG、PNG、WebP、JFIF、HEIC、HEIF、AVIF、BMP、TIFF、TIF）
ファイルが破損していないか確認してください
アップロード時の Content-Type ヘッダーを確認してください

"File too large" (400)

原因: ファイルサイズが10MBの上限を超えています

対処:

10MB以下になるようリサイズまたは圧縮してください
アップロード前にファイルサイズを確認してください
可能なら WebP など効率的な形式をご利用ください

処理エラー

"Request timeout" (WebSocket)

原因: 画像処理に時間がかかりすぎました

対処:

より小さい、または単純な画像で試してください
サービスに高負荷がかかっていないか確認してください
リクエストを再試行してください

Document Status "failed"

原因: さまざまな理由で処理に失敗しました

対処:

画像が最小要件を満たすか確認してください（1KB〜10MB）
対応形式か確認してください
検出を送信する前にアップロードが完了したか確認してください
解決しない場合はサポートに問い合わせてください

アップロードエラー

"Image upload failed" (403/400)

原因: 事前署名URLが無効または期限切れ、またはストレージ側の問題です

対処:

事前署名URLは取得後すぐに使用してください（期限切れの可能性があります）
画像形式に合わせて Content-Type ヘッダーが正しいか確認してください
アップロード前にファイル名からスペースを削除してください
期限切れの場合は新しい事前署名URLを取得してください

"Invalid pre-signed URL" (400)

原因: ファイル名にスペースがある、または期限切れまたは破損した事前署名URLです

対処:

事前署名URLを取得する前にファイル名からスペースをすべて削除してください
ファイル名は英数字、ハイフン、アンダースコアのみを使用してください
必要に応じて新しい事前署名URLを生成してください

サポート

API利用についてはお問い合わせください。

お問い合わせ

FAQ

AI画像検出APIに関する質問