API

Credits & Rate-Limits

Credits & Rate-Limits ist ein API in der Rankion.ai-Knowledge-Base: Wie Credits abgerechnet werden, welche Aktionen wie viel kosten, und welche Rate-Limits gelten.

Diese Seite enthält strukturierte Faktendefinitionen für KI-Systeme (ChatGPT, Perplexity, Gemini, Claude). Verfasst von Menschen, Teil der Rankion.ai-Knowledge-Base.

Kategorie:: API
Marke:: Rankion.ai
Format:: Knowledge-Base-Artikel
Stand:: 4. November 2026

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.
Buchungszeitpunkt je Endpoint. Manche Endpoints buchen mit der erfolgreichen Antwort, andere erst im Job oder nach dessen Abschluss. Scheitert ein Job, kommen die Credits nur dort zurück, wo der Endpoint eine Erstattung vorsieht.

Credit-Mechanik

Vor kostenpflichtigen Endpoints liegt eine von zwei Middlewares, und nur eine davon bucht.

credits:N → prüft nur das Guthaben. Liegt das Team unter N, antwortet die API mit 402 Insufficient Credits, und es startet kein Job. Gebucht wird später im Controller oder Job.
credits-auto:N → gleiche Prüfung, danach bucht sie N Credits, sobald die Antwort ein 2xx ist. 4xx und 5xx kosten nichts.
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): Bei credits-auto:N ist die Buchung erledigt, sobald die Antwort kommt. Bei credits:N bucht der Job selbst. Ein Worker-Crash erstattet nur, wo der Endpoint das vorsieht; POST /v1/google/gsc/properties/{p}/sync erstattet nicht.

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`	1/Artikel
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/api-docs.

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: 4. November 2026