API ドキュメント

AI 画像検出 API

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

コードを書かずに試すには、次の FastAPI エンドポイントにアクセスしてください： https://detect-image.truthscan.com/docs

認証

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

API キーは、エンドポイントがヘッダのみの認証を記載していない限り（例: check-user-credits）、次のような JSON ボディのリクエストに含めます。

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

YOUR API KEY GOES HERE は自分の API キーに置き換えてください。

レート制限

API は API キーごとに 1 分あたりのリクエスト予算を適用します。書き込み系エンドポイントは読み取り系より重みが大きくなります。デフォルトは 1 分あたり 60 リクエストです。より高い上限が必要な場合はお問い合わせください。

エンドポイント重み

各呼び出しは、その重みを 1 分あたりの予算から差し引きます。

エンドポイント	種別	重み
POST /detect	書き込み	1
POST /bulk-upload	書き込み	1
GET /get-presigned-url	読み取り	0.2
GET /check-user-credits	読み取り	0.2
POST /heatmap/{id}	読み取り	0.2
POST /preview/{id}	読み取り	0.2
POST /query	読み取り	対象外
GET /health	読み取り	対象外

例: 60/分の予算では、書き込み 60 回、読み取り約 300 回、または加重合計が 1 分あたり ≤ 60 となる任意の組み合わせを送信できます。

制限時のレスポンス (HTTP 429)

1 分あたりの予算を超えると、API は次を返します。

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 3
X-RateLimit-Retry-After: 3
Content-Type: application/json

{
  "error": "Too many requests"
}

レート制限のレスポンスヘッダ

X-RateLimit-Limit — 1 分あたりの容量。
X-RateLimit-Remaining — このリクエスト後の現在の 1 分間の残り回数。
X-RateLimit-Reset — (429 のときのみ) 次の書き込みリクエストが送れるまでの秒数。
X-RateLimit-Retry-After — (429 のときのみ) X-RateLimit-Reset と同値で Retry-After 形式。

推奨されるクライアント挙動

成功レスポンスの X-RateLimit-Remaining を見て送信ペースを調整してください。
429 を受けたら少なくとも X-RateLimit-Retry-After 秒待機し、指数バックオフ + ジッターで再試行してください。
バッチでは多数の /detect 並列呼び出しよりも POST /bulk-upload（1 回で最大 50 画像処理）を推奨します。

AI 画像検出

検出（3 ステップ）

AI 画像検出のワークフローは次のとおりです。

プリサイン済みアップロード URL を取得する
画像をアップロードする
検出のために画像を送信する

1. プリサイン済みアップロード URL を取得する

まず API からプリサイン URL を取得します。この URL で画像ファイルをストレージに安全にアップロードできます。

対応ファイル形式

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

ファイル名

プリサイン URL を要求する際、画像ファイル名からスペースを除いてください。

PDF ファイルでは、単一ファイルフローでは先頭の 1 枚のみが検出されます。

一括アップロードで ZIP を送る場合は、このエンドポイントで .zip のファイル名を使用してください。

クエリパラメータ

file_name（必須）— 元のファイル名。サーバー側で正規化される場合があります（スペースや安全でない文字が調整されます）。一括アップロードには .zip 拡張子を使用してください。
expiration（任意）— プリサイン URL の有効期限（秒）。既定は 3600 です。

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://nyc3.digitaloceanspaces.com/ai-image-detector-dev/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg...",
  "file_path": "uploads/example.jpg",
  "document_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

document_id はこのアップロード要求用に新規発行された UUID です（相関・ログ用）。/detect や /bulk-upload で使う id は、それらのエンドポイント送信時に割り当てられます（/detect で任意の id を渡さない場合）。

2. 画像をアップロードする

返された presigned_url に対し PUT で画像をアップロードします。画像形式に合わせて Content-Type を正しく設定してください。

ファイル名

画像をアップロードする際も、ファイル名からスペースを除いてください。

Content-Type は拡張子と完全一致するよう設定してください

image/jpeg: jpg, jpeg, jfif
image/png: png
image/webp: webp
image/heic: heic
image/heif: heif
image/avif: avif
image/bmp: bmp
image/tiff: tiff, tif
image/gif: gif
image/svg+xml: svg
application/pdf: pdf

