Документация для разработчиков

Документация API TokCaption

REST API для расшифровки публичных видео TikTok, ИИ-анализа хуков и переписывания сценариев, а также экспорта расшифровок в больших объёмах. Аутентификация по API-ключу, отправка URL и опрос результата. API доступен на тарифе Pro.

REST API · v2.1.0

TokCaption API

Расшифровывайте публичные видео TikTok, запускайте ИИ-анализ хуков и экспортируйте данные в больших объёмах — всё через удобный JSON REST API. Аутентификация по API-ключу, старт в два запроса. Предпочитаете ИИ-ассистентов? Те же инструменты доступны как MCP-сервер для Claude и ChatGPT.

Базовый URL

https://www.tokcaption.com/api/v1

Авторизация

X-API-Key

Эндпоинты

27 в 6 группах

Аутентификация

Создайте ключ API в разделе Настройки → Ключи API (тариф Pro). Отправляйте его в каждом запросе в заголовке X-API-Key. Панель управления и мобильные клиенты могут вместо этого отправлять JWT Supabase в виде Authorization: Bearer <jwt>. Храните ключи на сервере и никогда не включайте их в браузерный bundle.

curl "https://www.tokcaption.com/api/v1/billing/subscription" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Быстрый старт

Отправьте URL, затем опрашивайте задание до завершения. Одна ссылка часто обрабатывается сразу — проверьте статус в ответе перед опросом.

Шаг 1 — Отправка

Отправьте POST /api/v1/jobs со своими URL. Сохраните возвращённое значение job_id.

Шаг 2 — Опрос

Отправляйте GET /api/v1/jobs/{jobId} каждые 1–2 с, пока статус не станет конечным, затем считайте items[].transcript_text.

Нужна только одна ссылка, и не хотите опрашивать сервер? Используйте GET /api/v1/quick для синхронного результата.

Ошибки и лимиты запросов

Каждая ошибка возвращает один и тот же JSON-объект. Ветвите логику по code, а не по HTTP-статусу или тексту сообщения. При 429 учитывайте заголовок Retry-After.

Формат ошибок

{
  "success": false,
  "error": "Free plan allows 5 transcripts per day.",
  "code": "QUOTA_EXCEEDED",
  "message": "Free plan allows 5 transcripts per day.",
  "error_info": {
    "code": "QUOTA_EXCEEDED",
    "message": "Free plan allows 5 transcripts per day.",
    "details": {
      "limit_type": "daily",
      "daily_limit": 5,
      "retry_after_seconds": 43200
    }
  },
  "details": {
    "limit_type": "daily",
    "daily_limit": 5,
    "retry_after_seconds": 43200
  }
}

Все коды ошибок

Код	HTTP	Значение
AUTH_REQUIRED	401	Отсутствуют или неверны учётные данные. Отправьте корректный заголовок X-API-Key или Authorization: Bearer <jwt>.
VALIDATION_ERROR	400	Неверное тело запроса, параметры запроса или путь. Сообщение и details подскажут, что исправить.
PLAN_REQUIRED	403	Эта функция или опция требует тариф Pro. Перейдите на обновление, чтобы открыть доступ.
NOT_FOUND	404	Задание, расшифровка или ресурс не найдены или не принадлежат вам.
QUOTA_EXCEEDED	429	Достигнут лимит расшифровок, агентов, загрузок или переводов. Сбрасывается ежедневно (бесплатный тариф) или в каждом расчётном цикле (Pro). Подробнее: details.reset_at.
RATE_LIMIT_EXCEEDED	429	Слишком много запросов на отправку, опрос или работу агентов за короткий промежуток времени. Соблюдайте заголовок Retry-After / details.retry_after_seconds.
DUPLICATE_REQUEST	409	idempotency_key уже использовался. Исходный запрос уже выполнен.
TRANSLATION_LIMIT_EXCEEDED	429	Достигнута месячная квота переводов. Сбрасывается в начале вашего платёжного цикла.
UPSTREAM_TEMPORARY_ERROR	503	TikTok временно заблокировал или ограничил запрос. Повторите попытку с задержкой.
SEGMENTS_UNAVAILABLE	400	Для этого формата экспорта (srt/vtt) нужны сегменты с таймкодами, но в расшифровке их нет.
INTERNAL_ERROR	500	Непредвиденная ошибка сервера. Повторите попытку, а если проблема сохраняется, свяжитесь с поддержкой.

Транскрибация

