Zum Hauptinhalt springen

Lokale API-Übersicht

Skriptaktualisierung\nThreads in Pro unterstützt message, follow_back, scrape_users und repost; content_type = 2 bei post steht für einen reinen Textbeitrag. Das eigenständige message-Skript gibt es nicht für TikTok/Instagram; verwenden Sie Super Marketing.\n:::

TikMatrix bietet eine lokale RESTful-API, die es ermöglicht, Aufgaben programmatisch zu verwalten. Dies ist nützlich für die Integration von TikMatrix in Ihre Automatisierungssysteme, das Erstellen benutzerdefinierter Workflows oder das Durchführen von Batch-Operationen.

Anforderungen​

Lizenzanforderung

Die lokale API ist nur für Abonnenten der Pro-, Team- und Business-Pläne verfügbar. Für den Starter-Plan ist kein API-Zugriff verfügbar.

Basis-URL​

Die API läuft lokal unter:

http://localhost:50809/api/v1/
hinweis

Port 50809 ist der Standardport. Stellen Sie sicher, dass TikMatrix läuft, bevor Sie Anfragen senden.

Antwortformat​

Alle API-Antworten haben das Format:

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

Antwortcodes​

CodeBeschreibung
0Erfolg
40001Bad Request - Ungültige Parameter, einschließlich einer script_config, die die Validierung nicht besteht
40002Ungültige Anfrage - fehlender script_name
40003Bad Request - Skript auf diesem Build oder dieser Plattform nicht unterstützt, ohne Implementierung, oder ungültiger Aufgabenstatus
40004Ungültige Anfrage - Nur laufende Tasks können gestoppt werden
40005Ungültige Anfrage - task_ids darf nicht leer sein
40301Verboten - API-Zugriff erfordert Pro+-Plan
40401Nicht gefunden - Ressource existiert nicht
50001Interner Serverfehler

Schnellstart​

1. API-Zugriff prüfen​

Prüfen Sie zunächst, ob Ihre Lizenz API-Zugriff unterstützt:

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

Beispielantwort:

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

2. Die Skripte und ihre Parameter abfragen​

GET /api/v1/schema beschreibt jedes Skript, das dieser Build ausführen kann, samt der genauen script_config-Felder: Namen, Typen, Standardwerte, erlaubte Werte und welche Felder erforderlich sind. Es wird aus demselben Katalog erzeugt, gegen den der Server validiert, und kann deshalb nicht von dem abweichen, was die Aufgabenerstellung akzeptiert.

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

Zwei optionale Query-Parameter:

ParameterWirkung
platformBeschränkt die Auflistung auf tiktok, instagram oder threads. Eine Plattform, die dieser Build nicht mitbringt, wird mit 40001 abgelehnt. Standard sind alle Plattformen des Builds.
include_unavailableAuf true gesetzt, werden auch Skriptnamen aufgeführt, die die API akzeptiert, für die es aber keine Implementierung gibt. Jeder trägt einen unavailable_reason.

Antwort (gekürzt):

{
  "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", "threads"],
        "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 sagt, wie viele Aufgaben eine Anfrage erzeugt: per_device erstellt eine Aufgabe pro Gerät (bzw. pro Konto im Mehrkonto-Modus), per_item eine pro Eintrag des genannten Feldes, pro Gerät.

3. Aufgabe erstellen​

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": "Schaut euch mein neues Video an! #viral"
    },
    "enable_multi_account": false
  }'

4. Aufgaben auflisten​

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

Verfügbare Skripte​

Der Parameter script_name akzeptiert folgende Werte:

