tiktok/
user-live

Controlla se gli account TikTok pubblici sono in diretta tramite il nome utente, con stato live oppure offline e dettagli disponibili della stanza per più account in una sola richiesta.

TikTok User Live API

Controllo degli account per nome utente
Risultati live e offline
Più account per richiesta
0,5 crediti per risultato
Pronto
Pronto

Inserisci i parametri e invia una richiesta. Qui compariranno lo stato dell’attività e i risultati normalizzati.

README

A cura di SocQ · Aggiornato il

TikTok User Live

Lo stato live di un account TikTok descrive se sta trasmettendo in un dato momento, mentre una diretta attiva può avere un titolo della stanza, una copertina e un numero di spettatori. Conservare insieme a quello stato l’identità del creator e l’orario aiuta a capire quale account era in diretta e quanto sono recenti le informazioni.

Funzionalità della TikTok User Live API

  • Scopri se la ricerca ha trovato un account live o offlineOgni ricerca riuscita restituisce is_live come true per live o false per offline, così un account che non trasmette ha comunque un record di stato invece di sparire semplicemente dai risultati.
  • Vedi i dettagli della stanza di una diretta attivaUn record live può includere il titolo della stanza, il nome del creator, l’immagine di copertina e il numero di spettatori, dandoti informazioni sulla diretta e non solo uno stato sì o no.
  • Parti dagli handle degli account e non dagli identificatori delle stanzeCerca più nomi utente pubblici in una sola richiesta senza dover prima trovare room_id e user_id, necessari per la ricerca separata dei dettagli della stanza live.

Parametri della TikTok User Live API

ParametriObbligatorioDescrizione
usernamesObbligatorioElenco obbligatorio di almeno un handle di account pubblico, con o senza @; nel Playground inserisci un nome utente per riga, mentre in JSON usa un array come ["thejustalex", "@tiktok"] e non URL di profili.

Come usare la TikTok User Live API

La richiesta avvia un’attività di raccolta in background, quindi la prima risposta contiene un ID attività e non i dati finali; usa quell’ID per controllare l’avanzamento e recuperare i risultati.

  1. Prepara uno o più nomi utente pubblici e non link a profili o a stanze live; puoi copiare l’handle dopo la @ dal profilo di un account.
  2. Prima di eseguire l’esempio, sostituisci $SOCQ_API_KEY con la tua chiave API oppure imposta quella variabile d’ambiente. Invia l’input JSON a POST /v1/tiktok/user-live con l’intestazione Authorization mostrata qui sotto, poi salva il task_id dalla risposta.
  3. Usa GET /v1/tasks/{task_id} con l’ID salvato per controllare l’avanzamento. queued significa in attesa, running significa raccolta in corso e retrying significa che è in corso un nuovo tentativo. Attendi succeeded prima di leggere i risultati; se l’attività è failed, leggi error_message per conoscere il motivo.
  4. Quando l’attività riesce, leggi data.results.items: ogni elemento di questo elenco descrive lo stato di un account controllato con successo. Un elenco vuoto significa che l’attività è terminata senza restituire alcun record.
  5. Se data.results.has_more è true, il valore next_cursor è il segnaposto per un’altra pagina di risultati salvati. Copialo senza modifiche nel parametro cursor di GET /v1/tasks/{task_id}?cursor=... e continua finché has_more è false.
curl -X POST "https://api.socq.ai/v1/tiktok/user-live" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["thejustalex"]}'

Casi d’uso della TikTok User Live API

  • Prepara una bacheca dello stato live degli account: Crea una tabella con ogni creator, lo stato live o offline e l’orario di raccolta, così chiunque può controllare quali degli account forniti erano in diretta all’ultima osservazione.
  • Crea un elenco di revisione delle dirette attive: Seleziona i record con is_live=true e combina i link alle stanze, i titoli e i numeri di spettatori in un elenco di stanze attive da aprire e rivedere.

Consigli degli esperti per la TikTok User Live API

  • Prima di inviare un elenco ripetuto di handle, rimuovi le @ iniziali e deduplica senza distinguere maiuscole e minuscole, così tiktok e @TikTok non gonfiano la stima del numero di input.
  • Quando un record indica is_live=false, mostralo come offline e lascia vuoti i campi mancanti della stanza invece di segnalare che la ricerca dell’account è fallita.
  • Per una bacheca di stato che aggiorni tu stesso, mostra collected_at accanto allo stato, così un risultato precedente non viene scambiato per un’osservazione appena effettuata.
  • Se hai già un room_id e uno user_id corrispondenti e vuoi una ricerca separata della stanza, usa TikTok Live Room Info invece di inviare quegli ID nel campo usernames.

Oltre alla TikTok User Live API, usa queste API quando ti serve un altro tipo di dati pubblici di TikTok.

  • TikTok Profiles API — Recupera identità del profilo pubblico, bio, flag dell’account e conteggi del pubblico a partire dal nome utente.
  • TikTok Videos API — Recupera creator, didascalia, media, musica, tag, menzioni ed engagement dagli URL dei video.
  • TikTok User Videos API — Raccoglie i video pubblici del feed di un profilo a partire dal nome utente con didascalie, creator, media, date, engagement e contesto dell’account di origine.
  • TikTok Live Room Info API — Consulta una diretta nota tramite la coppia di ID della stanza e del proprietario, restituendo stato, contesto del proprietario, immagine di copertina e conteggi del pubblico.
  • TikTok Trending Feed API — Raccoglie il feed video pubblico attuale di una regione con creator, didascalia, copertina, data ed engagement visibile.
  • TikTok Live Shopping API — Elenca i prodotti nel carrello di una diretta LIVE, con prezzi attuali e unità vendute.

Esplora altre piattaforme

Combina i dati di TikTok con i dati pubblici delle altre piattaforme social supportate.

TikTok User Live API — FAQ

TikTok User Live API è un’interfaccia programmatica per controllare se gli account TikTok pubblici sono in diretta a partire da un elenco di nomi utente. Restituisce uno stato live oppure offline per ogni ricerca riuscita, più le informazioni sul creator e i dettagli disponibili della stanza per le dirette attive.

Significa che l’account non era in diretta al momento del controllo, non che la ricerca è fallita. Un record offline riuscito ha is_live=false e status=offline, mentre titolo della stanza, numero di spettatori o altri campi della stanza possono essere vuoti.

No. Inserisci il nome utente dell’account, come thejustalex o @thejustalex; room_id e user_id appartengono all’input separato di TikTok Live Room Info.

No. Un’attività controlla lo stato quando viene eseguita e poi termina. Se ti serve una bacheca di stato aggiornata, la tua applicazione deve eseguire un altro controllo e conservare il nuovo orario di raccolta.

No. Zero è un valore numerico, mentre null indica che la misura manca. Tieni separati i due casi e aspettati che le misure della stanza siano vuote nei record offline.

Ogni stato restituito costa 0,5 crediti, compresi i risultati offline riusciti, senza costo di base. Per esempio, tre nomi utente distinti stimano 1,5 crediti e tre stati restituiti costano 1,5 crediti anche se due account sono offline.