AI AWARE
Developers

AI Aware detection API

Check text, images, video and audio for AI generation from your own software. The API runs the same detectors as this website and uses the credits on your account, at the same prices. See how accurate the detectors are in our accuracy test results.

Get an API keyQuick start

1. Your API keys

Loading…

2. Quick start

Every check is asynchronous: you submit it, get a job_id back at once, then poll until the status is done or error. Most text checks finish within seconds; long documents and videos can take a few minutes. Send your key in the X-API-Key header (Authorization: Bearer <key> works too).

Check a text

curl -s https://aidetector.aiaware.io/api/v1/public/text \
  -H "X-API-Key: $AIAWARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Paste the text you want to check here."}'
{
  "job_id": "3f6c1e0a-6a8e-4c38-9a53-0f5f2b0f7d11",
  "status": "processing",
  "word_count": 812,
  "credits_charged": 3,
  "poll_url": "https://aidetector.aiaware.io/api/v1/public/text/3f6c1e0a-6a8e-4c38-9a53-0f5f2b0f7d11"
}

Fetch the result

curl -s https://aidetector.aiaware.io/api/v1/public/text/JOB_ID -H "X-API-Key: $AIAWARE_API_KEY"

While the check runs, this answers with HTTP 202 and "status": "processing". Poll every few seconds.

In Python

import os, time, requests

BASE = "https://aidetector.aiaware.io/api/v1/public"
HEADERS = {"X-API-Key": os.environ["AIAWARE_API_KEY"]}

def check_text(text, timeout=600):
    r = requests.post(f"{BASE}/text", json={"text": text}, headers=HEADERS)
    r.raise_for_status()          # 402: not enough credits, 413: too long, 429: too many open checks
    job = r.json()
    deadline = time.time() + timeout
    while time.time() < deadline:
        res = requests.get(job["poll_url"], headers=HEADERS)
        body = res.json()
        if body["status"] != "processing":
            return body           # "done" with a result, or "error"
        time.sleep(3)
    raise TimeoutError(job["job_id"])

result = check_text(open("essay.txt").read())
print(result["result"]["verdict"], result["result"]["ai_share"])

3. Reference

Base URL: https://aidetector.aiaware.io/api/v1/public

MethodPathWhat it does
POST/textSubmit a text check: JSON {"text": …}, a form with a text field, a file (PDF, DOCX, TXT …) or a text/plain body.
GET/text/{job_id}Status and result of a text check. Add ?include_text=true to get the analysed text back (useful for files).
POST/mediaSubmit an image, video or audio file (multipart field file), or JSON {"url": …}. multimodal=true checks a video's picture and sound together.
GET/media/{job_id}Status and result of a media check.
GET/accountYour credit balance and limits.

Text files

curl -s https://aidetector.aiaware.io/api/v1/public/text -H "X-API-Key: $AIAWARE_API_KEY" -F "file=@essay.docx"

Text result

{
  "job_id": "3f6c1e0a-6a8e-4c38-9a53-0f5f2b0f7d11",
  "status": "done",
  "result": {
    "verdict": "mostly_human",
    "ai_share": 0.12,
    "document_score": 0.31,
    "max_segment_score": 0.83,
    "word_count": 812,
    "character_count": 4950,
    "segments": [
      { "start": 0,    "end": 1630, "score": 0.08, "ai": false },
      { "start": 1631, "end": 2240, "score": 0.83, "ai": true },
      { "start": 2241, "end": 4950, "score": 0.12, "ai": false }
    ]
  }
}
FieldMeaning
verdictOne of human, mostly_human, mixed, mostly_ai, ai, from ai_share (under 5%, under 30%, under 70%, under 95%, 95% or more). The same words the website shows.
ai_shareShare of the text, by characters, in passages the detector judges AI-written (0 to 1).
segmentsPassages as character offsets into the text, each with a score and ai (whether the passage counts as AI-written).
max_segment_scoreThe highest passage score. Useful to flag documents with a single suspicious passage.
document_scoreThe detector's score for the document as a whole.
Reading the scores. Scores run from 0 to 1 and are centred on the detector’s decision point: 0.5 is the threshold at which a passage counts as AI-written, and that threshold was set so that human writing is rarely flagged. A score is a confidence, not the probability that the text is AI-written. When in doubt the detector leans towards “human”: a result of human doesn’t prove a person wrote the text, and no result should be the only evidence in a decision about someone.

Media

curl -s https://aidetector.aiaware.io/api/v1/public/media -H "X-API-Key: $AIAWARE_API_KEY" -F "file=@photo.jpg"

# a video, checking picture and sound together
curl -s https://aidetector.aiaware.io/api/v1/public/media -H "X-API-Key: $AIAWARE_API_KEY" -F "file=@clip.mp4" -F "multimodal=true"

# or a public URL
curl -s https://aidetector.aiaware.io/api/v1/public/media -H "X-API-Key: $AIAWARE_API_KEY" \
  -H "Content-Type: application/json" -d '{"url": "https://example.com/image.png"}'
{
  "job_id": "a1d2c3b4-...",
  "status": "done",
  "result": {
    "media_type": "video",
    "verdict": "likely_ai",
    "score": 63.4,
    "modalities": [ { "modality": "visual", "score": 63.4, "verdict": "likely_ai" } ]
  }
}

score is 0 to 100. verdict is real (under 25), likely_real (25 to 50), likely_ai (50 to 75) or ai_generated (75 or more). A video with no picture is checked as audio, and media_type then says audio. Images with content credentials may also carry a provenance object.

4. Prices and limits

CheckCost
TextLoading…
Image…
Audio…
Video…
Video, picture and sound together (multimodal)…

Credits are taken when you submit a check, and the response says how many (credits_charged). Media checks that fail are refunded automatically. Text checks that fail are not yet refunded automatically: contact us with the job ID. Buy credits, or contact us for volume pricing.

LimitValue
Text length100,000 words per check
File size80 MB
Text filesPDF, DOCX, TXT and the other formats the website accepts
ImagesJPG, PNG, WebP, BMP
VideoMP4, MOV, M4V, AVI, MKV, WebM
AudioMP3, WAV, FLAC, OGG, M4A
Checks running at once10 per account (website and API together); more get HTTP 429

5. Errors

Errors come back with an HTTP status and a body like this; error is a fixed code your program can check.

{
  "detail": {
    "error": "insufficient_credits",
    "message": "This 812-word text needs 3 credits; you have 1.",
    "required": 3,
    "available": 1,
    "word_count": 812
  }
}
HTTPerrorWhat to do
400missing_input, ambiguous_input, invalid_jsonSend exactly one of text, file or URL.
401invalid_api_keyThe key is missing, mistyped or revoked.
402insufficient_creditsBuy credits, or shorten the text. required and available say how many.
404not_foundNo check with that ID on your account.
413too_many_words, file_too_largeSplit the text, or send a smaller file.
415unsupported_content_type, unsupported_file_typeUse a supported format (see the limits above).
422unreadable_file, no_text, url_fetch_failed, multimodal_needs_videoThe input could not be used.
429too_many_open_jobsWait for running checks to finish; Retry-After says when to try again.
503storage_unavailableTry again shortly. You were not charged.

A finished check can also come back with "status": "error" and a message, when the detection itself failed (for example a damaged file).

6. Keeping your key safe

  • Keep keys on your server. Never put one in a web page, a mobile app or a public repository.
  • Use one key per program, so you can revoke one without stopping the others.
  • If a key may have leaked, revoke it above at once and create a new one.

What happens to the content you submit is described in our privacy policy. Questions, or need something the API doesn’t do yet? Contact us.