truthscan-image-detector-client 20260709.0.0

Official TruthScan Python client for AI image detection — presign, upload, detect, and poll for results.

TruthScan Image Detection — Python Client

Official Python client for the TruthScan AI Image Detection API. Detect whether images are AI-generated, real, digitally edited, or AI-edited.

Requirements

• Python 3.9+
• A TruthScan API key (get one here)

Installation

pip install truthscan-image-detector-client

Quick start

import os

from truthscan.image_detection import ImageDetectionClient

api_key = os.environ.get("TRUTHSCAN_API_KEY", "your_api_key_here")
client = ImageDetectionClient(api_key=api_key)

result = client.detect("path/to/image.jpg")

print(f"Status: {result['status']}")
print(f"Score: {result.get('result', 'N/A')}")
print(f"Final: {(result.get('result_details') or {}).get('final_result', '')}")

How it works

ImageDetectionClient.detect() runs the full workflow for you:

1. Presign — request a presigned upload URL for the image filename
2. Upload — upload the image bytes to storage
3. Detect — submit the image for analysis and receive a detection ID
4. Poll — call the query endpoint until status is done (or timeout)

You only need one method call; polling interval and max attempts are configurable on detect().

Send a request and poll manually

For step-by-step control, use ImageDetectionService:

from truthscan.image_detection import ImageDetectionService

service = ImageDetectionService(
    base_url="https://ai-image-detect.undetectable.ai",
    api_key=api_key,
)

presign = service.get_presigned_url("photo.jpg")
service.upload(presign["presigned_url"], "path/to/photo.jpg")

file_url = ImageDetectionService.build_detect_file_url(
    presign["file_path"], presign["presigned_url"]
)
detect = service.detect(file_url)

result = service.poll_for_result(detect["id"], max_attempts=60, sleep_seconds=0.5)
print(result["status"], result.get("result_details"))

Configuration

from truthscan.image_detection import ImageDetectionClient, DefaultConsoleLogger

client = ImageDetectionClient(
    api_key="YOUR_API_KEY",
    base_url=None,
    timeout=60,
    logger=DefaultConsoleLogger("info"),
)

API reference

ImageDetectionClient

Method	Description
detect(image, email?, generate_preview?, max_poll_attempts?, poll_interval_seconds?)	Full workflow: presign, upload, detect, poll. Returns DetectionResult.
check_user_credits()	Returns credit balance for the API key.

Supported file formats

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

File size limits: 1 KB – 10 MB

Note: Remove spaces from filenames before uploading.

Development

cd python
pip install -e .
python tests/test_client.py

License

MIT