Preds REST API

Minden végpont a /api/v1 útvonal alatt érhető el, HTTPS-t és JSON-t igényel.

Alap URL és verzió

Egy stabil v1 felület érhető el.

Alap URL-ek

https://preds.hu/api/v1

Kötelező fejlécek

Authorization: Api-Key ${PREDS_API_KEY}
Content-Type: application/json

Hitelesítés

Minden kéréshez csatolja az API-kulcsot.

Fejléc példa

curl -X GET https://preds.hu/api/v1/usage/api/   -H "Authorization: Api-Key sk_live_123"

A nem használt kulcsokat vonja vissza a vezérlőpultban.
Szolgáltatásonként külön kulcs javasolt a biztonságos és megfelelő használathoz.

POST /api/v1/detect/api/

Egy szöveg elemzése kvóta metaadatokkal.

Kérés törzse

{
  "text": "Illessze be az ellenőrizendő szöveget.",
  "request_id": "f1e9c1da-1ce3-4f3f-bf63-3cc6d9cf7f21"
}

Válasz

{
  "request_id": "a759869e-2cfb-4e4e-9ded-bf292a4a791d",
  "prediction": "ai",
  "confidence": 0.824,
  "quota": {
    "remaining": 742,
    "used_from": "plan"
  },
  "rate_limit": {
    "limit": 60,
    "remaining": 58
  }
}

A minimum 60 szó, a bemenetet csak 100 000 karakterig veszi figyelembe.

POST /api/v1/detect/batch/

Legfeljebb 20 szöveget küldhet egyszerre; minden elem egy kvótát fogyaszt.

Kérés törzse

{
  "texts": [
    "Esszé bekezdés...",
    "Második szöveg"
  ]
}

Válasz

{
  "results": [
    { "request_id": null, "prediction": "human", "confidence": 0.62 },
    { "request_id": null, "prediction": "ai", "confidence": 0.91 }
  ],
  "quota": {
    "remaining": 740
  },
  "rate_limit": {
    "limit": 60,
    "remaining": 40
  }
}

Erre is érvényes a limiter, csak bizonyos számú detektálást lehet küldeni egy perc alatt.
Ha több szöveget szeretne egyszerre osztályozni, használja az async végpontot.

POST /api/v1/detect/async/

Sorbaállítja a feladatokat a végpontot, és egyből visszaad egy feladatazonosítót.

Kérés törzse

{
  "text": "Illessze be az ellenőrizendő szöveget."
}

Elfogadott válasz

{
  "task_id": "b2b6c9c2-1c2e-4e3c-9a3d-43c7c9326d2f",
  "status": "pending",
  "status_url": "/api/v1/tasks/b2b6c9c2-1c2e-4e3c-9a3d-43c7c9326d2f/status/",
  "result_url": "/api/v1/tasks/b2b6c9c2-1c2e-4e3c-9a3d-43c7c9326d2f/result/"
}

A kvóták és kreditek a sorba állítás pillanatában kerülnek levonásra.

POST /api/v1/detect/batch/async/

Legfeljebb 20 szöveget sorba állít, az eredményt később a feladat végpontokról kérheti le.

Kérés törzse

{
  "texts": ["Bekezdés A", "Bekezdés B"]
}

Elfogadott válasz

{
  "task_id": "5bd0c2fa-d9de-4d7c-b3da-54fe4f1f2c5c",
  "status": "pending",
  "batch_size": 2,
  "status_url": "/api/v1/tasks/5bd0c2fa-d9de-4d7c-b3da-54fe4f1f2c5c/status/",
  "result_url": "/api/v1/tasks/5bd0c2fa-d9de-4d7c-b3da-54fe4f1f2c5c/result/"
}

Az összes kvóta azonnal levonásra kerül.

Feladat státusz

Ezekkel a végpontokkal követheti az aszinkron műveleteket.

GET /api/v1/tasks/<id>/status/

{
  "task_id": "b2b6c9c2-1c2e-4e3c-9a3d-43c7c9326d2f",
  "status": "started",
  "message": "Task is currently processing"
}