よくある誤り

image/jpg は誤りです。image/jpeg を使用してください。
ファイルとヘッダを一致させないでください（例: .png なのに image/jpeg）。
拡張子だけ、またはヘッダだけを変えないでください。
要求時・アップロード時にファイル名にスペースを含めないでください。

リクエスト例

curl -X PUT 'https://nyc3.digitaloceanspaces.com/ai-image-detector-dev/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg...' \
  --header 'Content-Type: image/jpeg' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.jpg'

アップロードの追加例（PNG, PDF, SVG）

curl -X PUT '<PRESIGNED_URL_FOR_example.png>' \
  --header 'Content-Type: image/png' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.png'

curl -X PUT '<PRESIGNED_URL_FOR_example.pdf>' \
  --header 'Content-Type: application/pdf' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.pdf'

curl -X PUT '<PRESIGNED_URL_FOR_example.svg>' \
  --header 'Content-Type: image/svg+xml' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.svg'

ファイルサイズの上限

最小: 1KB
最大: 10MB

アップロード中もファイル形式を一貫させてください。成功時は HTTP 200 が返ります。

3. AI 検出のために画像を送信する

アップロード後、前ステップの file_path を参照して AI 検出をリクエストします。PDF の場合は先頭の 1 枚のみが解析・検出の対象です。

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": true
}'

FILE_PATH はプリサイン URL 手順で返されたパス（例: uploads/...）です。例のとおりストレージホストと組み合わせて完全な URL を構築してください。

任意パラメータ

id: 任意の UUID 文字列。省略時はサーバーが新しい document id を生成します。指定する場合は未使用である必要があります。既に存在する場合はエラーになります。
generate_preview: true にすると画像のプレビュー URL を生成します（既定: true）。false でプレビュー生成を省略します。
document_type: ドキュメント種別（既定: Image）。
email: 処理用のメールアドレス。
generate_analysis_details: false にすると詳細分析の生成を省略します（既定: true）。
generate_heatmap_overlayed: ヒートマップ生成時の出力の仕方を制御します（既定: true）。true のときは元画像にヒートマップを重ねた標準オーバーレイ。false のときは透明背景の RGBA ヒートマップ（JET 色の活性マップとモデル由来のアルファ）を返し、UI 上で合成できます。
generate_heatmap_normalized: false のとき、活性マップに用いる正規化ステップを省略します（既定: true）。generate_heatmap_overlayed と併用して見た目を調整します。
model: モデルまたはルーティング指定（既定: generic）。例: generic、または instance_id/model（例: my-instance-id/generic）で専用キューに送れます。無効な instance_id は 400 で拒否されます。
user_agent: 分析・サポート用にドキュメントに保存する任意の文字列。

レスポンス例

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

レスポンスには検出状況の追跡用に一意の画像 ID が含まれます。

検出ステータスと結果の照会

ステータス確認と結果取得には、画像 ID を指定して /query エンドポイントを呼び出します。

認証: リクエストボディには id のみが含まれ、この呼び出しでは API キーは送られません。UUID を知る者は誰でも結果をポーリングできます。スコアの閲覧を制限する場合は document 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,
        "warnings": [
            { "type": "blur_dark", "label": "Blurred" },
            { "type": "watermark", "label": "Gemini", "confidence": 0.95 },
            { "type": "screen_recapture", "label": "screen", "metrics": { "is_screen": false }, "confidence": 99.99 }
        ]
    },
    "preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/..."
}

レスポンス例（/query、組織でセキュア URL が有効な場合）

{
    "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-detect.undetectable.ai/heatmap/00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
        "analysis_results_status": "ready",
        "analysis_results": null
    },
    "preview_url": "https://ai-image-detect.undetectable.ai/preview/00fee5ff-a55b-42fb-b7c7-d14f05ae0769"
}

分析結果が準備できたときのレスポンス例

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/uploads/....",
        "analysis_results_status": "ready",
        "analysis_results": {
            "imageTags": ["person", "portrait", "outdoor", "vineyard", "smiling"],
            "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/..."
}

