API-Dokumentation

Autorisierung

Senden Sie den Token im Header Authorization: Bearer sk_live_…. Nicht in die URL schreiben — er landet sonst in Serverlogs und im Browserverlauf.

Tokens werden im Arbeitsbereich nach Bestätigung der E-Mail erstellt, maximal 5 aktive pro Konto. Der vollständige Wert wird einmal angezeigt — bewahren Sie ihn nur auf dem Server auf und widerrufen Sie ihn bei einem Leck. Jeder Token erreicht Metadaten und Auswertung; eine Auswertung bucht Kommentare vom Guthaben ab (sonst 402 quota_exceeded).

Sandbox — ohne Token

POST /api/v1/sandbox/metadata und POST /api/v1/sandbox/analyze liefern Fixtures in derselben Form wie die produktiven Endpunkte: ohne TikTok, ohne Kontingent, ohne Token. IP-Limit: 5 Anfragen pro Minute und 30 pro Stunde.

# Metadaten-Fixture (ohne Token)
curl -X POST https://api.example.com/api/v1/sandbox/metadata \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.tiktok.com/@user/video/7300000000000000000"}'

# Fixture der vollständigen Auswertung (sofort status: complete)
curl -X POST https://api.example.com/api/v1/sandbox/analyze \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.tiktok.com/@user/video/7300000000000000000"}'

POST /api/v1/metadata — kostenlos

Synchrone Antwort: Autor, Kennzahlen, Hashtags, Sound, Cover und Schlüsselwörter der Beschreibung. Kommentare sind hier nicht enthalten. Limit: 10 Anfragen pro 2 Stunden und Konto; Antworten werden 5 Minuten pro URL zwischengespeichert, und ein Cache-Treffer ("cached": true) verbraucht das Limit nicht.

curl -X POST https://api.example.com/api/v1/metadata \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.tiktok.com/@user/video/7300000000000000000"}'

POST /api/v1/analyze — vom Kommentarguthaben

Asynchron: liefert eine job_id mit Status queued; das Ergebnis holen Sie über GET /api/v1/analyze/{job_id}. Fragen Sie alle 1–2 Sekunden ab; Status sind queued, in_progress, complete und failed. Ein fremder Job liefert 404. In comments stecken Antworten bereits als replies im übergeordneten Kommentar.

# Job anlegen
curl -X POST https://api.example.com/api/v1/analyze \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.tiktok.com/@user/video/7300000000000000000"}'

# Antwort: {"job_id": "b1e2...", "status": "queued"}

# Ergebnis abholen
curl https://api.example.com/api/v1/analyze/b1e2... \
  -H "Authorization: Bearer sk_live_..."

Dieselbe URL erneut

Dieselbe URL wird nie zweimal geparst. Läuft der Job noch, erhalten Sie dessen job_id zurück ("deduplicated": "in_flight"). Liegt das Ergebnis weniger als 5 Minuten zurück, kommt der fertige Job ("deduplicated": "recent_result"). In beiden Fällen wird kein Kontingent verbraucht.

Idempotency-Key

Optional. Senden Sie den Header Idempotency-Key mit einem eindeutigen Wert, liefert eine Wiederholung mit demselben Schlüssel innerhalb von 24 Stunden dieselbe job_id statt eines neuen Jobs. Für normale Anfragen ist der Header nicht nötig.

Limits und Kontingente

Antworten enthalten X-RateLimit-Limit, X-RateLimit-Remaining, X-Quota-Limit und X-Quota-Remaining, bei 429 zusätzlich Retry-After in Sekunden. Den aktuellen Stand liefert auch GET /api/v1/usage.

Ist das Kommentarguthaben aufgebraucht, antwortet die Auswertung mit 402 quota_exceeded: Kaufen Sie ein Paket auf der Kommentarseite, es wird dem laufenden Monat gutgeschrieben.

Fehler

Fehlerkörper: {"detail": "...", "code": "machine_code"}