AI Image Detection API: A Developer's Integration Guide

Why Developers Need AI Detection

If you are building a platform that handles user-uploaded images-a social network, a dating app, an e-commerce marketplace, a news platform, a hiring tool, or a content management system, you need to answer a fundamental question at scale: is this image real or AI-generated?

For high-trust platforms in 2026, that question has become mandatory. A growing share of profile photos on major platforms show signs of AI generation. AI-generated product photos mislead consumers. Synthetic news imagery spreads misinformation. Platforms that cannot verify image authenticity face regulatory risk, user trust erosion, and liability exposure.

The FauxLens AI Detection API provides the same analysis as a FauxLens scan through a simple REST interface: Content Credentials and metadata checks, detection of the invisible watermark Google and OpenAI embed in their AI images, and a specialist detection model's reading of the pixels. This guide covers everything you need to integrate AI detection into your application.

Architecture Overview

The FauxLens API accepts image uploads (or image URLs) and returns a structured JSON response containing a verdict, a confidence score and the evidence chain behind it. Image results usually come back within seconds; video takes longer. To build this into your own product, you can see the API here.

The system is designed for minimal data retention: uploaded images are deleted immediately after analysis and are not kept in persistent storage. This architecture is critical for platforms handling sensitive user content and for compliance with GDPR, CCPA, and similar data protection regulations.

Authentication

Authentication is a single bearer token. There is no request signing and no timestamp header.

curl -X POST https://api.fauxlens.com/v1/analyze \
  -H "Authorization: Bearer fxd_live_xxxxxxxxxxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@suspect_photo.jpg"

Create a key on the keys page. Keys are shown once and stored hashed, so a lost key is revoked and replaced rather than recovered. Keep the key server-side: the API path sends no CORS headers, so a browser call fails with an opaque network error.

Request Format

Image Upload (Multipart)

The primary endpoint accepts multipart form data with a file. Supported formats: JPEG, PNG, WebP, HEIC and AVIF up to 30MB; MP4, MOV, WebM and MKV up to 200MB.

POST /v1/analyze
Content-Type: multipart/form-data

Headers:
  Authorization   (required): Bearer fxd_live_...
  Idempotency-Key (required): a fresh UUID per operation

Parameters:
  file (file, required): the image or video to analyze

There are no per-signal toggles and no heatmap parameter: the pipeline runs its signals and returns the evidence chain it produced.

URL Submission

Alternatively, pass a publicly accessible image URL for the API to fetch and analyze.

POST /v1/analyze
Content-Type: application/json

{
  "url": "https://example.com/suspect.jpg"
}

URLs must be HTTPS. Private and loopback addresses are refused.

Response Format

The API returns a JSON envelope with a data object and three top-level fields.

{
  "data": {
    "summary": "Likely AI-Generated",
    "confidence_score": 0.94,
    "is_short_circuited": false,
    "evidence_chain": [
      {
        "layer": "Metadata Check",
        "status": "failed",
        "label": "Device Metadata",
        "detail": "No camera metadata present."
      }
    ],
    "short_id": "Ab3cD4eF"
  },
  "request_id": "req_9f2c...",
  "credits_remaining": 1990,
  "idempotent_replay": false
}

Response Fields Explained

Summary

data.summary is one of exactly four values: No AI Detected, Likely Authentic, Likely AI-Generated, AI-Generated. Treat them as an ordered scale rather than a boolean.

Confidence Score

data.confidence_score is a float between 0 and 1 expressing how strongly the evidence supports the verdict. 0.95 means the pipeline is highly confident, not that the image is 95% fake. Treat it as a ranking signal rather than a calibrated probability, and read the evidence chain alongside it.

Evidence Chain

data.evidence_chain is an array of per-layer results, each with a layer, a status of passed, warning or failed, a label and a human-readable detail. Store it alongside the verdict so a result you show a user can be traced back to the signals that produced it.

Short Circuiting

data.is_short_circuited is true when one signal was decisive enough that the remaining layers were skipped, which is why some responses return faster than others.

Credits

credits_remaining is your balance after the call. One call costs 10 credits, the same as one scan in the web app, and it spends the same wallet. idempotent_replay is true when your Idempotency-Key matched a previous request and you were served the cached verdict without being charged again.

Integration Patterns

Synchronous (Real-Time)

For user-facing applications where results must be displayed immediately (upload verification, content moderation dashboards), use the synchronous endpoint. Image results usually return within seconds; video takes longer. Set a generous client timeout - the upload dominates on a slow connection, and a large video has to finish uploading before analysis starts.

Background Processing

There is no asynchronous callback mode: every request is synchronous and returns the verdict in the same response. For a queue of flagged content, run the calls from your own worker and write the results back yourself. Reuse one Idempotency-Key per item so a retried job cannot be charged twice.

Rate Limiting

Developer keys are limited to 20 requests per minute; there is no monthly cap, because your credit balance is the quota. Exceeding the limit returns HTTP 429 with a Retry-After header. Implement exponential backoff with jitter, reusing the same Idempotency-Key so the retry cannot double-charge you.

Error Handling

The API uses standard HTTP status codes. Common responses:

• 200: Analysis complete. The verdict is data.summary; there is no top-level status field.
• 400: Bad request. Invalid image format, file too large, or missing required parameters.
• 401: Authentication failed. Invalid or expired API key.
• 402: Insufficient credits. Top up and retry.
• 409: Idempotency-Key already charged for a different request. Use a new one.
• 429: Rate limit exceeded. Check Retry-After header.
• 500: Internal server error. Retry with exponential backoff.

Production Best Practices

Threshold Calibration

Do not use a single threshold for all use cases. A dating platform detecting fake profiles should use a lower threshold (flag more aggressively, accept more false positives) than a news organization verifying press photos (require higher confidence before flagging, minimize false positives). Calibrate thresholds based on the cost asymmetry of false positives vs. false negatives in your specific domain.

Human-in-the-Loop

For high-stakes decisions (account bans, content removal, legal evidence), never automate the final action based solely on API results. Use the API to surface suspicious content for human review. The evidence chain provides what a human reviewer needs to make an informed decision quickly.

Caching and Deduplication

If the same image is submitted multiple times (common in social sharing contexts), implement perceptual hashing on your end to deduplicate before calling the API. This reduces API costs and latency without sacrificing detection coverage.

Frequently Asked Questions

What does the API cost?

One call costs 10 credits, the same as one scan in the web app - about 5 cents on the $9.99 credit pack, which is 200 calls. Your free starting credits cover a few calls, once. There is no monthly free allowance and no subscription. See the developer API page for the full breakdown.

What image formats are supported?

JPEG, PNG, WebP, HEIC, and AVIF. For best detection accuracy, submit the highest-quality version available. JPEG recompression degrades some forensic signals.

How is image data handled?

Uploads are written to a temporary file, analysed, and deleted immediately afterwards. They are not kept in persistent storage.

Can the API detect AI video?

Yes. Send an MP4, MOV, WebM or MKV file the same way you send an image, up to 200MB. A video call costs the same 10 credits as an image, though it takes longer to return because the upload dominates.

What languages and frameworks are supported?

Any language that can make an HTTP request. There are no SDKs to install and none are planned - the API is one POST with one header, and worked curl and Python examples are on the developer API page.