Отправляйте публичные URL TikTok на расшифровку и отслеживайте ход задач.

POST/api/v1/jobs

Отправить задание на расшифровку

Лимит: submit

Отправьте от 1 до N публичных URL TikTok на расшифровку. Размер пакета ограничен вашим тарифом; для одного URL готовый результат может вернуться сразу в ответе.

Авторизация: Ключ API или JWTЗапрос: application/jsonОтвет: application/json

curl -X POST "https://www.tokcaption.com/api/v1/jobs" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.tiktok.com/@creator/video/1234567890","https://www.tiktok.com/@creator/video/0987654321"],"output_language":"en","also_translate_to":["es"],"allow_asr_fallback":false,"include_download_assets":false,"idempotency_key":"client-req-001"}'

Один URL может вернуть HTTP 200 с конечным ответом completed или failed, если обработка завершается сразу.
Пакетные запросы возвращают HTTP 202 с job_id, общим статусом и статусами каждого элемента в items.
Проверьте массив items для статуса каждого видео: queued, processing, completed или failed.
Если указать include_download_assets: true на бесплатном тарифе, вернётся PLAN_REQUIRED (403).

Поля тела запроса

`urls`обязательно string[]	Ссылки на видео TikTok. Лимит пакетной обработки на бесплатном тарифе — 5.
`output_language` string	Целевой язык расшифровки (код ISO). По умолчанию en.
`also_translate_to` string[]	Дополнительные языки, на которые нужно перевести расшифровку.
`allow_asr_fallback` boolean	Расшифровывать аудио, если дорожка субтитров отсутствует. По умолчанию — false.
`include_download_assets` boolean	Сохранять видео и обложки для скачивания. Только для Pro.
`idempotency_key` string	Ключ дедупликации; повторное использование возвращает исходную задачу.

Ответ при успехе · HTTP 202

{
  "job_id": "b86f89f2-34f6-4b76-88f6-03c13c51b7a6",
  "status": "queued",
  "total_items": 2,
  "items": [
    {
      "id": "tx_1",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "item_index": 0,
      "input_url": "https://www.tiktok.com/@creator/video/1234567890",
      "status": "queued"
    }
  ]
}

Мгновенный единичный успех

HTTP 200

{
  "job_id": "51f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "status": "completed",
  "total_items": 1,
  "completed": 1,
  "failed": 0,
  "items": [
    {
      "id": "tx_single_1",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "item_index": 0,
      "status": "completed",
      "output_language": "en",
      "source_language": "en",
      "selected_track_type": "creator",
      "transcript_text": "Whenever I'm asked to teach a beginner how to cook...",
      "metadata": {
        "author_username": "foodnetwork",
        "duration_seconds": 29
      },
      "completed_at": "2026-03-14T08:33:14.000Z"
    }
  ]
}

Единичная ошибка (нет субтитров)

HTTP 200

{
  "job_id": "8a0d6d7a-78f0-4ab0-8a8c-72f8f5184de8",
  "status": "failed",
  "total_items": 1,
  "completed": 0,
  "failed": 1,
  "items": [
    {
      "id": "tx_single_2",
      "transcript_id": "d40b2545-7c62-4bbb-a7e3-020c663f18a0",
      "item_index": 0,
      "status": "failed",
      "error_code": "NO_CAPTIONS_AVAILABLE",
      "error_message": "Captions are not available for this TikTok video."
    }
  ]
}

Ошибки

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429DUPLICATE_REQUEST409UPSTREAM_TEMPORARY_ERROR503

GET/api/v1/jobs

Список заданий

Список ваших заданий на транскрибацию, сначала новые, с пагинацией по курсору.

Авторизация: Ключ API или JWTЗапрос: noneОтвет: application/json

curl -X GET "https://www.tokcaption.com/api/v1/jobs?cursor=2026-06-23T10%3A00%3A00.000Z" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Параметры

`cursor` string (ISO date) · query	Передайте предыдущий next_cursor, чтобы вернуться к более ранним страницам.
`limit` integer · query	Размер страницы, 1–50. По умолчанию 20.
`status` string · query	Фильтр по статусу задания (например, completed, processing, failed).

Ответ при успехе

{
  "jobs": [
    {
      "job_id": "b86f89f2-34f6-4b76-88f6-03c13c51b7a6",
      "created_at": "2026-06-23T10:02:11.000Z",
      "updated_at": "2026-06-23T10:02:48.000Z",
      "origin": "api",
      "status": "completed",
      "collection_name": null
    }
  ],
  "next_cursor": "2026-06-23T10:02:11.000Z"
}

