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 keys Upgrade plan

Authentication

Customer requests need the `x-api-key` header. Create a named key in Studio and copy it immediately; the secret is shown only once. You can revoke a key at any time.

Example

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

Multipart fields

file - Required image blob (JPEG, PNG, WebP, HEIC/HEIF).
model - Optional model name. The admin-configured API default is used when omitted.

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. Create a named key in Studio API Access and save it in a server secret manager.
2. Send one `POST /api/detect` request with a representative image.
3. Consume `score`, `presentation`, and `modules` in your UI/workflow.
4. Monitor `X-RateLimit-*` headers and query GET /api/usage/status.

Rate limits

The API enforces burst, daily, and monthly quotas per account. Successful responses include `X-RateLimit-*` headers; throttled responses may include `Retry-After`.

Tier	Per minute	Daily	Monthly
Free	10	50	1,000
Premium	30	1,000	2,500
Enterprise	100	10,000	300,000

Response shape

Successful replies include a score, the fused verdict, presentation details, uncertainty, per-module insights, and an optional detection ID.

{
  "score": 87.3,
  "verdict": "AI generated",
  "presentation": { "label": "AI generation detected" },
  "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

Keep keys on your server, honor rate-limit headers, and revoke any key you suspect was exposed. Use GET /api/usage/status to show usage counters to your team.