結果の各フィールド

is_valid: 画像ファイルが有効かどうか（true/false）。
detection_step: 検出が完了した段階: 1 = メタデータのみ、2 = メタデータと ocr、3 = メタデータ・ocr・ml_model。
final_result: 総合判定（例: "AI Generated", "Real", "Digitally Edited", "AI Edited"）。
confidence: 検出の信頼度スコア。
metadata: ExifTool と Pillow により画像メタデータから抽出した情報。
metadata_basic_source: 特定のモバイルカメラで撮影されたか、AI ツールで生成されたか、編集ソフトで加工されたかなどを示す場合があります。
ocr: 歴史的フィールド名 ocr のウォーターマーク検出結果。2 要素配列 [label, score]: label は検出クラス（例: "Gemini"）または "OCR did not detect AI"、score は 0–100 スケール（不明時は 0）。ラベルがある場合は warnings に要約されます。
ml_model: 機械学習モデルの結果。
warnings: 任意の警告オブジェクトの配列（type: blur_dark, watermark, screen_recapture など）。空または省略される場合があります。
preview_url: generate_preview が true のときのプレビュー画像 URL。直接ストレージ、またはセキュア URL 有効時は https://<api-host>/preview/<document_id> などの API パスになる場合があります。
heatmap_status: pending、ready、failed のいずれか。ヒートマップ生成は非同期です。
heatmap_url: heatmap_status が ready のときのヒートマップ。見た目は generate_heatmap_overlayed に依存。直接ストレージまたは https://<api-host>/heatmap/<document_id>（セキュア時は POST /heatmap/{id} と key で取得）。
analysis_results_status: pending、ready、skipped、failed、analyzing。generate_analysis_details が false のときは省略または null。
analysis_results: 有効時の詳細な説明分析。下記「分析結果の説明」を参照してください。

分析結果の説明

analysis_results が ready のとき、通常は agreement（strong | moderate | weak | disagreement）、imageTags（最大 5 つの短いタグ）、confidence（0–100）、keyIndicators、detailedReasoning、visualPatterns、recommendations が含まれます。

注記

ヒートマップ生成は非同期です。heatmap_status と heatmap_url は /query をポーリングして確認してください。
詳細分析も非同期です（generate_analysis_details=false を除く）。analysis_results_status と analysis_results をポーリングしてください。
セキュア URL: 有効な場合、heatmap_url と preview_url は API ホストになることがあります。キー付きで POST /heatmap/{id} および POST /preview/{id} で取得します（「セキュアなヒートマップとプレビュー」参照）。
メインスコアの後にヒートマップと analysis_results が揃うことがあるため、完了後も /query を再取得してください。

ヒートマップとオーバーレイの挙動

heatmap_url のファイルは /detect（または /bulk-upload）の generate_heatmap_overlayed と generate_heatmap_normalized を反映します。既定のオーバーレイ（true）は通常画像に重ねたヒートマップ、false は合成用の透明 PNG になりやすいです。

例: result が約 90.24、final_result が AI Generated、detection_step が 3 のとき、メタデータ・OCR・ML モデルまで完了しています。

分析結果（非同期の詳細分析）

/detect で generate_analysis_details が true のとき、メインスコアの後に詳細分析が完了することがあります。analysis_results_status が ready（または skipped/failed）になるまで /query をポーリングしてください。

1. 初期結果は分析より先に出る場合がある

コア検出（result、final_result、confidence）は、analysis_results_status がまだ pending のうちに得られることがあります。

