Passa al contenuto principale

Panoramica dell'API Locale

Aggiornamento script\nThreads in Pro supporta message, follow_back, scrape_users e repost; in post content_type = 2 indica un post solo testuale. Il message autonomo non è disponibile su TikTok/Instagram: usa Super Marketing.\n:::

TikMatrix fornisce un'API RESTful locale che consente di gestire le attività in modo programmatico. Questo è utile per integrare TikMatrix nei tuoi sistemi di automazione, creare flussi di lavoro personalizzati o eseguire operazioni in blocco.

Requisiti​

Requisito di Licenza

L'API locale è disponibile solo per gli abbonati ai piani Pro, Team e Business. Il piano Starter non ha accesso all'API.

URL Base​

L'API è in esecuzione sulla tua macchina locale all'indirizzo:

http://localhost:50809/api/v1/
note

La porta 50809 è la porta predefinita. Assicurati che TikMatrix sia in esecuzione prima di effettuare richieste API.

Formato di Risposta​

Tutte le risposte API seguono questo formato:

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

Codici di Risposta​

CodiceDescrizione
0Successo
40001Richiesta non valida - Parametri non validi, inclusa una script_config che non supera la convalida
40002Richiesta non valida - script_name mancante
40003Richiesta non valida - Script non supportato su questa build o piattaforma, privo di implementazione, o stato attività non valido
40004Richiesta non valida - Solo le attività in esecuzione possono essere interrotte
40005Richiesta non valida - task_ids non può essere vuoto
40301Vietato - L'accesso all'API richiede il piano Pro+
40401Non trovato - Risorsa non trovata
50001Errore interno del server

Avvio Rapido​

1. Verifica Accesso API​

Prima di tutto, verifica che la tua licenza supporti l'accesso all'API:

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

Risposta:

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

2. Scoprire gli script e i loro parametri​

GET /api/v1/schema descrive ogni script che questa build può eseguire e i campi esatti di script_config che accetta: nomi, tipi, valori predefiniti, valori ammessi e quali sono obbligatori. È generato dallo stesso catalogo usato dal server per la convalida, quindi non può divergere da ciò che la creazione attività accetta.

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

Due parametri di query facoltativi:

ParametroEffetto
platformLimita l’elenco a tiktok, instagram o threads. Una piattaforma non inclusa in questa build viene rifiutata con 40001. Per impostazione predefinita, tutte quelle della build.
include_unavailableImpostato a true, elenca anche i nomi di script accettati dall’API ma privi di implementazione. Ognuno riporta un unavailable_reason.

Risposta (abbreviata):

{
  "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 indica quante attività produrrà una richiesta: per_device crea un’attività per dispositivo (o per account in modalità multi-account), per_item ne crea una per ogni voce del campo indicato, per dispositivo.

3. Creare un'Attività​

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": "Guarda il mio nuovo video! #virale"
    },
    "enable_multi_account": false,
    "start_time": "14:30"
  }'

4. Elenco Attività​

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

Script Disponibili​

Il parametro script_name accetta i seguenti valori:

Nome ScriptDescrizioneSupporto API
postPubblica video, immagini o post di solo testo su Threads✅ Supportato
followSegui utenti✅ Supportato
unfollowSmetti di seguire utenti✅ Supportato
account_warmupRiscalda gli account✅ Supportato
commentPubblica un nuovo commento sui post✅ Supportato
boost_commentMetti mi piace o rispondi ai commenti esistenti✅ Supportato
loginAccedi all'account✅ Supportato
profileAggiorna il profilo✅ Supportato
match_accountAbbina gli account sul dispositivo✅ Supportato
likeMetti mi piace ai post✅ Supportato
viewGuarda un post per una durata✅ Supportato
favoriteSalva un post nei Preferiti✅ Supportato
repostRipubblica video TikTok o post di Threads✅ Supportato — TikTok e Threads
messageInvia messaggi diretti✅ Supportato — solo Threads
follow_backSegui gli account dalla lista dei follower✅ Supportato — TikTok, Instagram e Threads
follow_suggestedSegui gli account suggeriti✅ Supportato — solo TikTok
custom_scriptEsegui un programma registrato da te✅ Supportato ‡
super_marketingCampagna di super marketing✅ Supportato †
scrape_usersEsporta username di follower, following o di ricerca✅ Supportato — TikTok, Instagram e Threads
auto_replyRispondi a messaggi diretti e commenti❌ Non tramite API §
† Il super marketing utilizza endpoint dedicati

La campagna di super marketing non viene creata tramite POST /api/v1/task. Si basa su un dataset di target riutilizzabile e ha endpoint propri — vedi Configurazione dello script Super Marketing.

Messaggi diretti solo per Threads

Il task message autonomo esegue il flusso profilo Threads → Message. Per TikTok e Instagram, usa invece super_marketing con un dataset di target.

Script specifici per piattaforma

repost è implementato per TikTok e Threads; follow_suggested resta solo per TikTok. follow_back e scrape_users usano l'interfaccia reale di follower/ricerca di ciascuna piattaforma su dispositivo fisico e sono disponibili su TikTok, Instagram e Threads.

‡ Gli script personalizzati vanno registrati prima

custom_script esegue un programma registrato in Dispositivi → Script personalizzati. Passa il suo id in script_config.custom_script_id — vedi Script personalizzati.

§ La risposta automatica viene eseguita dalla propria pagina

auto_reply risponde a messaggi diretti e commenti su TikTok, Instagram e Threads, con piano Pro o superiore. I suoi cicli sono pianificati dalla pagina Risposta automatica dell'app, che contiene le regole di risposta, gli orari di lavoro e l'interruttore di pausa, quindi non può essere creata tramite POST /api/v1/task.

Convalida di script_config​

La creazione attività convalida script_config rispetto allo schema qui sopra prima di scrivere qualsiasi cosa, così un parametro sbagliato torna come 400 che nomina il campo, invece di un’attività che fallisce più tardi sul telefono. Vengono rifiutate tre cose:

  • un campo obbligatorio mancante o vuoto,
  • un gruppo alternativo in cui nessun membro è impostato (per esempio follow richiede uno tra target_users / target_user),
  • un valore fuori dai choices documentati di un campo.

Le chiavi non elencate nello schema vengono ignorate, non rifiutate: l’app desktop fa passare le proprie chiavi attraverso lo stesso oggetto e rifiutare quelle sconosciute romperebbe le integrazioni esistenti. Vengono registrate lato server così puoi individuare un refuso nel log dell’app.

I numeri possono essere inviati come stringhe ("20" oltre a 20), coerentemente con quanto gli script già accettano.

Stato dell'Attività​

Codice StatoTesto StatoDescrizione
0pendingAttività in attesa di esecuzione
1runningAttività in esecuzione
2completedAttività completata con successo
3failedAttività fallita

Passi Successivi​