> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gowinston.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Node SDK

> Integrate Winston AI into Node.js applications with the official SDK. Learn how to install and authenticate the package, configure the client, detect AI-generated text and images, check plagiarism and facts, compare text, and handle API errors.

# Winston AI Node.js SDK ⚡️

Detect AI-generated text and images, check for plagiarism, fact-check content, and compare text through a fully typed interface with our official Node.js SDK.

[View on npm](https://www.npmjs.com/package/@winston-ai/ai-detector) · [GitHub](https://github.com/gowinston-ai/ai-detector-node) · [Open the developer dashboard](https://dev.gowinston.ai)

## Installation

Install the package with npm:

```bash theme={null}
npm install @winston-ai/ai-detector
```

### Requirements

* Node.js 20 or later
* A Winston AI API key

Create an API key in the [Winston AI developer dashboard](https://dev.gowinston.ai/user/api-tokens). New accounts receive 2,000 free credits, with no credit card required.

We recommend storing your key in an environment variable for security reasons:

```bash theme={null}
WINSTON_AI_API_KEY=your-winston-ai-api-key
```

## Quickstart

Import the client, initialize it with your API key, and submit text for analysis:

```ts theme={null}
import { WinstonAIClient } from "@winston-ai/ai-detector";

const client = new WinstonAIClient(
  process.env.WINSTON_AI_API_KEY! // Key found in your environment variable
);

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 is also supported:

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

## Available methods

### Detect AI-generated text

Analyze text, a public file, or a public webpage for signs of AI generation.

```ts theme={null}
const result = await client.detectText({
  text: "Content to analyze...",
  sentences: true,
  language: "auto",
});
```

### Detect AI-generated images

Analyze an image using metadata and Winston AI's image detection model.

```ts theme={null}
const result = await client.detectImage({
  url: "https://example.com/image.jpg",
});
```

### Run advanced image analysis

Inspect an image using forensic signals such as error-level analysis, noise maps, and edge anomalies.

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

### Check for plagiarism

Compare content against sources found across the web.

```ts theme={null}
const result = await client.checkPlagiarism({
  text: "Content to check...",
  language: "auto",
});
```

### Fact-check content

Evaluate claims against trusted sources and receive a verdict for each claim.

```ts theme={null}
const result = await client.checkFact({
  text: "Content to fact-check...",
  language: "auto",
});
```

### Compare two texts

Measure similarity and matching word counts between two texts.

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

## Client configuration

Configure automatic retries for transient network and API failures:

```ts theme={null}
const client = new WinstonAIClient(
  process.env.WINSTON_AI_API_KEY!,
  {
    maxRetries: 1,
    retryBaseDelayMs: 500,
  }
);
```

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

## Error handling

The SDK throws a typed error for non-2xx responses and connection failures:

```ts theme={null}
import {
  WinstonAIError,
  WinstonAuthenticationError,
  WinstonPaymentRequiredError,
  WinstonRateLimitError,
} from "@winston-ai/ai-detector";

try {
  const result = await client.detectText({ text: "Content to analyze..." });
} catch (error) {
  if (error instanceof WinstonRateLimitError) {
    // Back off and try again later.
  } else if (error instanceof WinstonAuthenticationError) {
    // Check the API key.
  } else if (error instanceof WinstonPaymentRequiredError) {
    // Add credits to the account.
  } else if (error instanceof WinstonAIError) {
    console.error(error.status, error.error, error.description);
  } else {
    throw error;
  }
}
```

## Resources

* [API documentation](https://docs.gowinston.ai/api-reference/introduction)
* [Developer dashboard](https://dev.gowinston.ai)
* [Winston AI](https://gowinston.ai)
* [Interpreting AI detection scores](https://gowinston.ai/interpreting-our-ai-detection-scores/)
* [To see what types of content you can scan](https://help.gowinston.ai/understanding-winston-ai/what-types-of-content-can-i-scan-with-winston-ai)