{
    "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 が必要ならポーリングを続けてください。

2. ポーリングを続ける

同じ id で /query を呼び、analysis_results_status が pending から変わるまで待ちます。

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

3. 分析完了

analysis_results_status が ready になれば、analysis_results に agreement、imageTags、confidence、keyIndicators、detailedReasoning、visualPatterns、recommendations が含まれます。

{
    "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": {
            "imageTags": [
                "person",
                "portrait",
                "outdoor",
                "vineyard",
                "smiling"
            ],
            "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/..."
}

分析が利用できない場合

analysis_results_status が skipped/failed、または欠落、あるいは generate_analysis_details が false のときは、コア検出を最終結果として扱ってください。

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

分析結果のフィールド

analysis_results_status: pending | ready | skipped | failed | analyzing
analysis_results.agreement: strong | moderate | weak | disagreement
analysis_results.imageTags: 短い説明タグ
analysis_results.confidence: 0–100
analysis_results.keyIndicators: 具体的な手がかり
analysis_results.detailedReasoning: 短い説明
analysis_results.visualPatterns: より広いパターン
analysis_results.recommendations: 次のステップ

一括アップロード（ZIP）

ZIP で複数画像を一度に送れます。単一画像と同様: プリサイン（.zip 名）→ PUT で ZIP → POST /bulk-upload → /query をポーリング。

1. プリサイン URL を取得する（ZIP）

get-presigned-url に .zip のファイル名（例: images.zip）を指定します。

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

リクエスト例

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

2. ZIP をアップロードする

プリサイン URL に Content-Type: application/zip で PUT します。

curl -X PUT '<PRESIGNED_URL_FOR_images.zip>' \
  --header 'Content-Type: application/zip' \
  --header 'x-amz-acl: private' \
  --data-binary '@images.zip'

ZIP の制限

ZIP 最大サイズ: 100MB
1 バッチあたり最大 50 画像
各画像: 最小 1KB、最大 10MB

ZIP 内の対応形式

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

ZIP 内の PDF は非対応のためスキップされます。

SVG は検出前に PNG に変換されます。

3. ZIP を一括検出に送信する

POST /bulk-upload に key と、アップロード済み ZIP のパスを url で指定します。

任意パラメータ

generate_preview: true で各画像のプレビュー URL を生成（既定: false）。
generate_analysis_details: true で詳細分析を生成（既定: false）。
generate_heatmap_overlayed: /detect と同じ（オーバーレイと透明 RGBA ヒートマップ）。
generate_heatmap_normalized: /detect と同じ（既定: true）。
model: モデル種別: generic、または instance_id/model 形式。

リクエスト例

curl -X 'POST' \
  'https://detect-image.truthscan.com/bulk-upload' \
  -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": false,
  "model": "generic"
}'

レスポンス例

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

id、status pending、expected_count（ZIP から解析対象となる画像数）が返ります。

一括 ZIP の結果の更新

送信直後は status が pending、処理開始後は analyzing になります。
results に各画像が並び、未完了は result と result_details が null のままです。
result_details 内のヒートマップや詳細分析は、完了までまだ pending な場合があります。
results のすべてが終わると全体 status が done。バッチが完了できない場合は failed になり得ます。
ZIP 完了前でも /query で部分結果を確認できます。

4. 一括アップロード結果の照会

POST /query に /bulk-upload の id を渡します。単一画像と同じエンドポイントで、id が単一画像か ZIP バッチかでレスポンス形状が変わります。

curl -X 'POST' \
  'https://detect-image.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9"
}'

レスポンス例（処理中）

{
  "id": "3b81fb24-dd23-40e7-ae95-82f823f44098",
  "status": "analyzing",
  "results": [
    {
      "id": "4600c7e5-00ec-469d-9117-ff20e0f1c1fa",
      "status": "done",
      "result": 44.0006,
      "result_details": {},
      "filename": "photo1.jpg",
      "preview_url": null
    },
    {
      "id": "2f770c89-352a-4d53-b6a3-a2147ca2c0ae",
      "status": "pending",
      "result": null,
      "result_details": null,
      "filename": "photo2.jpg",
      "preview_url": null
    }
  ],
  "skipped": []
}

レスポンスフィールド（一括 ZIP）

id — 一括リクエストの id。
status — pending の後 analyzing、最後に done または failed。
results — 解析中の各画像のエントリ（id, status, result, result_details, filename、利用可能なら preview_url）。
skipped — 解析されなかったファイル（非対応型・サイズなど）。status failed、理由は result_details に。

課金: クレジットは正常に解析された画像にのみ消費されます。SVG 変換失敗やスキップされたファイルは課金されません。

セキュアなヒートマップとプレビュー

