API

Credits & Rate-Limits

Wie Credits abgerechnet werden, welche Aktionen wie viel kosten, und welche Rate-Limits gelten.

Rankion verrechnet kostenpflichtige API-Aktionen über ein einfaches Credit-System. Reine Lese-Endpoints (GET-Listen, Status-Polls, Detail-Views) sind immer kostenlos — bezahlt wird nur, was Tokens, externe APIs oder GPU-Zeit verbraucht.

Was sind Credits?

Eine Plattform-weite Einheit. Egal ob Artikel-Generierung, AI-Visibility-Run, Backlink-Pull oder Image-Edit — alles wird in Credits abgerechnet.
Team-Balance. Credits hängen am Team, nicht am User. Alle Token desselben Teams ziehen aus demselben Topf.
Vorabbuchung. Credits werden beim Dispatch eines Jobs reserviert/abgebucht — nicht erst nach Abschluss. Das verhindert Race-Conditions, aber heißt auch: ein abgebrochener Job gibt Credits nicht automatisch zurück.

Credit-Mechanik

In Laravel-Begriffen liegt vor jedem kostenpflichtigen Endpoint die Middleware credits:N. Sie prüft den Team-Balance, bucht ab, und lässt erst dann den Controller laufen.

credits:N Middleware → bucht N Credits vor dem Job-Dispatch ab. Kommt das Team unter N, antwortet die API direkt mit 402 Insufficient Credits ohne Job-Dispatch.
Inline-Refreshes (z.B. Keyword-Explorer mit ?cache=false) ziehen pauschal 50 Credits direkt — der Cache-Bust ist die teure Operation.
Async-Jobs (HTTP 202) sind bereits bezahlt, sobald die Response kommt. Der Background-Worker erbt die Buchung; ein Worker-Crash erstattet nicht automatisch.

Credit-Kosten (Auswahl)

Aktion	Endpoint	Credits
Artikel generieren	`POST /v1/articles/{id}/generate`	5
Artikel optimieren	`POST /v1/articles/{id}/optimize`	5
Artikel repurposen (1 oder alle Formate)	`POST /v1/articles/{id}/repurpose`	3
Standalone-Artikel	`POST /v1/generate/article`	5
Image generieren	`POST /v1/generate/image`	5
Image bearbeiten (OpenAI Edits)	`POST /v1/images/{id}/edit`	10
Keyword-Research	`POST /v1/keywords/research`	5
Keyword A-Z expandieren	`POST /v1/keywords/{id}/expand`	10
Keyword Explorer (Seed-Pull)	`POST /v1/explorer`	50
Explorer Cache-Bust	`?cache=false` an Explorer-GETs	50
Content Audit	`POST /v1/content-audits`	10
Competitor Analysis	`POST /v1/competitor-analyses`	20
Internal-Links analysieren	`POST /v1/projects/{id}/internal-links/analyze`	5
Content-Optimizer Analyse / Apply	`POST /v1/content-optimizer/analyze` · `.../apply`	5 / 5
AI-Scanner Detect	`POST /v1/ai-scanner/detect`	2
Humanize-Article	`POST /v1/ai-scanner/humanize`	5
Humanize-Text (Standalone)	`POST /v1/humanize`	8
Content-Brief generieren	`POST /v1/tracking-projects/{id}/prompts/{p}/generate-brief`	3
Community-Scan	`POST /v1/community/scan`	5
Bulk-Generation (Artikel-Reihe)	`POST /v1/bulk-generations`	15
Pipeline (Multi-Stage)	`POST /v1/pipelines`	20
Page-Deep-Audit (Vision + KI-Render)	`POST /v1/page-audit`	30 + bis zu 3×15
Tracking-Project Report	`POST /v1/tracking-projects/{id}/generate-report`	10
Platform-Gap-Diagnose	`POST /v1/tracking-projects/{id}/insights/platform-gap/{platform}/diagnose`	1
GSC-Sync	`POST /v1/google/gsc/properties/{p}/sync`	1
Agentic Chat	`POST /v1/agentic/chat`	varies (abhängig von benutzten Tools)

Vollständige Liste: docs/API_REFERENCE.md — alle v1-Endpoints inkl. Credit-Spalte (Endpoint-Count + Datum werden bei /api-docs/markdown automatisch aus der Route-Tabelle injiziert). Live-Tabelle: rankion.ai/settings/api-documentation.

Insufficient Credits — HTTP 402

Reicht der Team-Balance nicht für die Aktion, antwortet die API mit 402 Payment Required:

{
  "message": "Insufficient credits",
  "error": "insufficient_credits",
  "required": 10,
  "available": 4
}

Der Job wird nicht dispatched, der Aufrufer kann den User informieren oder Credits nachladen. Den aktuellen Balance bekommst du jederzeit über die Credit-API.

Credit-API

# Aktueller Balance + Plan-Info
curl -H "Authorization: Bearer $TOKEN" "$BASE/credits"

# Buchungs-Historie (paginiert)
curl -H "Authorization: Bearer $TOKEN" "$BASE/credits/history"

Beispiel-Response für GET /v1/credits:

{
  "data": {
    "balance": 1240,
    "plan": "growth",
    "monthly_allotment": 5000,
    "renews_at": "2026-05-15T00:00:00Z"
  }
}

GET /v1/credits/history liefert je Eintrag: created_at, delta (negativ = Verbrauch, positiv = Top-up), endpoint, reference_id (z.B. die Artikel-ID), balance_after. Damit lässt sich exakt zuordnen, welche Aktion welche Credits verbraucht hat.

Rate-Limits

Zusätzlich zum Credit-System gibt es ein klassisches Request-Limit pro Token:

~60 Requests pro Minute pro Token als Standard für auth:sanctum-Routen.
Übersteigt der Client das Limit, antwortet die API mit 429 Too Many Requests plus Retry-After-Header.
Polling-Loops auf Async-Jobs deshalb nie aggressiver als alle 5 Sekunden — und immer mit Exponential-Backoff bei 429.

Spezielle Endpoints haben striktere Limits, z.B.:

POST /v1/tracking-projects/{id}/generate-report → 1 Request / 30 Min / Project. Sonst 429 {error: "rate_limited"}.
Public Share-Unlock (POST /share/{token}/unlock) → 5 / Minute (Brute-Force-Schutz).

Tipps zum sparsamen Umgang

Cache nutzen. Explorer und ähnliche Endpoints cachen 60 Min — ?cache=false nur, wenn wirklich frische Daten nötig sind.
Async-Polling vor neuem Dispatch. Vor einem zweiten POST /generate immer per GET prüfen, ob der erste Job schon läuft (status == processing). Sonst zahlst du doppelt.
include= verwenden wo unterstützt — spart Roundtrips und Quota-Kosten gegen Drittanbieter.

Weiter mit Projekte-API · zurück zu Authentifizierung.

Letzte Aktualisierung: 10. Mai 2026