API

Detectiks Detection API

Send an image, get a verdict. The REST endpoint evaluates visual artifacts, metadata, frequency, physics, optional ML models, and fuses every signal into a single response. Premium and Enterprise plans include API access, rate limits, and usage telemetry.

Manage keysUpgrade plan

Authentication

Every request needs the `x-api-key` header. Generate or rotate a key from your Studio and copy it before sending any detection requests.

Example

curl -X POST https://your-site.com/api/detect
-H 'x-api-key: imag_your_key_here'
-F 'file=@/path/to/image.jpg'
-F 'model=flux-v1'

Multipart fields

  • file - Required image blob (JPEG, PNG, WebP, HEIC/HEIF).
  • model - Optional slug to evaluate a specific model (sanitized on the backend).

Headers (optional)

  • x-detection-source - Tag requests as `extension`, `extension-local`, or `website` for downstream analytics.

Quickstart

Recommended rollout: create a key, validate with one image, then instrument quota and error handling before scale.

  1. 1. Create or rotate your key in Studio API Access.
  2. 2. Send one `POST /api/detect` request with a representative image.
  3. 3. Consume `score`, `presentation`, and `modules` in your UI/workflow.
  4. 4. Monitor `X-RateLimit-*` headers and query GET /api/usage/status.

Rate limits

The API enforces burst and daily quotas per tier. Every response adds `X-RateLimit-*` headers plus a `Retry-After` when throttled.

TierPer minuteDailyMonthly
Free10501,000
Premium301,0002,500
Enterprise10010,000300,000

Response shape

Successful replies include a score, the fused verdict, presentation copy, uncertainty, per-module insights, and cached hashes for deduplication.

{
  "score": 87.3,
  "verdict": "AI generated",
  "presentation": "AI generation detected with high confidence",
  "confidence": 0.97,
  "uncertainty": 0.02,
  "explanations": [
    "Metadata mentions Adobe Firefly",
    "Frequency grid detected near reflections"
  ],
  "hashes": {
    "sha256": "171f290b04b6ca5705e6f6b2c4a0c796edc4a1d7efb2a7a7ae357c4b5d314e74"
  },
  "modules": {
    "visual": {
      "score": 0.92,
      "flags": ["skin_smoothing", "melting_edges"]
    },
    "metadata": {
      "score": 0.78,
      "flags": ["firefly_signature"]
    },
    "physics": {
      "score": 0.65,
      "flags": []
    },
    "frequency": {
      "score": 0.88,
      "flags": ["grid_artifact"]
    },
    "ml": {
      "score": 0.93,
      "flags": []
    },
    "provenance": {
      "score": 0.4,
      "flags": []
    },
    "fusion": {
      "score": 0.87,
      "flags": []
    }
  }
}

Key fields

  • score - 0-100 probability that the image is AI-generated.
  • presentation - Human-friendly label for UI.
  • modules - Deep insights per forensic module.

Usage headers

  • X-RateLimit-Limit - Maximum requests within the current burst window.
  • X-RateLimit-Remaining - Remaining credits in this window.
  • X-RateLimit-Reset / Retry-After - When you can retry after a throttle.

Errors & protective guards

  • 401 Unauthorized - Missing, disabled, or revoked API key. Rotate the key from your Studio.
  • 429 Rate limit - Burst or daily quotas exceeded. Respect the `Retry-After` header before retrying.
  • 413 Payload too large - Files must be <= 10 MB.
  • 415 Unsupported media - Only JPEG/PNG/WebP/HEIC/HEIF are allowed.

Best practices

Cache hashes on your side to avoid duplicated work, honor rate-limit headers, and tag every request with `x-detection-source` so we can attribute requests in the analytics dashboard. Use GET /api/usage/status to show usage counters to your team.