Ошибки

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/jobs/{jobId}

Опросить статус задания

Лимит: poll

Опрашивайте задание, пока оно не достигнет конечного состояния. Возвращает сводные счётчики и подробные данные по каждому элементу.

Авторизация: Ключ API или JWTЗапрос: noneОтвет: application/json

curl -X GET "https://www.tokcaption.com/api/v1/jobs/b86f89f2-34f6-4b76-88f6-03c13c51b7a6" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Конечными состояниями задания являются completed, partial или failed; отдельные элементы внутри задания могут отличаться.
Завершённые элементы содержат transcript_text, segments, translations, metadata и assets.
Опрашивайте с разумным интервалом (каждые 1–2 с). При HTTP 429 учитывайте retry_after_seconds.

Параметры

jobIdобязательно

string · path

ID задания, возвращённый POST /api/v1/jobs.

Ответ при успехе

{
  "job_id": "b86f89f2-34f6-4b76-88f6-03c13c51b7a6",
  "status": "processing",
  "total_items": 2,
  "completed": 1,
  "failed": 0,
  "items": [
    {
      "id": "tx_1",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "item_index": 0,
      "status": "completed",
      "output_language": "en",
      "transcript_text": "Whenever I'm asked to teach a beginner...",
      "completed_at": "2026-03-14T08:33:14.000Z"
    },
    {
      "id": "tx_2",
      "transcript_id": "2448b6b8-7e07-46ef-96be-1f339abdb71f",
      "item_index": 1,
      "status": "processing"
    }
  ]
}

Ошибки

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404RATE_LIMIT_EXCEEDED429INTERNAL_ERROR500

POST/api/v1/jobs/{jobId}/cancel

Отмена задачи

Отменяет элементы задачи в очереди или в обработке. Отменённые элементы возвращают свою квоту.

Авторизация: Ключ API или JWTЗапрос: noneОтвет: application/json

curl -X POST "https://www.tokcaption.com/api/v1/jobs/b86f89f2-34f6-4b76-88f6-03c13c51b7a6/cancel" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Параметры

jobIdобязательно

string · path

ID задания для отмены.

Ответ при успехе

{
  "cancelled_count": 3
}

Ошибки

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

GET/api/v1/quick

Быстрая расшифровка (один URL)

Лимит: submit

Отправьте одну ссылку и дождитесь (до ~55 с) конечного результата — синхронный вариант работы через задания.

Авторизация: Ключ API или JWTЗапрос: noneОтвет: application/json

curl -X GET "https://www.tokcaption.com/api/v1/quick?url=https%3A%2F%2Fwww.tiktok.com%2F%40creator%2Fvideo%2F1234567890" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Возвращает HTTP 200 после достижения конечного состояния (completed/failed) или HTTP 202, если обработка ещё идёт по истечении времени ожидания — тогда опрашивайте /api/v1/jobs/{jobId}.

Параметры

urlобязательно

string · query

Один URL видео TikTok.

Ответ при успехе

{
  "job_id": "51f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
  "status": "completed"
}

Ошибки

AUTH_REQUIRED401VALIDATION_ERROR400QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429UPSTREAM_TEMPORARY_ERROR503

POST/api/v1/import/collection

Массовый импорт

ProЛимит: submit

Отправьте список URL или необработанный текст со ссылками. На бесплатном тарифе доступна 1 ссылка; массовая обработка требует Pro.

Авторизация: Ключ API или JWTЗапрос: application/jsonОтвет: application/json

curl -X POST "https://www.tokcaption.com/api/v1/import/collection" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.tiktok.com/@creator/video/1234567890","https://www.tiktok.com/@creator/video/0987654321"],"output_language":"en"}'

Поля тела запроса

`urls` string[]	Явный список URL. Укажите его или текст.
`text` string	Произвольный текст; ссылки TikTok извлекаются автоматически.
`output_language` string	Целевой язык расшифровки. По умолчанию en.
`allow_asr_fallback` boolean	Расшифровывать аудио, если субтитров нет. По умолчанию — false.

Ответ при успехе · HTTP 202

{
  "total_urls_found": 5,
  "valid_urls": 4,
  "jobs_created": 1,
  "job_ids": [
    "b86f89f2-34f6-4b76-88f6-03c13c51b7a6"
  ],
  "invalid_urls": [
    "https://example.com/not-a-video"
  ]
}

