Official Node.js / TypeScript SDK for the Winston AI API. Detect AI‑generated text and images, check for plagiarism, fact‑check content and compare text with a simple, fully typed interface.

Fully typed requests and responses
Typed error classes you can branch on
Automatic retries with exponential backoff
Works in Node.js (20+) using the native fetch

About us

Winston AI is the world’s best AI content detector, as demonstrated by multiple independent third-party studies. Trained on vast and diverse datasets, it accurately detects content generated by leading AI models, including ChatGPT, Claude, Gemini, and others.

Installation

npm install @winston-ai/ai-detector

Authentication

All endpoints are authenticated with a Bearer token. Create an account on the Winston AI developer dashboard to generate an API key. You'll get 2000 free credits to start, no credit card required.

Quick start

import { WinstonAIClient } from "@winston-ai/ai-detector";

const winstonAIKey = "your-winston-ai-api-key";
const client = new WinstonAIClient(winstonAIKey);

const result = await client.detectText({
  text: "The text you want to analyze. Provide at least 300 characters for reliable results...",
});

console.log(result.score); // 0 = likely AI, 100 = likely human

CommonJS works too:

const { WinstonAIClient } = require("@winston-ai/ai-detector");

Client configuration

const client = new WinstonAIClient(apiKey, {
  maxRetries: 1,        // retries after the first attempt (default: 1, max: 5)
  retryBaseDelayMs: 500, // base delay for exponential backoff (default: 500)
});

Retries apply to network failures and to 408, 409, 429, 500, 502, 503, 504 responses.

API

Every method returns a typed Promise and throws a WinstonAIError on failure.

Method	Endpoint	Credit cost
`detectText`	`/ai-content-detection`	1 credit / word
`detectImage`	`/image-detection`	300 credits / image
`detectAdvancedImage`	`/advanced-image-detection`	500 credits / image
`checkPlagiarism`	`/plagiarism`	2 credits / word
`checkFact`	`/fact-checker`	2 credits / word
`compareText`	`/text-compare`	½ credit / total words in both texts

`detectText(params)`

Detect whether text was written by a human or generated by AI. Provide text, a public file URL, or a public website URL. If more than one is supplied, the API prefers: website > file > text.

const result = await client.detectText({
  text: "Content to analyze...",
  // file: "https://example.com/document.pdf",
  // website: "https://example.com/article",
  // version: "latest",   // defaults to the API's latest model
  // sentences: true,      // include per-sentence scores
  // language: "auto",     // 2-letter code or "auto"
});

console.log(result.score);            // human score, 0–100
console.log(result.readability_score);
console.log(result.credits_remaining);

`detectImage(params)`

Detect AI‑generated images using metadata (C2PA, EXIF) and a machine‑learning model.

const result = await client.detectImage({
  url: "https://example.com/image.jpg", // JPG, JPEG, PNG or WEBP, min 256×256
  // version: "5", // omit to automatically use the latest version
});

console.log(result.score);            // 0 = AI, 100 = human
console.log(result.human_probability);
console.log(result.ai_watermark_detected);

`detectAdvancedImage(params)`

Run an advanced forensic analysis (ELA, noise maps, edge anomalies, and more) on a public image URL.

const result = await client.detectAdvancedImage({
  image_url: "https://example.com/image.png",
});

console.log(result.label);        // "AI-Generated" | "Human"
console.log(result.confidence);   // "High" | "Moderate" | "Low"
console.log(result.authenticity); // "Authentic" | "Manipulated"
console.log(result.conclusion);

`checkPlagiarism(params)`

Scan text for plagiarism against content found across the web.

const result = await client.checkPlagiarism({
  text: "Content to check...",
  // file / website also supported
  // excluded_sources: ["example.com"],
  // language: "auto",
  // country: "us",
});

console.log(result.result.score);   // plagiarism percentage
console.log(result.sources.length); // matching sources

`checkFact(params)`

Verify the accuracy of content against trusted sources.

const result = await client.checkFact({
  text: "Content to fact-check...", // min 300 characters
  // file / website also supported
  // language: "auto",
});

console.log(result.score);       // overall accuracy, 0–100
for (const claim of result.claims) {
  console.log(claim.verdict);    // SUPPORTED | PARTIALLY_SUPPORTED | NOT_ENOUGH_EVIDENCE | REFUTED
  console.log(claim.explanation);
}

`compareText(params)`

Compare two texts and measure their similarity.

const result = await client.compareText({
  first_text: "The first text to compare...",
  second_text: "The second text to compare...",
});

console.log(result.similarity_score);                    // 0–100
console.log(result.first_text.matching_word_count);
console.log(result.second_text.similarity_percentage);

Error handling

The SDK throws on any non‑2xx response or connection failure. Catch the base WinstonAIError, or narrow to a subclass to react to a specific status.

import {
  WinstonAIClient,
  WinstonAIError,
  WinstonRateLimitError,
  WinstonAuthenticationError,
  WinstonPaymentRequiredError,
} from "@winston-ai/ai-detector";

try {
  const result = await client.detectText({ text: "..." });
} catch (err) {
  if (err instanceof WinstonRateLimitError) {
    // back off and retry later
  } else if (err instanceof WinstonAuthenticationError) {
    // invalid or missing API key
  } else if (err instanceof WinstonPaymentRequiredError) {
    // out of credits
  } else if (err instanceof WinstonAIError) {
    console.error(err.status, err.error, err.description);
  } else {
    throw err;
  }
}

Every WinstonAIError exposes status (HTTP status), error (API error code), and description (human‑readable message).

Class	Status	Meaning
`WinstonBadRequestError`	400	Invalid or malformed request
`WinstonAuthenticationError`	401	Missing or invalid API key
`WinstonPaymentRequiredError`	402	Insufficient credits
`WinstonPermissionDeniedError`	403	Forbidden (e.g. inaccessible URL/file)
`WinstonUnsupportedMediaTypeError`	415	Unsupported content type
`WinstonRateLimitError`	429	Rate limit exceeded
`WinstonInternalServerError`	≥ 500	Error on the Winston AI side
`WinstonConnectionError`	—	Network failure before a response

TypeScript

The package ships type definitions. Request and response interfaces are exported for use in your own code:

import type {
  AiTextDetectionRequest,
  AiTextDetectionResponse,
  AiImageDetectionResponse,
  AdvancedAiImageDetectionResponse,
  PlagiarismResponse,
  FactCheckResponse,
  TextCompareResponse,
} from "@winston-ai/ai-detector";