gptzero

What this skill does

# GPTZero API Integration

## Overview

GPTZero is a specialized AI content detection service providing per-document and per-sentence AI probability scores. It detects output from GPT-family, Claude, Gemini, and other LLMs.

- **API base URL:** `https://api.gptzero.me/v2`
- **Auth:** `x-api-key` header
- **Docs:** https://gptzero.me/docs

## Instructions

### Authentication

Set `GPTZERO_API_KEY` in your environment, then use it in the `x-api-key` header for all requests.

### Single Text Analysis — POST `/v2/predict/text`

Send `{ "document": "<text>" }` as JSON. Returns a response with:
- `completely_generated_prob` (0-1) — probability the entire document is AI-generated
- `average_generated_prob` (0-1) — average AI probability across sentences
- `overall_burstiness` — burstiness score (low = more AI-like)
- `sentences[]` — per-sentence objects with `generated_prob`, `perplexity`, and `highlight_sentence_for_ai`

### Score Interpretation

| `completely_generated_prob` | Meaning                  |
|-----------------------------|--------------------------|
| > 0.80                      | Very likely AI-generated |
| 0.50 - 0.80                | Mixed / uncertain        |
| < 0.50                      | Likely human-written     |

### File Upload — POST `/v2/predict/files`

Upload PDF, DOCX, or TXT files using multipart form data. Returns the same document structure as text analysis.

### Batch Processing

GPTZero free tier allows ~10 req/min. For bulk scanning, process in batches with concurrency control (e.g., 3 concurrent requests with 300ms delay between batches).

### Flagged Sentences

Filter `sentences` where `highlight_sentence_for_ai === true` to extract the specific sentences GPTZero considers AI-generated.

## Examples

### Example 1: Scanning a student essay

A university teaching assistant checks a submitted essay using the GPTZero API:

```
POST https://api.gptzero.me/v2/predict/text
Headers: { "x-api-key": "gz-abc123...", "Content-Type": "application/json" }
Body: { "document": "The Industrial Revolution fundamentally transformed Western society in numerous ways. It is worth noting that the shift from agrarian economies to industrial manufacturing created unprecedented urbanization. Furthermore, the development of steam power and mechanized production significantly altered labor dynamics and social structures across Europe and North America." }

Response:
{
  "documents": [{
    "completely_generated_prob": 0.89,
    "average_generated_prob": 0.85,
    "overall_burstiness": 0.12,
    "sentences": [
      { "sentence": "The Industrial Revolution fundamentally transformed Western society in numerous ways.", "generated_prob": 0.78, "highlight_sentence_for_ai": true },
      { "sentence": "It is worth noting that the shift from agrarian economies...", "generated_prob": 0.95, "highlight_sentence_for_ai": true },
      { "sentence": "Furthermore, the development of steam power...", "generated_prob": 0.91, "highlight_sentence_for_ai": true }
    ]
  }]
}

Verdict: AI-generated (89% probability). All 3 sentences flagged.
```

### Example 2: Verifying a journalist's draft

An editor checks a news article draft before publication:

```
POST https://api.gptzero.me/v2/predict/text
Body: { "document": "At 3:47 AM on Tuesday, a pipe burst in the basement of Mel's Diner on Crenshaw Blvd, flooding the kitchen where owner Melinda Torres had just finished prepping 40 pounds of brisket for the lunch rush. 'I heard it pop and I just stood there watching the water come up,' Torres said. 'Twenty-two years in this spot and nothing like this has happened.' The city's Department of Water and Power dispatched a crew by 5 AM." }

Response:
{
  "documents": [{
    "completely_generated_prob": 0.08,
    "average_generated_prob": 0.11,
    "overall_burstiness": 0.67,
    "sentences": [
      { "sentence": "At 3:47 AM on Tuesday, a pipe burst...", "generated_prob": 0.05, "highlight_sentence_for_ai": false },
      { "sentence": "'I heard it pop and I just stood there...'", "generated_prob": 0.03, "highlight_sentence_for_ai": false },
      { "sentence": "The city's Department of Water and Power...", "generated_prob": 0.12, "highlight_sentence_for_ai": false }
    ]
  }]
}

Verdict: Human-written (8% probability). No sentences flagged.
```

## Guidelines

- Minimum text length: ~250 characters for reliable results
- Best accuracy on English text; other languages are supported but less reliable
- Paraphrased or lightly edited AI text may score lower than raw AI output
- Does not detect AI-generated images or code
- Free tier: ~10,000 words/month, ~10 req/min; check https://gptzero.me/pricing for paid plans
- Handle HTTP 429 (rate limit) by waiting 60s and HTTP 402 (quota exceeded) by checking your plan
- Always route flagged content to human review — no detector is 100% accurate