Core concepts
Detection signals
What the Detect API measures, how confidence works, and why scores are signals rather than verdicts.
The Detect API estimates how likely a text is to be AI-generated and, more usefully, says why. Every score comes with the sentence-level habits and document-level structure behind it, so a person can check the reasoning.
Signals, not verdicts
Important:
Don't use a score as proof
Detectors are wrong in predictable ways. Perplexity-based detectors flagged 61% of essays by non-native English writers as AI, and “extremely minor” AI polishing got 43–65% of human texts flagged by leading detectors.
Never make a decision about a person (hiring, grading, moderation, payment) on a score alone.
That's why verdict has a mixed band, why confidence is explicit, and why every score ships with its reasons.
What a detection contains
| Field | Meaning |
|---|---|
ai_likelihood | 0–1 for the whole document. |
verdict | A banding of the score: likely_human below 0.35, mixed 0.35–0.70, likely_ai above 0.70. |
confidence | low, medium or high, driven mostly by length (below). |
sentences[] | Per-sentence score and the signal names that fired. |
structure[] | Document-level patterns, present or absent. |
Sentence signals
| Signal | What fires it |
|---|---|
stock_opener | “In today's fast-paced world…”, “In the ever-evolving landscape of…” |
inflation_frame | “more than just”, “isn't just X, it's Y”: inflating a claim by denying a smaller one. |
trailing_ing_clause | “…, highlighting the importance of…”. GPT-4o uses these at 5.3× the human rate. |
vocabulary_tell | Words models overuse: “delves” appeared at 28× its expected rate in 2024 PubMed abstracts. |
uniform_rhythm | Consecutive sentences of near-identical length and shape. |
triplet_list | Habitual three-item lists, especially of abstract nouns. |
Structural features
Structure is the strongest evidence we have, and it survives paraphrasing. On B2B blog posts, structure alone separates AI from human writing at 97.0 macro-F1, and still 96.1 after the AI rewords its own posts.
| Feature | AI posts | Human posts |
|---|---|---|
no_reader_action | 97% | 38% |
announced_thesis | 93% | 51% |
summary_section | 88% | 27% |
restated_close | 77% | 12% |
old_vs_new_frame | 76% | 26% |
Word-level methods are fragile by comparison: one paraphrase pass cut DetectGPT from 70.3% to 4.6% detection at a 1% false-positive rate, and cut a text watermark from 66.5% to 1.5%.
Source: Krishna et al., NeurIPS 2023; DAMAGE authors' test.Confidence and length
| Words | confidence | Advice |
|---|---|---|
| 40–149 | low | Show the reasons, not the number. A tweet can't carry enough evidence. |
| 150–599 | medium | Useful for triage and comparisons (before vs after a rewrite). |
| 600+ | high | Structural features are fully in play. |
Below 40 words the API returns 400 text_too_short.
Calibration
Some people write in ways population-level detectors misread: very formal, very consistent, or in a second language. Pass calibrate_to with a voice id and scores are reported relative to that writer's own baseline.
Tip:
Per-author fine-tuning cut a leading detector's flag rate from 97% to 3% in one study. Calibration is the same idea applied at scoring time. Read the guide.