API de AI Tools (Detector + Humanizer)

La API de AI Tools agrupa dos áreas: el AI Detector (detecta texto generado por IA y entrega un score de 0–100) y el Humanizer (reescribe texto IA para que suene más humano — single-shot o batch sobre varios documentos). Todos los endpoints viven bajo /v1/... y están scope al team.

Contexto del módulo: AI Detector · Humanizer.

AI Scanner (Detect + Humanize inline)

La vía rápida — Detection + Humanize sobre un artículo que ya vive en Rankion.

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

# Detection sobre un 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 analiza a nivel de párrafo y entrega un array tipo heatmap passages[] con score por párrafo. scan_type=snippet (por defecto) solo devuelve el score agregado.

El endpoint humanize reescribe inline un artículo ya existente en Rankion (sobrescribe article.content, crea versión) — el level controla la agresividad: light = ajustes de fraseo, medium = sintaxis + vocabulario, heavy = reformulación completa.

Humanizer (batch, async)

El endpoint dedicado del Humanizer acepta texto libre (sin necesidad de stub de artículo) y lo procesa como batch — ideal para reescritura bulk o workflows headless.

# Iniciar batch
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)

# Polling de status (async: 15–60 s por documento)
curl "$BASE/humanize/$BATCH" \
  -H "Authorization: Bearer $TOKEN"

Valores de status: queued → processing → completed (o 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
}

El texto humanizado completo lo obtienes vía GET /humanize/{batch_id}/documents/{id} (campo humanized_text).

Ejemplo completo: Detect → Humanize → Re-Detect

TEXT="..."  # texto IA original

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

# 4) Texto humanizado + nueva 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}'

Notas y pitfalls

• Humanize no garantiza un AI score 0. Realista: 80+ → 15–30. Quien promete «AI score 0» miente. Usa level=heavy para una reducción más fuerte (más cambio de estilo).
• /humanize es async, /ai-scanner/humanize es sync. Artículo único síncrono, bulk/texto libre asíncrono.
• La detection es probabilística. AI score < 30 = probablemente humano, > 70 = probablemente IA. Los valores intermedios deben interpretarse honestamente como ambiguos.
• Indica el idioma. Sin language, el Humanizer adivina — con mezcla de idiomas (DE en texto EN) los resultados empeoran.

Relacionado: API de Artículos · Créditos · AI Detector · Humanizer.