Przejdź do głównej zawartości

Przegląd Local API

TikMatrix zapewnia lokalne RESTful API, które pozwala na programowe zarządzanie zadaniami. Jest to przydatne do integracji TikMatrix z własnymi systemami automatyzacji, tworzenia niestandardowych przepływów pracy lub wykonywania operacji wsadowych.

Wymagania​

Wymaganie licencji

Local API jest dostępne tylko dla subskrybentów planów Pro, Team i Business. Plan Starter nie ma dostępu do API.

Bazowy URL​

API działa na twoim lokalnym komputerze pod adresem:

http://localhost:50809/api/v1/
notatka

Port 50809 jest domyślnym portem. Upewnij się, że TikMatrix jest uruchomiony przed wykonywaniem żądań API.

Format odpowiedzi​

Wszystkie odpowiedzi API mają następujący format:

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

Kody odpowiedzi​

KodOpis
0Sukces
40001Błędne żądanie - Nieprawidłowe parametry, w tym script_config, który nie przechodzi walidacji
40002Złe żądanie - Brak script_name
40003Błędne żądanie - Skrypt nieobsługiwany w tej kompilacji lub na tej platformie, bez implementacji, albo nieprawidłowy stan zadania
40004Złe żądanie - Tylko uruchomione zadania mogą być zatrzymane
40005Złe żądanie - task_ids nie może być puste
40301Zabronione - Dostęp do API wymaga planu Pro+
40401Nie znaleziono - Zasób nie znaleziony
50001Wewnętrzny błąd serwera

Szybki start​

1. Sprawdź dostęp do API​

Najpierw sprawdź, czy twoja licencja obsługuje dostęp do API:

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

Odpowiedź:

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

2. Poznaj skrypty i ich parametry​

GET /api/v1/schema opisuje każdy skrypt, który ta kompilacja potrafi uruchomić, oraz dokładne pola script_config, jakie przyjmuje: nazwy, typy, wartości domyślne, dozwolone wartości i to, które są wymagane. Powstaje z tego samego katalogu, względem którego waliduje serwer, więc nie może rozminąć się z tym, co akceptuje tworzenie zadań.

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

Dwa opcjonalne parametry zapytania:

ParametrDziałanie
platformOgranicza listę do tiktok lub instagram. Platforma, której ta kompilacja nie zawiera, jest odrzucana z kodem 40001. Domyślnie wszystkie z kompilacji.
include_unavailableUstawione na true wypisuje także nazwy skryptów, które API przyjmuje, ale które nie mają działającej implementacji. Każdy niesie unavailable_reason.

Odpowiedź (skrócona):

{
  "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 mówi, ile zadań wyprodukuje żądanie: per_device tworzy jedno zadanie na urządzenie (lub na konto w trybie wielu kont), per_item tworzy jedno na każdy wpis wskazanego pola, na urządzenie.

3. Utwórz zadanie​

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": "Check out my new video! #viral"
    },
    "enable_multi_account": false,
    "start_time": "14:30"
  }'

4. Wyświetl zadania​

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

Dostępne skrypty​

Parametr script_name akceptuje następujące wartości:

Nazwa skryptuOpisWsparcie API
postPublikowanie treści✅ Obsługiwane
followObserwowanie użytkowników✅ Obsługiwane
unfollowZaprzestanie obserwacji użytkowników✅ Obsługiwane
account_warmupRozgrzewanie kont✅ Obsługiwane
commentDodawanie nowego komentarza do postów✅ Obsługiwane
boost_commentPolubienie/odpowiedź na istniejące komentarze✅ Obsługiwane
loginZaloguj się na konto✅ Obsługiwane
profileZaktualizuj profil✅ Obsługiwane
match_accountDopasuj konta na urządzeniu✅ Obsługiwane
likePolubienia postów✅ Obsługiwane
viewOglądaj post przez określony czas✅ Obsługiwane
favoriteZapisz post do Ulubionych✅ Obsługiwane
repostRepostuj filmy TikTok✅ Obsługiwane — tylko TikTok
messageWysyłanie wiadomości bezpośrednich❌ Niedostępne §
follow_suggestedObserwuj sugerowane konta✅ Obsługiwane — tylko TikTok
super_marketingKampania super marketingu✅ Obsługiwane †
scrape_userZbieranie danych użytkownika🔜 Wkrótce
† Super marketing używa dedykowanych punktów końcowych

Kampania super marketingu nie jest tworzona przez POST /api/v1/task. Działa na podstawie wielokrotnie używanego zestawu danych celów i ma własne punkty końcowe — zobacz Konfigurację skryptu super marketingu.

§ message nie ma implementacji

message był przyjmowany przy tworzeniu zadań, ale binarka skryptów nie ma dla niego obsługi na żadnej z platform, więc każde takie zadanie kończyło się na urządzeniu błędem "Unknown script". Teraz jest odrzucane już przy tworzeniu, z podaniem tego powodu. Do wysyłania wiadomości prywatnych użyj super_marketing, które prowadzi DM-y na podstawie zbioru odbiorców.

Skrypty zależne od platformy

repost i follow_suggested są zaimplementowane tylko dla TikToka. Utworzenie takiego zadania dla celu na Instagramie jest odrzucane zamiast kolejkowane — wcześniej zadanie powstawało, a potem kończyło się błędem na urządzeniu.

Walidacja script_config​

Tworzenie zadania waliduje script_config względem powyższego schematu, zanim cokolwiek zapisze, więc zły parametr wraca jako 400 ze wskazaniem pola, a nie jako zadanie, które zawiedzie później na telefonie. Odrzucane są trzy rzeczy:

  • wymagane pole, którego brakuje lub jest puste,
  • grupa alternatyw, w której nie ustawiono żadnego z członków (na przykład follow potrzebuje target_users albo target_user),
  • wartość spoza udokumentowanych choices danego pola.

Klucze, których schemat nie wymienia, są ignorowane, a nie odrzucane — aplikacja desktopowa przepuszcza własne klucze przez ten sam obiekt, a odrzucanie nieznanych zepsułoby istniejące integracje. Są logowane po stronie serwera, więc literówkę wypatrzysz w logu aplikacji.

Liczby można przesyłać jako ciągi znaków ("20" tak samo jak 20), zgodnie z tym, co skrypty już przyjmują.

Status zadania​

Kod statusuTekst statusuOpis
0pendingZadanie oczekuje na wykonanie
1runningZadanie jest obecnie wykonywane
2completedZadanie zakończone pomyślnie
3failedZadanie nie powiodło się

Następne kroki​