SkriptBeschreibungAPI-Unterstützung
postVideos, Bilder oder reine Text-Beiträge auf Threads veröffentlichen✅ Unterstützt
followBenutzern folgen✅ Unterstützt
unfollowBenutzern entfolgen✅ Unterstützt
account_warmupKonten aufwärmen✅ Unterstützt
commentEinen neuen Kommentar zu Beiträgen hinterlassen✅ Unterstützt
boost_commentVorhandene Kommentare liken / beantworten✅ Unterstützt
loginBeim Konto anmelden✅ Unterstützt
profileProfil aktualisieren✅ Unterstützt
match_accountKonten auf dem Gerät zuordnen✅ Unterstützt
likeBeiträge liken✅ Unterstützt
viewEinen Beitrag für eine bestimmte Zeit ansehen✅ Unterstützt
favoriteBeitrag zu Favoriten speichern✅ Unterstützt
repostTikTok-Videos oder Threads-Beiträge reposten✅ Unterstützt — TikTok und Threads
messageDirektnachrichten senden✅ Unterstützt — nur Threads
follow_backKonten aus der Follower-Liste zurückfolgen✅ Unterstützt — TikTok, Instagram und Threads
follow_suggestedVorgeschlagenen Konten folgen✅ Unterstützt — nur TikTok
custom_scriptEin selbst registriertes Programm ausführen✅ Unterstützt ‡
super_marketingSuper-Marketing-Kampagne✅ Unterstützt †
scrape_usersFollower-, Following- oder Suchbenutzernamen exportieren✅ Unterstützt — TikTok, Instagram und Threads
auto_replyDirektnachrichten und Kommentare beantworten❌ Nicht über die API §
† Super-Marketing verwendet eigene Endpunkte

Die Super-Marketing-Kampagne wird nicht über POST /api/v1/task erstellt. Sie läuft auf einem wiederverwendbaren Ziel-Datensatz und hat eigene Endpunkte — siehe Konfiguration des Super-Marketing-Skripts.

Direktnachrichten nur für Threads

Die eigenständige message-Aufgabe steuert den Ablauf Threads-Profil → Nachrichten. Für TikTok und Instagram verwenden Sie stattdessen super_marketing mit einem Ziel-Datensatz.

Plattformspezifische Skripte

repost ist für TikTok und Threads implementiert; follow_suggested bleibt nur für TikTok verfügbar. follow_back und scrape_users nutzen die Follower- und Suchoberfläche jeder Plattform auf dem echten Gerät und sind auf TikTok, Instagram und Threads verfügbar.

‡ Benutzerdefinierte Skripte müssen zuerst registriert werden

custom_script führt ein Programm aus, das Sie unter Geräte → Benutzerdefinierte Skripte registriert haben. Übergeben Sie dessen ID in script_config.custom_script_id — siehe Benutzerdefinierte Skripte.

§ Die Auto-Antwort läuft auf einer eigenen Seite

auto_reply beantwortet Direktnachrichten und Kommentare auf TikTok, Instagram und Threads im Pro-Tarif und höher. Seine Durchläufe werden auf der Seite Auto-Antwort der App geplant, die die Antwortregeln, Arbeitszeiten und den Pausenschalter enthält. Daher kann sie nicht über POST /api/v1/task erstellt werden.

script_config-Validierung​

Die Aufgabenerstellung validiert script_config gegen das obige Schema, bevor irgendetwas geschrieben wird. Ein falscher Parameter kommt so als 400 mit Feldnamen zurück statt als Aufgabe, die später auf dem Telefon scheitert. Drei Dinge werden abgelehnt:

  • ein erforderliches Feld, das fehlt oder leer ist,
  • eine Entweder-oder-Gruppe, in der kein Mitglied gesetzt ist (z. B. braucht follow eines von target_users / target_user),
  • ein Wert außerhalb der dokumentierten choices eines Feldes.

Schlüssel, die das Schema nicht kennt, werden ignoriert, nicht abgelehnt — die Desktop-App reicht eigene Schlüssel durch dasselbe Objekt, und unbekannte Schlüssel abzulehnen würde bestehende Integrationen brechen. Sie werden serverseitig protokolliert, damit Sie Tippfehler im App-Log finden.

Zahlen dürfen als Zeichenketten gesendet werden ("20" ebenso wie 20), passend zu dem, was die Skripte ohnehin akzeptieren.

Aufgabenstatus​

StatuscodeStatusBeschreibung
0pendingAufgabe wartet auf Ausführung
1runningAufgabe wird ausgeführt
2completedAufgabe erfolgreich abgeschlossen
3failedAufgabe mit Fehler beendet

Weiterführend​