GET /api/v1/tasks/<id>/result/

{
  "task_id": "b2b6c9c2-1c2e-4e3c-9a3d-43c7c9326d2f",
  "status": "completed",
  "data": { "results": [ { "submission_id": 1341, "prediction": "ai" } ] }
}

OCR végpontok

PDF feltöltésekből készít tiszta szöveget, amit aztán detektálhat.

POST /api/v1/ocr/extract/

curl -X POST https://preds.hu/api/v1/ocr/extract/   -H "Authorization: Api-Key $PREDS_API_KEY"   -F "[email protected]"

POST /api/v1/ocr/public/

curl -X POST https://preds.hu/api/v1/ocr/public/   -F "[email protected]"

A végpont kvóta metaadatot és opcionális quota_reservation tokent is visszaad.

Felhasználási végpontok

Ezekkel figyelheti a kvótát és a számlázási időszakot.

GET /api/v1/usage/api/

{
  "period_start": "2025-01-01",
  "period_end": "2025-02-01",
  "shared_limit": 1000,
  "shared_used": 248,
  "shared_remaining": 752,
  "api_used": 120,
  "web_used": 128,
  "credits_available": 1200
}

GET /api/v1/usage/

{
  "usage": { "period_start": "2025-01-01", "total_used": 248, "credits_available": 1200 },
  "billing_events": [],
  "available_periods": ["2025-02-01"],
  "selected_period": "2025-02-01"
}

Folyamat figyelje, hogy ne fusson ki a limitekből.

Előzmény végpontok

Listázhatja vagy lekérheti a mentett beküldéseket előnézettel és metaadatokkal.

GET /api/v1/history/

curl -X GET https://preds.hu/api/v1/history/   -H "Authorization: Api-Key $PREDS_API_KEY"

GET /api/v1/history/<public_id>/

curl -X GET https://preds.hu/api/v1/history/5c2a9a6a-7c7c-4f61-9d2c-76d21a9e2d1b/   -H "Authorization: Api-Key $PREDS_API_KEY"

A válasz tartalmaz időbélyegeket, eredményekről metaadatokat.

POST /api/v1/reports/

PDF jelentést generál egy korábbi beküldéshez.

Kérés törzse

{
  "submission_id": 1341,
  "filename": "audit-week42",
  "analyzed_text": "Opcionális cenzúrázott változat."
}

Válasz

{
  "id": 22,
  "submission": 1341,
  "filename": "audit-week42",
  "prediction": "ai",
  "report_generated_at": "2025-09-27T07:02:11.114220Z"
}

Megosztható, visszakövethető bizonyítékot készíthet.

POST /api/v1/reports/false-detections/

Jelentse a gyanús téves találatokat belső felülvizsgálatra.

Kérés törzse

{
  "submission_id": 1341,
  "origin": "detect"
}

Válasz

{
  "id": 14,
  "submission_id": 1341,
  "prediction": "ai",
  "reported_at": "2025-09-27T07:44:11.114220Z"
}

Egy beküldés csak egyszer jelenthető, minden eset felülvizsgálatra kerül.

GET /api/v1/keys/

Listázza az aktív API kulcsokat.

cURL kérés

curl -X GET https://preds.hu/api/v1/keys/   -H "Authorization: Api-Key $PREDS_API_KEY"

Válasz

[
  {
    "id": 18,
    "name": "Production ingest",
    "last_used_at": "2025-09-26T12:24:01.911Z",
    "created_at": "2025-07-02T09:12:44.120Z"
  }
]

Új kulcsot létrehozni vagy törölni a vezérlőpultban ajánlott.

Hiba válaszok

A hibák szabványos HTTP kódot és struktúrált JSON-t adnak.

Hiba példa

{
  "detail": "Quota exceeded. Daily free predictions exhausted.",
  "code": "quota_exceeded",
  "request_id": "f2e7a6f5-1f9c-4e0b-a921-0f2fc0f6d3d1"
}

A `code` mezőből derül ki, hogy kvóta-, auth- vagy validációs hiba történt.
Minden hiba tartalmaz `request_id` értéket.