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"}