AI Tools API (Detector + Humanizer)

The AI tools API bundles two functional areas: the AI Detector (detects AI-generated text and returns a 0–100 score) and the Humanizer (rewrites AI text to feel more human — single-shot or as a batch across multiple documents). All endpoints live under /v1/... and are team-scoped.

Module context: AI Detector · Humanizer.

AI Scanner (detect + inline humanize)

The fast path — detect + humanize on an article that is already in Rankion.

TOKEN="$RANKION_API_TOKEN"
BASE="https://rankion.ai/api/v1"

# Detection on a snippet
curl -X POST "$BASE/ai-scanner/detect" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"text":"Artificial intelligence is revolutionizing the digital world...","scan_type":"snippet"}'

Response:

{
  "ai_probability": 87,
  "verdict": "likely_ai",
  "confidence": "high",
  "flagged_passages": [
    { "start": 0, "end": 142, "score": 92, "reason": "Generic opener pattern" }
  ]
}

scan_type=full analyzes at paragraph level and returns a heatmap array passages[] with a score per paragraph. scan_type=snippet (default) returns only the aggregate score.

The humanize endpoint rewrites an article that already exists in Rankion inline (overwrites article.content, creates a version) — the level controls aggressiveness: light = phrasing fixes, medium = sentence structure + vocabulary, heavy = full reformulation.

Humanizer (batch, async)

The dedicated humanizer endpoint accepts free text (no article stub needed) and processes it as a batch — ideal for bulk rewriting or headless workflows.

# Start batch
BATCH=$(curl -s -X POST "$BASE/humanize" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "text":"AI-generated original text, multiple paragraphs...",
    "language":"en",
    "level":"medium"
  }' | jq -r .batch_id)

# Poll status (async: 15–60 s per document)
curl "$BASE/humanize/$BATCH" \
  -H "Authorization: Bearer $TOKEN"

Status values: queued → processing → completed (or failed).

Response GET /humanize/{batch_id} (200):

{
  "batch_id": 19,
  "status": "completed",
  "language": "en",
  "level": "medium",
  "documents": [
    {
      "id": 102,
      "original_word_count": 740,
      "humanized_word_count": 758,
      "ai_score_before": 91,
      "ai_score_after": 22,
      "preview": "First 200 characters of the humanized text..."
    }
  ],
  "credits_used": 8
}

You fetch the full humanized text via GET /humanize/{batch_id}/documents/{id} (field humanized_text).

Complete example: detect → humanize → re-detect

TEXT="..."  # original AI text

# 1) Detection before
SCORE_BEFORE=$(curl -s -X POST "$BASE/ai-scanner/detect" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"text\":\"$TEXT\",\"scan_type\":\"snippet\"}" | jq -r .ai_probability)

# 2) Humanize batch
BATCH=$(curl -s -X POST "$BASE/humanize" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"text\":\"$TEXT\",\"level\":\"medium\"}" | jq -r .batch_id)

# 3) Poll
while [ "$(curl -s "$BASE/humanize/$BATCH" \
  -H "Authorization: Bearer $TOKEN" | jq -r .status)" != "completed" ]; do
  sleep 5
done

# 4) Humanized text + new detection
DOC_ID=$(curl -s "$BASE/humanize/$BATCH" \
  -H "Authorization: Bearer $TOKEN" | jq -r '.documents[0].id')
HUMANIZED=$(curl -s "$BASE/humanize/$BATCH/documents/$DOC_ID" \
  -H "Authorization: Bearer $TOKEN" | jq -r .humanized_text)

curl -s -X POST "$BASE/ai-scanner/detect" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"text\":\"$HUMANIZED\",\"scan_type\":\"snippet\"}" \
  | jq '{before: '$SCORE_BEFORE', after: .ai_probability}'

Notes & pitfalls

• Humanize does not guarantee an AI score of 0. Realistically: 80+ → 15–30. Anyone promising "AI score 0" is lying. Use level=heavy for stronger reduction (more style change).
• /humanize is async, /ai-scanner/humanize is sync. Single article sync, bulk/free text async.
• Detection is probabilistic. AI score < 30 = likely human, > 70 = likely AI. Treat values in between honestly as ambiguous.
• Specify language. Without language the humanizer guesses — with mixed language (DE in EN text) this leads to worse results.

Related: Articles API · Credits · AI Detector · Humanizer.