Ошибки

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403RATE_LIMIT_EXCEEDED429UPSTREAM_TEMPORARY_ERROR503

Расшифровки

Читайте, ищите, экспортируйте и скачивайте готовые расшифровки и их файлы.

GET/api/v1/history

Список и поиск расшифровок

Лимит: poll

Постраничная история расшифровок с поиском и фильтрами по статусу, папке и сортировке.

Авторизация: Ключ API или JWTЗапрос: noneОтвет: application/json

curl -X GET "https://www.tokcaption.com/api/v1/history?page=1" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Параметры

`page` integer · query	Номер страницы, начиная с 1. По умолчанию 1.
`limit` integer · query	Размер страницы, 1–100. По умолчанию 15.
`search` string · query	Полнотекстовый поиск по тексту расшифровки и исходному URL.
`status` string · query	completed \| failed \| all. По умолчанию — all.
`order_by` string · query	created_at_desc \| created_at_asc \| completed_at_desc \| completed_at_asc.

Ответ при успехе

{
  "transcripts": [
    {
      "id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "input_url": "https://www.tiktok.com/@creator/video/1234567890",
      "tiktok_video_id": "1234567890",
      "status": "completed",
      "output_language": "en",
      "source_language": "en",
      "transcript_text": "Whenever I'm asked to teach a beginner...",
      "created_at": "2026-06-23T10:02:11.000Z",
      "completed_at": "2026-06-23T10:02:48.000Z",
      "folder": null
    }
  ],
  "page": 1,
  "limit": 15,
  "has_more": true,
  "total_count": 42,
  "total_pages": 3
}

Ошибки

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/transcripts/{id}

Получить расшифровку

Лимит: poll

Получить одну расшифровку по ID с полным текстом, сегментами, переводами, метаданными и ресурсами.

Авторизация: Ключ API или JWTЗапрос: noneОтвет: application/json

curl -X GET "https://www.tokcaption.com/api/v1/transcripts/85f4dd35-3bc5-413f-81a6-63e0b61722d2" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Параметры

idобязательно

string · path

ID расшифровки.

Ответ при успехе

{
  "id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
  "status": "completed",
  "input_url": "https://www.tiktok.com/@creator/video/1234567890",
  "output_language": "en",
  "source_language": "en",
  "selected_track_type": "creator",
  "transcript_text": "Whenever I'm asked to teach a beginner how to cook...",
  "segments": [
    {
      "start": 0,
      "end": 2.4,
      "text": "Whenever I'm asked to teach"
    }
  ],
  "translations": {
    "es": {
      "full_text": "Cada vez que me piden..."
    }
  },
  "metadata": {
    "author_username": "foodnetwork",
    "duration_seconds": 29
  },
  "completed_at": "2026-06-23T10:02:48.000Z"
}

Ошибки

AUTH_REQUIRED401NOT_FOUND404VALIDATION_ERROR400

GET/api/v1/transcripts/{id}/export

Экспорт расшифровки

Скачайте одну расшифровку в формате txt, srt, vtt, csv, json или pdf. Для json и pdf нужен тариф Pro.

Авторизация: Ключ API или JWTЗапрос: noneОтвет: file download

curl -X GET "https://www.tokcaption.com/api/v1/transcripts/85f4dd35-3bc5-413f-81a6-63e0b61722d2/export?format=srt" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Возвращает файл с Content-Disposition: attachment. При format=json возвращает { id, text, segments, metadata }.
Для srt/vtt нужны сегменты с таймкодами, иначе вернётся SEGMENTS_UNAVAILABLE.

Параметры

`id`обязательно string · path	ID расшифровки.
`format` string · query	txt \| srt \| vtt \| csv \| json \| pdf. По умолчанию — txt.
`language` string · query	Экспорт перевода вместо исходного языка.

Ответ при успехе

{
  "note": "Binary/text download. Example shows the format=json body.",
  "id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
  "text": "Whenever I'm asked to teach a beginner how to cook...",
  "segments": [
    {
      "start": 0,
      "end": 2.4,
      "text": "Whenever I'm asked to teach"
    }
  ],
  "metadata": {
    "author_username": "foodnetwork"
  }
}

Ошибки

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403NOT_FOUND404SEGMENTS_UNAVAILABLE400

POST/api/v1/transcripts/export-batch

Пакетный экспорт (ZIP)

Экспорт нескольких расшифровок сразу в ZIP — по списку ID или по фильтрам. Для json/pdf нужен Pro.

