Перейти к основному содержимому

Обзор локального API

TikMatrix предоставляет локальное RESTful API, которое позволяет управлять задачами программно. Это полезно для интеграции TikMatrix с вашими автоматизированными системами, создания пользовательских рабочих процессов или выполнения пакетных операций.

Требования​

Требование лицензии

Локальное API доступно только для подписчиков планов Pro, Team и Business. Для плана Starter доступ к API отсутствует.

Базовый URL​

API работает локально по адресу:

http://localhost:50809/api/v1/
примечание

Порт 50809 — порт по умолчанию. Убедитесь, что TikMatrix запущен перед отправкой запросов.

Формат ответа​

Все ответы API имеют формат:

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

Коды ответов​

CodeОписание
0Успех
40001Неверный запрос - Недопустимые параметры, в том числе script_config, не прошедший проверку
40002Неверный запрос - отсутствует script_name
40003Неверный запрос - Скрипт не поддерживается в этой сборке или на этой платформе, не имеет реализации, либо недопустимое состояние задачи
40004Неверный запрос - можно остановить только запущенные задачи
40005Неверный запрос - task_ids не может быть пустым
40301Запрещено - доступ к API требует план Pro+
40401Не найдено - ресурс отсутствует
50001Внутренняя ошибка сервера

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

1. Проверка доступа к API​

Сначала проверьте, поддерживает ли ваша лицензия доступ к API:

curl http://localhost:50809/api/v1/license/check

Пример ответа:

{
  "code": 0,
  "message": "success",
  "data": {
    "plan_name": "Pro",
    "api_enabled": true,
    "device_limit": 20,
    "message": "API access enabled"
  }
}

2. Как узнать список скриптов и их параметры​

GET /api/v1/schema описывает каждый скрипт, который может выполнить эта сборка, и точный набор полей script_config: имена, типы, значения по умолчанию, допустимые значения и то, какие поля обязательны. Он формируется из того же каталога, по которому проверяет сервер, поэтому не может разойтись с тем, что принимает создание задач.

curl http://localhost:50809/api/v1/schema

Два необязательных параметра запроса:

ПараметрДействие
platformОграничивает выдачу платформой tiktok или instagram. Платформа, которой нет в сборке, отклоняется с кодом 40001. По умолчанию — все платформы сборки.
include_unavailableСо значением true дополнительно перечисляет имена скриптов, которые API принимает, но у которых нет рабочей реализации. У каждого есть unavailable_reason.

Ответ (сокращённо):

{
  "code": 0,
  "message": "success",
  "data": {
    "build": { "platforms": ["tiktok"] },
    "scripts": [
      {
        "name": "follow",
        "internal_name": "follow",
        "summary": "Follow the given users. One task per target.",
        "platforms": ["tiktok", "instagram"],
        "available": true,
        "fan_out": { "kind": "per_item", "key": "target_users", "alt_key": "target_user" },
        "any_of": [["target_users", "target_user"]],
        "fields": [
          {
            "key": "access_method",
            "type": "string",
            "required": false,
            "default": "direct",
            "choices": ["direct", "search"],
            "description": "How to reach the profile: direct (via URL) or search."
          }
        ]
      }
    ]
  }
}

fan_out показывает, сколько задач создаст запрос: per_device создаёт одну задачу на устройство (или на аккаунт в многоаккаунтном режиме), per_item — по одной на каждый элемент указанного поля, на каждое устройство.

3. Создание задачи​

curl -X POST http://localhost:50809/api/v1/task \
  -H "Content-Type: application/json" \
  -d '{
    "serials": ["device_serial_1", "device_serial_2"],
    "script_name": "post",
    "script_config": {
      "content_type": 1,
      "captions": "Смотрите моё новое видео! #вирусное"
    },
    "enable_multi_account": false,
    "start_time": "14:30"
  }'

4. Получение списка задач​

curl http://localhost:50809/api/v1/task?status=0&page=1&page_size=20

Доступные скрипты​

Параметр script_name может принимать следующие значения:

СкриптОписаниеПоддержка API
postОпубликовать контент✅ Поддерживается
followПодписаться на пользователя✅ Поддерживается
unfollowОтписаться✅ Поддерживается
account_warmupРазогрев аккаунта✅ Поддерживается
commentОставить комментарий к публикации✅ Поддерживается
boost_commentЛайк / ответ на существующие комментарии✅ Поддерживается
loginВойти в аккаунт✅ Поддерживается
profileОбновить профиль✅ Поддерживается
match_accountСопоставить аккаунты на устройстве✅ Поддерживается
likeПоставить лайк✅ Поддерживается
viewПросмотр публикации в течение заданного времени✅ Поддерживается
favoriteСохранить публикацию в избранное✅ Поддерживается
repostРепостить видео TikTok✅ Поддерживается — только TikTok
messageОтправить сообщение❌ Недоступно §
follow_suggestedПодписаться на рекомендованных✅ Поддерживается — только TikTok
super_marketingСупер маркетинговая кампания✅ Поддерживается †
scrape_userСобирать данные о пользователе🔜 Скоро
† Супер маркетинг использует отдельные эндпоинты

Кампания супер маркетинга не создаётся через POST /api/v1/task. Она работает на основе многократно используемого датасета целей с собственными эндпоинтами — см. Конфигурацию скрипта супер маркетинга.

§ у message нет реализации

message принимался при создании задачи, но в бинарнике скриптов нет обработчика для него ни на одной из платформ, поэтому каждая такая задача падала на устройстве с ошибкой "Unknown script". Теперь она отклоняется уже при создании с указанием этой причины. Для личных сообщений используйте super_marketing, который рассылает их по набору целей.

Скрипты, зависящие от платформы

repost и follow_suggested реализованы только для TikTok. Создание такой задачи для цели в Instagram отклоняется, а не ставится в очередь — раньше задача создавалась и затем падала на устройстве.

Проверка script_config​

Перед записью создание задачи проверяет script_config по описанной выше схеме, поэтому неверный параметр возвращается как 400 с указанием поля, а не превращается в задачу, которая упадёт на телефоне позже. Отклоняются три вещи:

  • обязательное поле отсутствует или пусто;
  • ни один член группы «одно из» не задан (например, follow требует target_users или target_user);
  • значение вне документированного списка choices для поля.

Ключи, которых нет в схеме, игнорируются, а не отклоняются — настольное приложение передаёт собственные ключи через тот же объект, и отклонение неизвестных сломало бы существующие интеграции. Они пишутся в серверный журнал, так что опечатку можно заметить в логе приложения.

Числа можно передавать строками ("20" наравне с 20) — так же, как их уже принимают скрипты.

Статус задачи​

Код статусаСтатусОписание
0pendingЗадача ожидает выполнения
1runningЗадача выполняется
2completedЗадача выполнена успешно
3failedЗадача завершилась с ошибкой

Дальше​