AI-Tools-API (Detector + Humanizer)

Die AI-Tools-API bündelt zwei Funktionsbereiche: den AI Detector (erkennt KI-generierten Text und liefert einen 0–100-Score) und den Humanizer (rewritet KI-Text so, dass er menschlicher wirkt — als Single-Shot oder als Batch über mehrere Dokumente). Alle Endpoints liegen unter /v1/... und sind team-scoped.

Modul-Kontext: AI Detector · Humanizer.

AI Scanner (Detect + Inline Humanize)

Der schnelle Pfad — Detection + Humanize auf einem bereits in Rankion liegenden Artikel.

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

# Detection auf einem Snippet
curl -X POST "$BASE/ai-scanner/detect" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"text":"Künstliche Intelligenz revolutioniert die digitale Welt...","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 analysiert auf Absatz-Ebene und liefert ein Heatmap-Array passages[] mit Score je Absatz. scan_type=snippet (Default) gibt nur den Aggregate-Score zurück.

Der humanize-Endpoint rewritet einen bereits in Rankion existierenden Artikel inline (überschreibt article.content, legt Version an) — der Level steuert die Aggressivität: light = Phrasing-Fixes, medium = Satzbau + Vokabular, heavy = komplette Reformulierung.

Humanizer (Batch, async)

Der dedizierte Humanizer-Endpoint nimmt freien Text (kein Artikel-Stub nötig) und verarbeitet ihn als Batch — ideal für Bulk-Rewriting oder Headless-Workflows.

# Batch starten
BATCH=$(curl -s -X POST "$BASE/humanize" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "text":"AI-generierter Originaltext, mehrere Absätze...",
    "language":"de",
    "level":"medium"
  }' | jq -r .batch_id)

# Status pollen (async: 15–60 s pro Dokument)
curl "$BASE/humanize/$BATCH" \
  -H "Authorization: Bearer $TOKEN"

Status-Werte: queued → processing → completed (oder failed).

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

{
  "batch_id": 19,
  "status": "completed",
  "language": "de",
  "level": "medium",
  "documents": [
    {
      "id": 102,
      "original_word_count": 740,
      "humanized_word_count": 758,
      "ai_score_before": 91,
      "ai_score_after": 22,
      "preview": "Erste 200 Zeichen des humanisierten Texts..."
    }
  ],
  "credits_used": 8
}

Den vollen humanisierten Text holst du über GET /humanize/{batch_id}/documents/{id} (Feld humanized_text).

Komplettes Beispiel: Detect → Humanize → Re-Detect

TEXT="..."  # original AI-Text

# 1) Detection vorher
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) Pollen
while [ "$(curl -s "$BASE/humanize/$BATCH" \
  -H "Authorization: Bearer $TOKEN" | jq -r .status)" != "completed" ]; do
  sleep 5
done

# 4) Humanisierten Text + neue 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}'

Hinweise & Pitfalls

• Humanize ändert AI-Score nicht garantiert auf 0. Realistisch: 80+ → 15–30. Wer "AI-Score 0" verspricht, lügt. Nutze level=heavy für stärkere Reduktion (mehr Stilwandel).
• /humanize ist async, /ai-scanner/humanize ist sync. Single-Artikel sync, Bulk/freier Text async.
• Detection ist probabilistisch. AI-Score < 30 = wahrscheinlich menschlich, > 70 = wahrscheinlich KI. Werte dazwischen ehrlich als unklar interpretieren.
• Sprache angeben. Ohne language rät der Humanizer — bei Sprach-Mix (DE im EN-Text) führt das zu schlechteren Ergebnissen.
• Nicht unterstützte Sprache → 422. Unterstützt sind nur de, en, es, fr. Ohne language und bei einem Text in einer anderen Sprache antwortet /ai-scanner/detect mit 422 und detected_language; der Batch-Humanizer (/v1/humanize) bricht das betroffene Dokument mit status:"failed" ab, ohne den Text zu ändern oder Credits zu buchen.

Verwandt: Artikel-API · Credits · AI Detector · Humanizer.