Aller au contenu principal

Aperçu de l'API Locale

Mise à jour des scripts\nThreads dans Pro prend en charge message, follow_back, scrape_users et repost ; content_type = 2 pour post signifie une publication texte. Le message autonome n'est pas disponible sur TikTok/Instagram : utilisez Super Marketing.\n:::

TikMatrix fournit une API RESTful locale qui vous permet de gérer les tâches par programmation. Cela est particulièrement utile pour intégrer TikMatrix dans vos propres systèmes d'automatisation, créer des flux de travail personnalisés ou effectuer des opérations en masse.

Exigences​

Exigences de licence

L'API locale est disponible uniquement pour les utilisateurs des forfaits Pro, Team et Business. Le forfait Starter ne fournit pas d'accès à l'API.

URL de Base​

L'API fonctionne localement à l'adresse :

http://localhost:50809/api/v1/
remarque

Le port 50809 est le port par défaut. Veuillez vous assurer que TikMatrix est en cours d'exécution avant d'envoyer des requêtes.

Format de Réponse​

Toutes les réponses de l'API suivent le format suivant :

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

Description des Codes de Réponse​

CodeDescription
0Succès
40001Requête incorrecte - Paramètres invalides, y compris une script_config qui échoue à la validation
40002Erreur de paramètre - script_name manquant
40003Requête incorrecte - Script non pris en charge par cette build ou cette plateforme, sans implémentation, ou état de tâche invalide
40004Erreur de paramètre - Seules les tâches en cours d'exécution peuvent être arrêtées
40005Erreur de paramètre - task_ids ne peut pas être vide
40301Interdit - L'accès à l'API nécessite un forfait Pro+
40401Non trouvé - La ressource n'existe pas
50001Erreur interne du serveur

Démarrage Rapide​

1. Vérifier l'Accès à l'API​

Tout d'abord, confirmez que votre licence prend en charge l'API :

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

Exemple de réponse :

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

2. Découvrir les scripts et leurs paramètres​

GET /api/v1/schema décrit chaque script que cette build peut exécuter ainsi que les champs script_config exacts qu’il accepte : noms, types, valeurs par défaut, valeurs autorisées et champs obligatoires. Il est généré à partir du même catalogue que celui utilisé pour la validation côté serveur, il ne peut donc pas diverger de ce que la création de tâche accepte.

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

Deux paramètres de requête facultatifs :

ParamètreEffet
platformRestreint la liste à tiktok, instagram ou threads. Une plateforme absente de cette build est rejetée avec 40001. Par défaut, toutes celles de la build.
include_unavailableÀ true, liste aussi les noms de script que l’API accepte mais qui n’ont aucune implémentation. Chacun porte un unavailable_reason.

Réponse (abrégée) :

{
  "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 indique combien de tâches une requête produira : per_device crée une tâche par appareil (ou par compte en mode multi-compte), per_item en crée une par entrée du champ nommé, par appareil.

3. Créer une Tâche​

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": "Regardez ma nouvelle vidéo ! #tendance"
    },
    "enable_multi_account": false
  }'

4. Interroger la Liste des Tâches​

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

Scripts Disponibles​

Le paramètre script_name accepte les valeurs suivantes :

Nom du ScriptDescriptionSupport API
postPublier des vidéos, des images ou des publications texte uniquement sur Threads✅ Pris en charge
followSuivre des utilisateurs✅ Pris en charge
unfollowNe plus suivre des utilisateurs✅ Pris en charge
account_warmupPréchauffer des comptes✅ Pris en charge
commentPublier un nouveau commentaire sur des publications✅ Pris en charge
boost_commentAimer ou répondre à des commentaires existants✅ Pris en charge
loginSe connecter au compte✅ Pris en charge
profileMettre à jour le profil✅ Pris en charge
match_accountAssocier les comptes sur l'appareil✅ Pris en charge
likeAimer des publications✅ Pris en charge
viewRegarder une publication pendant une durée donnée✅ Pris en charge
favoriteEnregistrer une publication dans les Favoris✅ Pris en charge
repostRepartager des vidéos TikTok ou des publications Threads✅ Pris en charge — TikTok et Threads
messageEnvoyer des messages privés✅ Pris en charge — Threads uniquement
follow_backSuivre les comptes de la liste des abonnés✅ Pris en charge — TikTok, Instagram et Threads
follow_suggestedSuivre les comptes suggérés✅ Pris en charge — TikTok uniquement
custom_scriptExécuter un programme que vous avez enregistré✅ Pris en charge ‡
super_marketingCampagne de super marketing✅ Pris en charge †
scrape_usersExporter les noms d'utilisateur des abonnés, des abonnements ou des recherches✅ Pris en charge — TikTok, Instagram et Threads
auto_replyRépondre aux messages privés et aux commentaires❌ Indisponible via l'API §
† Le super marketing utilise des endpoints dédiés

La campagne de super marketing n'est pas créée via POST /api/v1/task. Elle s'appuie sur un dataset de cibles réutilisable et dispose de ses propres endpoints — voir la Configuration du Script Super Marketing.

Messages privés réservés à Threads

La tâche autonome message pilote le parcours profil Threads → Message. Pour TikTok et Instagram, utilisez plutôt super_marketing avec un dataset de cibles.

Scripts propres à une plateforme

repost est implémenté pour TikTok et Threads ; follow_suggested reste réservé à TikTok. follow_back et scrape_users utilisent l'interface de liste d'abonnés et de recherche propre à chaque plateforme, sur un appareil réel, et sont disponibles sur TikTok, Instagram et Threads.

‡ Les scripts personnalisés doivent être enregistrés au préalable

custom_script exécute un programme que vous avez enregistré sous Appareils → Scripts personnalisés. Transmettez son identifiant dans script_config.custom_script_id — voir Scripts personnalisés.

§ La réponse automatique s'exécute depuis sa propre page

auto_reply répond aux messages privés et aux commentaires sur TikTok, Instagram et Threads, avec le forfait Pro ou supérieur. Ses cycles sont planifiés depuis la page Réponse automatique de l'application, qui contient les règles de réponse, les horaires de fonctionnement et l'interrupteur de pause. Il ne peut donc pas être créé via POST /api/v1/task.

Validation de script_config​

La création de tâche valide script_config contre le schéma ci-dessus avant d’écrire quoi que ce soit : un mauvais paramètre revient donc en 400 en nommant le champ, plutôt qu’en tâche qui échoue plus tard sur le téléphone. Trois choses sont rejetées :

  • un champ obligatoire manquant ou vide,
  • un groupe alternatif dont aucun membre n’est renseigné (par exemple follow exige target_users ou target_user),
  • une valeur hors des choices documentés d’un champ.

Les clés absentes du schéma sont ignorées, pas rejetées : l’application de bureau fait passer ses propres clés par le même objet, et rejeter les clés inconnues casserait les intégrations existantes. Elles sont journalisées côté serveur pour vous permettre de repérer une faute de frappe dans le log.

Les nombres peuvent être envoyés sous forme de chaînes ("20" comme 20), conformément à ce que les scripts acceptent déjà.

États des Tâches​

Code d'ÉtatTexte d'ÉtatDescription
0pendingLa tâche est en attente d'exécution
1runningLa tâche est en cours d'exécution
2completedLa tâche a été exécutée avec succès
3failedL'exécution de la tâche a échoué

Suite​