Dokumentacja API

Autoryzacja

Przekaż token w nagłówku Authorization: Bearer sk_live_…. Nie umieszczaj go w URL — trafi wtedy do logów serwerów i historii przeglądarki.

Tokeny tworzysz w panelu po potwierdzeniu e-maila, maksymalnie 5 aktywnych na konto. Pełną wartość pokazujemy raz — trzymaj ją tylko na serwerze i odwołaj przy wycieku. Każdy token ma dostęp do metadanych i analizy; analiza pobiera komentarze z salda (inaczej 402 quota_exceeded).

Piaskownica — bez tokena

POST /api/v1/sandbox/metadata i POST /api/v1/sandbox/analyze zwracają dane testowe w tej samej formie co produkcyjne punkty końcowe: bez TikToka, bez limitu i bez tokena. Limit na IP to 5 zapytań na minutę i 30 na godzinę.

# fixture metadanych (bez tokena)
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 pełnej analizy (od razu 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 — za darmo

Odpowiedź synchroniczna: autor, statystyki, hashtagi, dźwięk, okładka i słowa kluczowe opisu. Komentarzy tu nie ma. Limit to 10 zapytań na 2 godziny na konto; odpowiedzi są buforowane przez 5 minut po URL, a trafienie w cache ("cached": true) nie zużywa limitu.

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 — z salda komentarzy

Asynchronicznie: zwraca job_id ze statusem queued, a wynik pobierasz przez GET /api/v1/analyze/{job_id}. Odpytuj co 1–2 sekundy; statusy to queued, in_progress, complete i failed. Cudze zadanie zwraca 404. W comments odpowiedzi są już zagnieżdżone w komentarzu nadrzędnym jako replies.

# utwórz zadanie
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"}'

# odpowiedź: {"job_id": "b1e2...", "status": "queued"}

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

Powtórzenie tego samego URL

Ten sam URL nie jest parsowany dwa razy. Jeśli zadanie wciąż trwa, dostaniesz jego job_id ("deduplicated": "in_flight"). Jeśli wynik pojawił się mniej niż 5 minut temu, wrócimy z gotowym zadaniem ("deduplicated": "recent_result"). W obu przypadkach limit nie jest zużywany.

Idempotency-Key

Opcjonalnie. Jeśli wyślesz nagłówek Idempotency-Key z unikalną wartością, powtórka z tym samym kluczem w ciągu doby zwróci to samo job_id zamiast nowego zadania. Zwykłe zapytania nie potrzebują tego nagłówka.

Limity i przydziały

Odpowiedzi zawierają X-RateLimit-Limit, X-RateLimit-Remaining, X-Quota-Limit i X-Quota-Remaining, a przy 429 dodatkowo Retry-After w sekundach. Bieżący stan zwraca też GET /api/v1/usage.

Gdy saldo komentarzy się skończy, analiza odpowiada 402 quota_exceeded: kup pakiet na stronie komentarzy, dopiszemy go do bieżącego miesiąca.

Błędy

Treść błędu: {"detail": "...", "code": "machine_code"}