Авторизация: Ключ API или JWTЗапрос: application/jsonОтвет: application/zip

curl -X POST "https://www.tokcaption.com/api/v1/transcripts/export-batch" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format":"srt","filters":{"status":"completed","orderBy":"created_at_desc"}}'

Поля тела запроса

`format` string	txt \| srt \| vtt \| csv \| json \| pdf. По умолчанию — txt.
`ids` string[]	Явные ID расшифровок. Опустите, чтобы использовать фильтры.
`filters` object	{ search?, status?, folderId?, orderBy?, view? }. Экспортируются только завершённые расшифровки.

Ответ при успехе

{
  "note": "Returns a ZIP attachment named tokcaption-srt-export-<date>.zip."
}

Ошибки

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403NOT_FOUND404SEGMENTS_UNAVAILABLE400INTERNAL_ERROR500

DELETE/api/v1/transcripts/{id}

Удалить расшифровку

Безвозвратно удалить расшифровку, её сохранённые файлы и ссылки на папки.

Авторизация: Ключ API или JWTЗапрос: noneОтвет: application/json

curl -X DELETE "https://www.tokcaption.com/api/v1/transcripts/85f4dd35-3bc5-413f-81a6-63e0b61722d2" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Параметры

idобязательно

string · path

ID расшифровки.

Ответ при успехе

{
  "deleted": true
}

Ошибки

AUTH_REQUIRED401NOT_FOUND404INTERNAL_ERROR500

GET/api/v1/transcripts/stats

Статистика расшифровки

Лимит: poll

Сводные счётчики по вашему аккаунту.

Авторизация: Ключ API или JWTЗапрос: noneОтвет: application/json

curl -X GET "https://www.tokcaption.com/api/v1/transcripts/stats" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Ответ при успехе

{
  "total": 944,
  "completed": 702,
  "failed": 212,
  "folders": 5
}

Ошибки

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/transcripts/{id}/download/video

Скачать исходное видео

Pro

Скачайте исходное видео TikTok в формате MP4. Только для Pro, учитывается в месячной квоте загрузок.

Авторизация: Ключ API или JWTЗапрос: noneОтвет: video/mp4

curl -X GET "https://www.tokcaption.com/api/v1/transcripts/85f4dd35-3bc5-413f-81a6-63e0b61722d2/download/video" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Возвращает video/mp4 как вложение. Квота списывается только при успешной передаче потока.

Параметры

idобязательно

string · path

ID расшифровки.

Ответ при успехе

{
  "note": "Binary video/mp4 attachment."
}

Ошибки

AUTH_REQUIRED401PLAN_REQUIRED403QUOTA_EXCEEDED429NOT_FOUND404VALIDATION_ERROR400

ИИ-агенты

Запускайте анализ хуков, переписывание сценариев и оценку виральности для расшифровки. (Pro)

POST/api/v1/agents/{agentType}

Запустить ИИ-агента

ProЛимит: agent

Поставить в очередь ИИ-анализ завершённой расшифровки. agentType — один из: hooks, script_rewrite, virality_explain, hook_score.

Авторизация: Ключ API или JWTЗапрос: application/jsonОтвет: application/json

curl -X POST "https://www.tokcaption.com/api/v1/agents/hooks" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transcript_id":"85f4dd35-3bc5-413f-81a6-63e0b61722d2","input":{}}'

Поля тела запроса

`transcript_id`обязательно string	Готовая расшифровка для анализа.
`input` object	Необязательные параметры, специфичные для агента.

Параметры

agentTypeобязательно

string · path

hooks | script_rewrite | virality_explain | hook_score.

Ответ при успехе · HTTP 202

{
  "run_id": "a1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "status": "queued"
}

Ошибки

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429NOT_FOUND404RATE_LIMIT_EXCEEDED429

GET/api/v1/agents/runs

Список запусков агентов

Список ваших запусков агентов, сначала новые, с пагинацией по курсору.

Авторизация: Ключ API или JWTЗапрос: noneОтвет: application/json

curl -X GET "https://www.tokcaption.com/api/v1/agents/runs?cursor=2026-06-23T10%3A00%3A00.000Z" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Параметры

`cursor` string (ISO date) · query	Передайте next_cursor, чтобы вернуться назад.
`limit` integer · query	Размер страницы, 1–50. По умолчанию 20.

Ответ при успехе

