Metadata-Version: 2.4
Name: truthscan-image-detector-client
Version: 20260526.0.0
Summary: Official TruthScan Python client for AI image detection — presign, upload, detect, and poll for results.
Author: truthscan.com
License: MIT
Project-URL: Homepage, https://github.com/truthscan/image-detection-sdk
Project-URL: Documentation, https://github.com/truthscan/image-detection-sdk/tree/main/python
Project-URL: Repository, https://github.com/truthscan/image-detection-sdk
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31.0

# TruthScan Image Detection — Python Client

Official Python client for the [TruthScan AI Image Detection API](https://truthscan.com/truthscan-ai-image-detection-api-documentation). Detect whether images are AI-generated, real, digitally edited, or AI-edited.

## Requirements

- Python 3.9+
- A TruthScan API key ([get one here](https://truthscan.com))

## Installation

```bash
pip install truthscan-image-detector-client
```

## Quick start

```python
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`:

```python
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

```python
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

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

## License

MIT