/query の heatmap_url または preview_url がオブジェクトストレージではなく API ホストを指す場合は、POST と API キーでバイナリを取得します。

POST /heatmap/{id}

POST /preview/{id}

リクエストボディ JSON: { "key": "YOUR-API-KEY-GOES-HERE" }

ヒートマップの応答（HTTP ステータスと Content-Type を確認）

200 + バイナリ（image/png など）— ヒートマップ取得済み。X-Heatmap-Status が付く場合があります。
202 + JSON — heatmap_status pending。/query をポーリングして再試行。
200 + JSON — ヒートマップなし（任意機能・失敗など）。サーバーエラーではありません。
500 + JSON — heatmap_url はあるがストレージから取得できなかった。後で再試行。
404 + JSON — document id が見つかりません。
403 + JSON — API キーがこのドキュメントを所有していません。

プレビュー: POST /preview/{id} はプレビューのバイナリを返します。generate_preview が false の場合はプレビューなしで 404 + JSON になります。

例

curl -X POST 'https://detect-image.truthscan.com/heatmap/00fee5ff-a55b-42fb-b7c7-d14f05ae0769' \
  -H 'Content-Type: application/json' \
  -d '{"key":"YOUR-API-KEY-GOES-HERE"}' \
  --output heatmap.png

curl -X POST 'https://detect-image.truthscan.com/preview/00fee5ff-a55b-42fb-b7c7-d14f05ae0769' \
  -H 'Content-Type: application/json' \
  -d '{"key":"YOUR-API-KEY-GOES-HERE"}' \
  --output preview.png

内部: 組織利用量の Stripe 同期（ジョブシークレット）

信頼できるバックエンドジョブのみ。一般 API 利用者向けではありません。ヘッダ x-job-secret がサーバーの JOB_SECRET と一致する必要があります。指定期間の TruthScan 組織の従量課金利用を Stripe に同期します。

POST /organizations/{org_id}/usage/sync-to-stripe

Headers: x-job-secret: <JOB_SECRET>

ボディ JSON: start_date, end_date、任意で Stripe メーター用の idempotency_id。

success, organization_id, total_documents, value_sent_to_stripe, report_date, message を返します。組織が従量課金でない、または stripe_customer_id が必要なのに欠ける場合は 400；シークレット不正は 401；組織なしは 404；Stripe/設定エラーは 500。

ユーザー残クレジットの確認

ユーザーの apikey をヘッダで受け取り、クレジット情報を返します。

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
}

外部連携では credits フィールドのみが埋まります。

ヘルスチェック

API サーバーの稼働状態を確認します。

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

リクエスト例

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

レスポンス例

{
    "status": "healthy"
}

「healthy」はサービスが正常に動作していることを示します。

エラー

多くは API に誤ったパラメータを送ったことが原因です。各呼び出しを再確認し、例を参考にしてください。

一般的なエラーコードは REST の慣例に沿っています。

コード	意味
400	Bad Request — リクエストが無効です。
401	Unauthorized — 内部ジョブ用エンドポイントでジョブシークレットが無効など、認証に失敗しました。
403	Forbidden — API キーが無効、アクセス拒否、またはクレジット不足です。
404	Not Found — 指定したリソースが存在しません。
405	Method Not Allowed — 許可されていない HTTP メソッドでアクセスしました。
406	Not Acceptable — JSON 以外の形式を要求しました。
410	Gone — このエンドポイントのリソースは削除されました。
422	Invalid Request Body — ボディの形式が誤っている、無効、または必須パラメータが欠けています。
429	Too Many Requests — API キーごとのレート制限を超過しました（「レート制限」を参照）。ボディは {"error":"Too many requests"}、X-RateLimit-Retry-After ヘッダで再試行までの待機秒数が分かります。
500	Internal Server Error — サーバー側の問題でした。しばらくしてから再試行してください。
503	Service Unavailable — メンテナンス等のため一時的に利用できません。後ほどお試しください。

よくある問題と対処

認証まわり

"User verification failed" (403)

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

対処:

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

"Not enough credits" (403)

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

対処:

/check-user-credits で残りクレジットを確認してください
必要に応じてクレジットを追加購入してください

入力検証