{
  "runs": [
    {
      "id": "a1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
      "status": "completed",
      "agent_type": "hooks",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "created_at": "2026-06-23T10:05:00.000Z"
    }
  ],
  "next_cursor": null
}

Ошибки

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/agents/runs/{runId}

Получить запуск агента

Получить один запуск агента, включая структурированный результат после завершения.

Авторизация: Ключ API или JWTЗапрос: noneОтвет: application/json

curl -X GET "https://www.tokcaption.com/api/v1/agents/runs/a1f0ab70-7b6f-4f3b-9116-4135a6d8f53d" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Параметры

runIdобязательно

string · path

ID запуска агента.

Ответ при успехе

{
  "id": "a1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "status": "completed",
  "agent_type": "hooks",
  "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
  "output": {
    "hooks": [
      "The first 3 seconds promise a payoff..."
    ]
  },
  "output_text": "The first 3 seconds promise a payoff...",
  "model": "claude-...",
  "completed_at": "2026-06-23T10:05:09.000Z"
}

Ошибки

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404

Извлечь и перевести

Низкоуровневые примитивы: получение метаданных, перевод текста и классификация вставленных данных.

POST/api/v1/extract/metadata

Собрать метаданные

Определить метаданные по URL TikTok и лучшую доступную дорожку субтитров без создания задания.

Авторизация: Ключ API или JWTЗапрос: application/jsonОтвет: application/json

curl -X POST "https://www.tokcaption.com/api/v1/extract/metadata" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.tiktok.com/@creator/video/1234567890"}'

Поля тела запроса

`url`обязательно string	URL видео TikTok.
`output_language` string	Предпочтительный язык субтитров. По умолчанию en.

Ответ при успехе

{
  "normalized_url": "https://www.tiktok.com/@creator/video/1234567890",
  "source_language": "en",
  "selected_track_type": "creator",
  "subtitle_format": "webvtt",
  "metadata": {
    "author_username": "creator",
    "duration_seconds": 29
  }
}

Ошибки

AUTH_REQUIRED401VALIDATION_ERROR400UPSTREAM_TEMPORARY_ERROR503

POST/api/v1/extract/translate

Перевести текст

Переведите текст расшифровки и/или сегменты с таймкодами на один или несколько языков.

Авторизация: Ключ API или JWTЗапрос: application/jsonОтвет: application/json

curl -X POST "https://www.tokcaption.com/api/v1/extract/translate" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"full_text":"Whenever I'm asked to teach a beginner how to cook...","output_language":"es"}'

Поля тела запроса

`full_text` string	Текст для перевода. Укажите его и/или segments.
`segments` TranscriptSegment[]	Сегменты с таймкодами для перевода с сохранением тайминга.
`output_language` string	Основной целевой язык. По умолчанию en.
`additional_languages` string[]	Дополнительные целевые языки.

Ответ при успехе

{
  "fullText": "Cada vez que me piden que enseñe a un principiante a cocinar...",
  "segments": [],
  "translations": {
    "es": {
      "full_text": "Cada vez que me piden..."
    }
  }
}

Ошибки

AUTH_REQUIRED401VALIDATION_ERROR400TRANSLATION_LIMIT_EXCEEDED429INTERNAL_ERROR500

POST/api/v1/workspace/resolve

Обработать вставленный текст

Определяет, является ли вставленный текст, @-упоминания или URL списком URL видео, превью подборки или превью профиля.

Авторизация: Ключ API или JWTЗапрос: application/jsonОтвет: application/json

curl -X POST "https://www.tokcaption.com/api/v1/workspace/resolve" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"@foodnetwork"}'

Поля тела запроса

`text` string	Необработанный вставленный текст. Укажите его или urls.
`urls` string[]	Явный список URL.

Ответ при успехе

{
  "kind": "profile",
  "profile": {
    "username": "foodnetwork",
    "video_count": 1200
  }
}

Ошибки

AUTH_REQUIRED401VALIDATION_ERROR400UPSTREAM_TEMPORARY_ERROR503

Папки

Раскладывайте расшифровки по папкам.

GET/api/v1/folders

Список папок

Список ваших папок с количеством элементов.

Авторизация: Ключ API или JWTЗапрос: noneОтвет: application/json

curl -X GET "https://www.tokcaption.com/api/v1/folders" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Ответ при успехе

{
  "folders": [
    {
      "id": "f1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
      "name": "Cooking hooks",
      "created_at": "2026-06-23T10:00:00.000Z",
      "item_count": 12
    }
  ]
}

