Die Clevera REST API verwenden

Mit der REST API von Clevera können deine eigenen Skripte und Dienste das tun, was ein Agent über MCP erledigen kann: deine Bibliothek lesen, Videos und Artikel anfordern, Videos exportieren, an Dokumentationsseiten arbeiten und Jobs verfolgen. Dieser Artikel behandelt die Basis-URL, die Authentifizierung, den Anforderungsablauf für kostenpflichtige Arbeiten, Fehler und Ratenbegrenzungen.

Grundlagen#

Überprüfe ein Token mit GET /docs/me:

curl -H "Authorization: Bearer $CLEVERA_TOKEN" \
     -H "Accept: application/json" \
     https://app.clevera.ai/api/v1/docs/me

Die Antwort gibt an, wer das Token verwendet: der Name und das Ablaufdatum des Tokens, die Person und ihre aktuelle Rolle, der Arbeitsbereich, die betroffenen Seiten und die Berechtigungen, die aktuell funktionieren (die Berechtigungen des Tokens, gekürzt auf die aktuelle Rolle der Person). Rufe dies zuerst auf, wenn ein Aufruf verweigert wird.

Endpunkte#

Jeder Endpunkt benötigt die angezeigte Berechtigung. Der Aufruf ohne diese Berechtigung gibt 403 forbidden_ability zurück. Siehe Agenten-Berechtigungen.

Bibliothek und Materialien#

Videos und Artikel#

Jobs und Credits#

Dokumentationsseiten#

Mehr zu Agenten und Dokumentationsseiten: KI-Agenten mit deinen Dokumentationsseiten verbinden.

Kostenpflichtige Arbeit anfordern#

Arbeiten, die Credits kosten, erfordern immer zuerst ein Angebot und dann den Start:

1. Angebot einholen. POST /videos/quotes (oder /clips/quotes) mit dem, was du möchtest. Die Antwort enthält eine quote_id und den Credit-Bereich. Ein Angebot ist 15 Minuten gültig und kann einmal verwendet werden.
2. Optional: Testlauf. Sende den Start mit "dry_run": true, um zu erfahren, ob er starten würde, eine Genehmigung benötigt oder blockiert wird. Es wird nichts geschrieben.
3. Starten. POST /videos mit quote_id und einem Idempotency-Key-Header. Die Antwort ist 202 mit einem Job.
4. Verfolgen. GET /jobs/{job}/wait, bis sich der status des Jobs ändert, oder achte auf Webhooks.

curl -X POST https://app.clevera.ai/api/v1/videos/quotes \
  -H "Authorization: Bearer $CLEVERA_TOKEN" -H "Content-Type: application/json" \
  -d '{"type": "how_to", "recording_id": "<recording id>", "language": "en-US"}'

curl -X POST https://app.clevera.ai/api/v1/videos \
  -H "Authorization: Bearer $CLEVERA_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f6c1a2e-8d4b-4f7a-9c1e-2b5d7e9f0a13" \
  -d '{"quote_id": "<quote id>"}'

Job-Status:

Ob ein Start sofort ausgeführt wird oder auf eine Person wartet, hängt von den Ausgabenlimits des Tokens und seiner Einstellung Automatisch genehmigen unter ab. Siehe Ausgaben und Genehmigungen für Agenten steuern.

Wiederholungen und Idempotenz#

Sende bei jedem Erstellen und Starten einen Idempotency-Key-Header (eine neue UUID pro Aktion). Wenn die Netzwerkverbindung abbricht und du es mit demselben Schlüssel und Body erneut versuchst, erhältst du die erste Antwort zurück, anstatt ein zweites Video zu erstellen. Schlüssel werden 24 Stunden lang gespeichert.

Fehler#

Jeder Fehler hat das gleiche Format, mit einer Nachricht, die besagt, was als Nächstes zu tun ist:

{
  "error": {
    "code": "forbidden_ability",
    "message": "This token lacks the videos:create ability. Ask the workspace member who owns it for a token that has it.",
    "details": { "ability": "videos:create" }
  },
  "request_id": "req_example"
}

Gib die request_id an, wenn du den Support kontaktierst.

Jede Nachricht mit der Lösung: Agenten- und API-Fehler beheben.

Ratenbegrenzungen#

Eine 429-Antwort enthält einen Retry-After-Header und retry_after (Sekunden) im Body. Warte so lange, bevor du es erneut versuchst. Lesezugriffe, Angebote und Statusprüfungen kosten keine Credits.

Verwandte Themen#