API документація

Авторизація

Передайте токен у заголовку Authorization: Bearer sk_live_…. У URL його класти не потрібно — токен потрапить у логи серверів і історію браузера.

Токени випускаються в кабінеті після підтвердження email, максимум 5 активних на акаунт. Повне значення показується один раз — зберігайте його лише на сервері й відкликайте в разі витоку. У кожного токена одразу є доступ до метаданих і аналізу; аналіз на запиті списує коментарі з балансу (інакше 402 quota_exceeded).

Пісочниця — без токена

POST /api/v1/sandbox/metadata і POST /api/v1/sandbox/analyze віддають фікстури тієї самої форми, що бойові ендпоінти: без TikTok, без квоти і без токена. Ліміт за IP — 5 запитів на хвилину і 30 на годину.

# фікстура метаданих (без токена)
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"}'

# фікстура повного аналізу (одразу 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 — безкоштовно

Синхронна відповідь: автор, метрики, хештеги, музика, обкладинка, ключові слова опису. Коментарів тут немає. Ліміт — 10 запитів за 2 години на акаунт; відповіді кешуються 5 хвилин за URL, і потрапляння в кеш ("cached": true) ліміт не витрачає.

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 — за балансом коментарів

Асинхронний: повертає job_id зі статусом queued, результат забирається через GET /api/v1/analyze/{job_id}. Опитуйте раз на 1–2 секунди; статуси — queued, in_progress, complete, failed. Чуже завдання віддає 404. У comments відповіді вже вкладені в батьківський коментар як replies.

# створити завдання
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"}'

# відповідь: {"job_id": "b1e2...", "status": "queued"}

# забрати результат
curl https://api.example.com/api/v1/analyze/b1e2... \
  -H "Authorization: Bearer sk_live_..."

Повтори одного URL

Той самий URL не парситься двічі. Якщо завдання ще виконується, повернеться його job_id ("deduplicated": "in_flight"). Якщо результат отримано менше ніж 5 хвилин тому — повернеться готове завдання ("deduplicated": "recent_result"). В обох випадках квота не витрачається.

Idempotency-Key

Опційно. Якщо передасте заголовок Idempotency-Key з унікальним значенням, повтор із тим самим ключем протягом доби поверне той самий job_id замість нового завдання. Для звичайних запитів заголовок не потрібен.

Ліміти та квоти

Відповіді містять X-RateLimit-Limit, X-RateLimit-Remaining, X-Quota-Limit, X-Quota-Remaining, а при 429 — Retry-After в секундах. Поточний стан також віддає GET /api/v1/usage.

Коли баланс коментарів вичерпано, аналіз відповідає 402 quota_exceeded: купіть пакет на сторінці коментарів — він додається до поточного місяця.

Помилки

Тіло помилки: {"detail": "...", "code": "machine_code"}