Ошибки

AUTH_REQUIRED401INTERNAL_ERROR500

POST/api/v1/folders

Создать папку

Создайте папку, чтобы группировать расшифровки.

Авторизация: Ключ API или JWTЗапрос: application/jsonОтвет: application/json

curl -X POST "https://www.tokcaption.com/api/v1/folders" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Cooking hooks"}'

Поля тела запроса

nameобязательно

string

Название папки.

Ответ при успехе · HTTP 201

{
  "id": "f1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "name": "Cooking hooks",
  "created_at": "2026-06-23T10:00:00.000Z"
}

Ошибки

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

POST/api/v1/folders/{folderId}/items

Добавить расшифровку в папку

Добавить расшифровку в папку (идемпотентно).

Авторизация: Ключ API или JWTЗапрос: application/jsonОтвет: application/json

curl -X POST "https://www.tokcaption.com/api/v1/folders/f1f0ab70-7b6f-4f3b-9116-4135a6d8f53d/items" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transcript_id":"85f4dd35-3bc5-413f-81a6-63e0b61722d2"}'

Поля тела запроса

transcript_idобязательно

string

Расшифровка для добавления.

Параметры

folderIdобязательно

string · path

ID целевой папки.

Ответ при успехе · HTTP 201

{
  "added": true
}

Ошибки

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404INTERNAL_ERROR500

Аккаунт, ключи и оплата

Управляйте ключами API, просматривайте тарифы и квоты, отправляйте отзывы.

POST/api/v1/api-keys

Создать ключ API

Pro

Создайте действующий ключ API. Полный ключ показывается один раз — храните его в надёжном месте. Только для Pro.

Авторизация: Ключ API или JWTЗапрос: application/jsonОтвет: application/json

curl -X POST "https://www.tokcaption.com/api/v1/api-keys" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production server"}'

Поля тела запроса

nameобязательно

string

Метка для идентификации ключа.

Ответ при успехе · HTTP 201

{
  "id": "k1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "name": "Production server",
  "key_prefix": "tok_live_a1b2c3",
  "key": "tok_live_a1b2c3_d4e5f6g7h8i9j0k1l2m3n4o5",
  "created_at": "2026-06-23T10:00:00.000Z",
  "warning": "Save this key now — it will not be shown again."
}

Ошибки

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403INTERNAL_ERROR500

GET/api/v1/api-keys

Список ключей API

Pro

Список активных ключей по префиксу (секрет никогда не возвращается). Только для Pro.

Авторизация: Ключ API или JWTЗапрос: noneОтвет: application/json

curl -X GET "https://www.tokcaption.com/api/v1/api-keys" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Ответ при успехе

{
  "keys": [
    {
      "id": "k1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
      "name": "Production server",
      "key_prefix": "tok_live_a1b2c3",
      "last_used_at": "2026-06-23T10:30:00.000Z",
      "created_at": "2026-06-23T10:00:00.000Z",
      "revoked_at": null
    }
  ]
}

Ошибки

AUTH_REQUIRED401PLAN_REQUIRED403INTERNAL_ERROR500

GET/api/v1/plans

Список тарифов

Публичный список активных тарифов и их лимитов. Авторизация не требуется.

Авторизация: Публичный (без авторизации)Запрос: noneОтвет: application/json

curl -X GET "https://www.tokcaption.com/api/v1/plans"

Ответ при успехе

{
  "plans": [
    {
      "id": "free",
      "price_cents": 0,
      "billing_interval": "none",
      "free_daily_limit": 5,
      "agents_enabled": false,
      "downloads_enabled": false,
      "features": [
        "5 transcripts per day",
        "TXT & SRT export"
      ]
    },
    {
      "id": "pro_monthly",
      "price_cents": 900,
      "billing_interval": "month",
      "agents_enabled": true,
      "downloads_enabled": true,
      "features": [
        "Unlimited transcripts",
        "30 AI agent runs / month",
        "API access"
      ]
    }
  ]
}

Ошибки

INTERNAL_ERROR500

GET/api/v1/billing/subscription

Подписка и квота

Ваш текущий тариф, статус подписки и актуальное использование и квоты по расшифровкам, агентам, загрузкам и переводам.

Авторизация: Ключ API или JWTЗапрос: noneОтвет: application/json

curl -X GET "https://www.tokcaption.com/api/v1/billing/subscription" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

Ответ при успехе

