Kernkonzepte

Das Vokabular, das über Skills, MCP-Operationen, Public-Data-APIs, Schemas und Pagination hinweg verwendet wird.

Einige Begriffe tauchen überall in UnifAPI auf. Lerne sie einmal, und der Rest der Dokumentation liest sich schneller.

Skill

Ein aufgabenspezifischer Workflow, den ein Agent mit UnifAPI MCP ausführen kann. Ein Skill startet von einer gewünschten Ausgabe aus, etwa einem KOL-Pricing-Briefing oder einer Creator-Shortlist, und lässt den Agenten dann Public-Data-Operationen entdecken und aufrufen, wenn er Belege benötigt.

Skills sind der empfohlene Ausgangspunkt für Agent-Nutzer. Die API-Referenz ist die Datenschicht dahinter.

Provider

Die öffentliche Plattform, aus der eine API Daten bereitstellt — zum Beispiel TikTok, Twitter/X, LinkedIn, YouTube, Reddit oder Instagram. Jeder Provider hat ein Pfadpräfix auf oberster Ebene.

https://api.unifapi.com/tiktok/...

Operation

Ein einzelner aufrufbarer Public-Data-Endpunkt innerhalb eines Providers — zum Beispiel GET /tiktok/videos/{id}. Jede Operation hat ihre eigene Seite in der API-Referenz, und MCP stellt die Operationsentdeckung über list_operations und get_operation bereit.

Kanonische Schemas

Jede Operation, die dieselbe Art von Ressource zurückgibt — ein Video, einen User, einen Comment — nutzt dasselbe kanonische Schema. So geben GET /tiktok/videos/{id} und GET /tiktok/users/{id}/videos beide Video-Objekte mit identischen Feldnamen und -typen zurück.

Die kanonischen Formen liegen in components.schemas der OpenAPI-Spezifikation und umfassen: Video, Author, Music, MusicDetail, Comment, User, Hashtag, LiveRoom.

Identifier

IDs sind opake Strings. Sie sehen aus wie lange Zahlen, sollten aber als Strings behandelt werden, um die Präzision zu erhalten (manche sind > 2^53).

Die TikTok-User-id (sec_uid) ist ein langer base64-Token, z. B. MS4wLjABAAAA....
TikTok-Video-, -Music- und -Hashtag-ids sind numerisch aussehende Strings. TikTok-User-Endpunkte akzeptieren das öffentliche Handle, die numerische User-id oder die sec_uid, wo unterstützt.

Löse einen Username mit /tiktok/users/resolve?username=jennmelon in eine stabile User-id auf. Löse eine Share-URL mit /tiktok/videos/resolve?url=... in ein Video auf.

Öffentlicher Response-Envelope

Erfolgreiche Antworten nutzen denselben Envelope auf oberster Ebene:

{
  "request_id": "req_...",
  "data": {
    /* resource or list payload */
  },
  "pagination": {
    "cursor": "1711494099000",
    "has_more": true
  },
  "billing": {
    "credits_charged": 10,
    "records_charged": 10,
    "balance_remaining": 90,
    "truncated_due_to_balance": false
  }
}

request_id — die UnifAPI-Request-id für Support und Tracing.
data — die fachliche Payload.
pagination — vorhanden, wenn eine List-Operation fortgesetzt werden kann.
billing — für den Aufruf abgerechnete credits und Records.

Pagination

pagination.has_more — true, wenn mindestens eine weitere Seite existiert.
pagination.cursor — opaker String, der als ?cursor= für die nächste Seite zurückgegeben wird. null, wenn has_more false ist.

Der Query-Parameter limit ist bei 50 gedeckelt.

Cursors sind bewusst opak: Manche Quellen nutzen Integer-Offsets, andere Timestamps, wieder andere Page-Tokens. UnifAPI verbirgt die Variation. Versuche nicht, pagination.cursor zu parsen.

Fehler-Envelope

Alle Fehler teilen sich einen einzigen verschachtelten Envelope:

{
  "error": {
    "type": "...",
    "message": "...",
    "request_id": "...",
    "issues": [
      /* validation only */
    ]
  }
}

error.type ist ein geschlossenes Vokabular (validation_error, not_found, unauthorized, ...). Siehe Fehler.

Workspace

Die Abrechnungs- und Zugriffsgrenze. OAuth-MCP-Sessions, API keys, Nutzung und Rechnungen leben alle auf Workspace-Ebene. Lade Teamkollegen über das Dashboard ein — sie teilen sich dieselben keys und denselben Nutzungszähler.

Public-Data-Grenze

UnifAPI bedient öffentliche Daten. OAuth autorisiert den UnifAPI-MCP-Zugriff und die Workspace-Credits; es autorisiert keine privaten Quellkonten. Wenn ein Workflow die privaten SaaS-Daten eines Nutzers benötigt, kombiniere UnifAPI mit einer Connector-Plattform, statt UnifAPI als diese OAuth-Integrationsschicht zu behandeln.

Kernkonzepte

Auf dieser Seite