Zum Hauptinhalt springen

Lokale API-Übersicht

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 oder instagram. 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"],
        "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 kann folgende Werte annehmen:

SkriptBeschreibungAPI-Unterstützung
postInhalt veröffentlichen✅ Unterstützt
followBenutzer folgen✅ Unterstützt
unfollowEntfolgen✅ Unterstützt
account_warmupAccount-Warmup✅ Unterstützt
commentKommentar hinterlassen✅ Unterstützt
boost_commentVorhandene Kommentare liken/beantworten✅ Unterstützt
loginBeim Konto anmelden✅ Unterstützt
profileProfil aktualisieren✅ Unterstützt
match_accountKonten auf Gerät zuordnen✅ Unterstützt
likeLiken✅ Unterstützt
viewBeitrag eine bestimmte Zeit ansehen✅ Unterstützt
favoriteBeitrag zu Favoriten hinzufügen✅ Unterstützt
repostTikTok-Videos reposten✅ Unterstützt — nur TikTok
messageNachricht senden❌ Nicht verfügbar §
follow_suggestedVorgeschlagenen Konten folgen✅ Unterstützt — nur TikTok
super_marketingSuper-Marketing-Kampagne✅ Unterstützt †
scrape_userBenutzerdaten sammeln🔜 Bald
† Super-Marketing verwendet eigene Endpunkte

Die Super-Marketing-Kampagne wird nicht über POST /api/v1/task erstellt. Sie basiert auf einem wiederverwendbaren Ziel-Datensatz mit eigenen Endpunkten — siehe Super-Marketing-Skript-Konfiguration.

§ message hat keine Implementierung

message wurde von der Aufgabenerstellung akzeptiert, aber die Skript-Binary hat auf keiner der beiden Plattformen einen Handler dafür, sodass jede solche Aufgabe auf dem Gerät mit "Unknown script" fehlschlug. Sie wird nun bereits bei der Erstellung mit dieser Begründung abgelehnt. Für Direktnachrichten verwenden Sie super_marketing, das DMs über einen Ziel-Datensatz steuert.

Plattformspezifische Skripte

repost und follow_suggested sind nur für TikTok implementiert. Eine Erstellung gegen ein Instagram-Ziel wird abgelehnt statt eingereiht — zuvor wurde die Aufgabe erstellt und schlug dann auf dem Gerät fehl.

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​