{
  "plan": {
    "id": "free",
    "price_cents": 0,
    "billing_interval": "none"
  },
  "subscription_status": null,
  "quota": {
    "transcripts": {
      "window": "daily",
      "limit": 5,
      "used": 2,
      "remaining": 3,
      "is_unlimited": false,
      "reset_at": "2026-06-24T00:00:00.000Z"
    },
    "agents": {
      "enabled": false,
      "limit": 0,
      "used": 0,
      "remaining": 0
    }
  }
}

Ошибки

AUTH_REQUIRED401INTERNAL_ERROR500

POST/api/v1/feedback

Отправить отзыв

Отправьте отзыв о продукте, отчёт об ошибке или запрос новой функции.

Авторизация: Ключ API или JWTЗапрос: application/jsonОтвет: application/json

curl -X POST "https://www.tokcaption.com/api/v1/feedback" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"feature","rating":5,"message":"Add a Zapier integration please!"}'

Поля тела запроса

`category`обязательно string	bug \| feature \| improvement \| other.
`message`обязательно string	До 2000 символов.
`rating` integer \| null	Необязательная оценка от 1 до 5.

Ответ при успехе

{
  "success": true
}

Ошибки

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

Loading API documentation…

POST/api/v1/jobs

Отправить задание на расшифровку

Лимит: submit

Авторизация: Ключ API или JWTЗапрос: application/jsonОтвет: application/json

curl -X POST "https://www.tokcaption.com/api/v1/jobs" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.tiktok.com/@creator/video/1234567890","https://www.tiktok.com/@creator/video/0987654321"],"output_language":"en","also_translate_to":["es"],"allow_asr_fallback":false,"include_download_assets":false,"idempotency_key":"client-req-001"}'

Один URL может вернуть HTTP 200 с конечным ответом completed или failed, если обработка завершается сразу.
Пакетные запросы возвращают HTTP 202 с job_id, общим статусом и статусами каждого элемента в items.
Проверьте массив items для статуса каждого видео: queued, processing, completed или failed.
Если указать include_download_assets: true на бесплатном тарифе, вернётся PLAN_REQUIRED (403).

Поля тела запроса

`urls`обязательно string[]	Ссылки на видео TikTok. Лимит пакетной обработки на бесплатном тарифе — 5.
`output_language` string	Целевой язык расшифровки (код ISO). По умолчанию en.
`also_translate_to` string[]	Дополнительные языки, на которые нужно перевести расшифровку.
`allow_asr_fallback` boolean	Расшифровывать аудио, если дорожка субтитров отсутствует. По умолчанию — false.
`include_download_assets` boolean	Сохранять видео и обложки для скачивания. Только для Pro.
`idempotency_key` string	Ключ дедупликации; повторное использование возвращает исходную задачу.

Ответ при успехе · HTTP 202

{
  "job_id": "b86f89f2-34f6-4b76-88f6-03c13c51b7a6",
  "status": "queued",
  "total_items": 2,
  "items": [
    {
      "id": "tx_1",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "item_index": 0,
      "input_url": "https://www.tiktok.com/@creator/video/1234567890",
      "status": "queued"
    }
  ]
}

Мгновенный единичный успех

HTTP 200

{
  "job_id": "51f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "status": "completed",
  "total_items": 1,
  "completed": 1,
  "failed": 0,
  "items": [
    {
      "id": "tx_single_1",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "item_index": 0,
      "status": "completed",
      "output_language": "en",
      "source_language": "en",
      "selected_track_type": "creator",
      "transcript_text": "Whenever I'm asked to teach a beginner how to cook...",
      "metadata": {
        "author_username": "foodnetwork",
        "duration_seconds": 29
      },
      "completed_at": "2026-03-14T08:33:14.000Z"
    }
  ]
}

Единичная ошибка (нет субтитров)

HTTP 200

{
  "job_id": "8a0d6d7a-78f0-4ab0-8a8c-72f8f5184de8",
  "status": "failed",
  "total_items": 1,
  "completed": 0,
  "failed": 1,
  "items": [
    {
      "id": "tx_single_2",
      "transcript_id": "d40b2545-7c62-4bbb-a7e3-020c663f18a0",
      "item_index": 0,
      "status": "failed",
      "error_code": "NO_CAPTIONS_AVAILABLE",
      "error_message": "Captions are not available for this TikTok video."
    }
  ]
}

Ошибки

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429DUPLICATE_REQUEST409UPSTREAM_TEMPORARY_ERROR503