Ga naar hoofdinhoud

Local API Overzicht

TikMatrix biedt een lokale RESTful API waarmee u taken programmatisch kunt beheren. Dit is handig voor het integreren van TikMatrix met uw eigen automatiseringssystemen, het bouwen van aangepaste workflows of het maken van batchbewerkingen.

Vereisten​

Licentie Vereiste

De Local API is alleen beschikbaar voor Pro, Team en Business plan abonnees. Het Starter plan heeft geen toegang tot de API.

Basis URL​

De API draait op uw lokale machine op:

http://localhost:50809/api/v1/
notitie

De poort 50809 is de standaard poort. Zorg ervoor dat TikMatrix draait voordat u API verzoeken doet.

Response Formaat​

Alle API responses volgen dit formaat:

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

Response Codes​

CodeBeschrijving
0Succes
40001Ongeldig verzoek - Ongeldige parameters, waaronder een script_config die de validatie niet doorstaat
40002Bad Request - Ontbrekende script_name
40003Ongeldig verzoek - Script niet ondersteund op deze build of dit platform, zonder implementatie, of ongeldige taakstatus
40004Bad Request - Alleen lopende taken kunnen worden gestopt
40005Bad Request - task_ids kan niet leeg zijn
40301Forbidden - API toegang vereist Pro+ plan
40401Not Found - Resource niet gevonden
50001Internal Server Error

Snelstart​

1. Controleer API Toegang​

Controleer eerst of uw licentie API toegang ondersteunt:

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

Response:

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

2. De scripts en hun parameters opvragen​

GET /api/v1/schema beschrijft elk script dat deze build kan uitvoeren en precies welke script_config-velden het aanneemt: namen, typen, standaardwaarden, toegestane waarden en welke verplicht zijn. Het wordt gegenereerd uit dezelfde catalogus waartegen de server valideert, dus het kan niet afwijken van wat het aanmaken van taken accepteert.

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

Twee optionele queryparameters:

ParameterEffect
platformBeperkt de lijst tot tiktok of instagram. Een platform dat deze build niet meelevert wordt afgewezen met 40001. Standaard alles wat de build meelevert.
include_unavailableOp true worden ook scriptnamen getoond die de API accepteert maar die geen werkende implementatie hebben. Elk draagt een unavailable_reason.

Antwoord (ingekort):

{
  "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 zegt hoeveel taken een verzoek oplevert: per_device maakt één taak per apparaat (of per account in multi-accountmodus), per_item maakt er één per item van het genoemde veld, per apparaat.

3. Maak een Taak​

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. Lijst Taken​

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

Beschikbare Scripts​

De script_name parameter accepteert de volgende waarden:

Script NaamBeschrijvingAPI Ondersteuning
postPubliceer inhoud✅ Ondersteund
followVolg gebruikers✅ Ondersteund
unfollowOntvolg gebruikers✅ Ondersteund
account_warmupWarm accounts op✅ Ondersteund
commentReageer op posts✅ Ondersteund
boost_commentLike/beantwoord bestaande opmerkingen✅ Ondersteund
loginInloggen op account✅ Ondersteund
profileProfiel bijwerken✅ Ondersteund
match_accountAccounts op apparaat koppelen✅ Ondersteund
likeLike posts✅ Ondersteund
viewBekijk een bericht voor een bepaalde duur✅ Ondersteund
favoriteSla een bericht op in Favorieten✅ Ondersteund
repostTikTok-video's herplaatsen✅ Ondersteund — alleen TikTok
messageStuur directe berichten❌ Niet beschikbaar §
follow_suggestedVolg voorgestelde accounts✅ Ondersteund — alleen TikTok
super_marketingSuper marketing campagne✅ Ondersteund †
scrape_userScrape gebruikersgegevens🔜 Binnenkort
† Super marketing gebruikt speciale eindpunten

De super marketing campagne wordt niet aangemaakt via POST /api/v1/task. Het maakt gebruik van een herbruikbare doeldataset met eigen eindpunten — zie Super Marketing Script Configuratie.

§ message heeft geen implementatie

message werd geaccepteerd bij het aanmaken van taken, maar de script-binary heeft er op geen van beide platforms een handler voor, dus elke zo’n taak mislukte op het apparaat met "Unknown script". Hij wordt nu al bij het aanmaken afgewezen, met die reden. Gebruik voor directe berichten super_marketing, dat DM’s aanstuurt via een doelgroepbestand.

Platformspecifieke scripts

repost en follow_suggested zijn alleen voor TikTok geïmplementeerd. Er een aanmaken tegen een Instagram-doel wordt afgewezen in plaats van ingepland — voorheen werd de taak aangemaakt en mislukte daarna op het apparaat.

script_config-validatie​

Bij het aanmaken van een taak wordt script_config eerst tegen bovenstaand schema gevalideerd, zodat een verkeerde parameter terugkomt als een 400 die het veld noemt, in plaats van als een taak die later op de telefoon mislukt. Drie dingen worden afgewezen:

  • een verplicht veld dat ontbreekt of leeg is,
  • een of-of-groep waarvan geen enkel lid is ingevuld (follow heeft bijvoorbeeld target_users of target_user nodig),
  • een waarde buiten de gedocumenteerde choices van een veld.

Sleutels die het schema niet kent worden genegeerd, niet afgewezen — de desktop-app stuurt eigen sleutels door hetzelfde object, en onbekende sleutels weigeren zou bestaande integraties breken. Ze worden serverzijdig gelogd zodat je een typefout in het app-log kunt vinden.

Getallen mogen als tekst worden verstuurd ("20" net zo goed als 20), passend bij wat de scripts al accepteren.

Taak Status​

Status CodeStatus TekstBeschrijving
0pendingTaak wacht om uitgevoerd te worden
1runningTaak wordt momenteel uitgevoerd
2completedTaak succesvol voltooid
3failedTaak mislukt

Volgende Stappen​