"Input URL cannot be empty" (400)

原因: URL が空または無効である

対処:

url 入力が空でないことを確認してください
画像名の前後の空白を削除してください
URL エンコードが正しいか確認してください

"Input email is empty" (400)

原因: URL 処理に必要なメールが未入力

対処:

URL 送信時に有効なメールアドレスを指定してください
メール形式が正しいか確認してください

"Unsupported image type" (400)

原因: 非対応のファイル形式

対処:

対応形式（JPG, PNG, WebP, HEIC, HEIF, AVIF, BMP, TIFF, GIF, SVG, PDF など）に変換してください
拡張子が正しいか確認してください

"File size is too small" (400)

原因: 画像が最小サイズ未満

対処:

より大きい画像を使用してください（最小 1KB）
アップロード中に破損していないか確認してください

"File size exceeds limit" (400)

原因: 画像が大きすぎる

対処:

圧縮またはリサイズしてください（上限はデプロイにより異なり、エラーメッセージに MB が示されます）
別の画像形式を試してください

"Invalid file type" (400)

原因: ファイル種別の検証に失敗

対処:

有効な画像形式であることを確認してください
ファイルが破損していないか確認してください
MIME タイプが拡張子と一致しているか確認してください

処理

画像ステータスが "failed"

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

対処:

URL が対応形式か確認してください
画像ファイルが有効で破損していないか確認してください
サイズ要件を満たしているか確認してください
解消しない場合はサポートに連絡してください

"User not found"

原因: ユーザー ID が無効

対処:

ユーザー ID が正しいか確認してください
アカウントが有効か確認してください
必要に応じて再認証してください

"File metadata could not be fetched" (500)

原因: アップロード済みファイルにアクセスできない

対処:

ファイルが正常にアップロードされたか確認してください
ファイル URL にアクセスできるか確認してください
再アップロードを試してください

アップロード

"Image upload failed" (403/400)

原因: プリサイン URL が無効または期限切れ、またはストレージ側の問題

対処:

プリサイン URL は取得後すぐに使用してください
Content-Type がファイル形式と一致しているか確認してください
アップロード前にファイル名からスペースを除いてください
必要に応じて新しいプリサイン URL を取得してください

"Invalid pre-signed URL" (400)

原因: ファイル名にスペースがある、またはプリサイン URL が期限切れ・破損

対処:

プリサイン URL 取得前にファイル名からスペースを除いてください
英数字・ハイフン・アンダースコアを使用してください
必要に応じて新しいプリサイン URL を取得してください

一括アップロード

"URL must point to a ZIP file" (400)

原因: /bulk-upload に渡した URL が ZIP を指していない

対処:

get-presigned-url?file_name=images.zip（など .zip 名）を使用してください
有効な ZIP をプリサイン URL にアップロードしてください
bulk-upload の url がその ZIP を指しているか確認してください

"ZIP file too large" (400)

原因: ZIP が最大サイズ（100MB）を超えている

対処:

画像数を減らすか圧縮してください
複数回に分けて一括アップロードしてください

"Too many files" (400)

原因: ZIP 内の有効な画像が 50 枚を超えている

対処:

1 回あたり 50 枚以下にしてください
複数の ZIP に分割してください

"No valid images found in ZIP" (400)

原因: ZIP 内のすべてのファイルがスキップされた（非対応形式・小さすぎる・無効なパスなど）

対処:

対応形式（JPG, PNG, WebP, HEIC, HEIF, AVIF, BMP, TIFF, TIF, GIF, SVG）を使用してください
一括では PDF は非対応です
各画像は 1KB 以上 10MB 以下にしてください
隠しファイル（先頭が .）やパストラバーサル（..）を避けてください

"Document is not a bulk upload (image-zip) result" (400)

原因: id がアップロード種別と一致しない（単一画像と ZIP バッチの取り違え）

対処:

単一画像の送信は /detect の id を使用してください
ZIP 送信は /bulk-upload の id を使用してください

サポートが必要ですか？

API の利用方法や技術サポートについては、お問い合わせください。

お問い合わせ

API に関するよくある質問

TruthScan の AI 画像検出 API についてよくある質問と回答です。