Come controllare lo stato di pubblicazione di un post TikTok tramite l'API
TikTok pubblica i post via API in modo asincrono: la chiamata di pubblicazione restituisce uno share_id, e GET /business/publish/status/ con quell'ID come publish_id indica a che punto si trova il post. Lo stato è PROCESSING_DOWNLOAD mentre TikTok scarica il file, PUBLISH_COMPLETE quando il post ha superato la moderazione ed è stato pubblicato, oppure FAILED con un motivo come frame_rate_check_failed.
easyCoexistence pubblica su TikTok con publish_tiktok_post e segue ogni post con get_tiktok_publish_status, da Claude, ChatGPT o dal tuo codice, così la tua AI vede lo stato di TikTok e l'eventuale motivo di errore così come sono.
Quanto possono volerci gli ID dei post dopo PUBLISH_COMPLETE; TikTok consiglia di riprovare dopo tre minuti se mancano.
La stima generale di TikTok per scaricare il file di un post da 1 GB; il tempo reale dipende dalle dimensioni e dalla rete.
L'attesa più lunga abituale, una volta completato il caricamento, perché un post diventi pubblico; la moderazione manuale può richiedere più tempo.
Timeout di download, oltre il quale TikTok fa fallire un post con video_pull_failed o photo_pull_failed.
Perché bisogna seguire un post TikTok?
Perché TikTok lo pubblica in background. La chiamata di pubblicazione avvia un'attività e restituisce subito uno share_id; poi TikTok scarica il file dal suo URL, controlla il formato, esegue la moderazione e rende pubblico il post. Un post può comunque fallire anche se la chiamata stessa è andata a buon fine.
Quali stati esistono?
GET /business/publish/status/ richiede il business_id dell'account e lo share_id come publish_id, e restituisce uno di quattro stati:
PROCESSING_DOWNLOAD: TikTok sta scaricando il contenuto dal suo URL.PUBLISH_COMPLETE: il post ha superato la moderazione ed è stato pubblicato;post_idslo elenca non appena è visibile pubblicamente.- FAILED: la pubblicazione si è interrotta, e reason ne spiega il motivo.
SEND_TO_USER_INBOX: una bozza è stata caricata e TikTok ha notificato l'inbox del creator; vale solo per le bozze.
Quanto dura la pubblicazione?
TikTok non indica un tempo fisso. Il download dipende dalle dimensioni del file e dalla rete; la stima generale di TikTok è che 30 minuti bastino per un file da 1 GB, con un'ora come limite. Dopo, un post di norma diventa pubblico entro 2 minuti, oppure più tardi se richiede la moderazione manuale, e il suo ID può impiegare fino a tre minuti in più per comparire nello stato.
Cosa significano i motivi di errore?
reason indica che cosa ha bloccato il post. Alcuni richiedono di modificare il file, altri indicano che un nuovo tentativo può funzionare:
file_format_check_failed,duration_check_failed,frame_rate_check_failed,picture_size_check_failed: il file viola una regola sul formato, e TikTok li segna come non recuperabili con un nuovo tentativo.video_pull_failed,photo_pull_failed: TikTok non è riuscito a scaricare il file, o non lo ha fatto entro l'ora; riprova quando l'URL è raggiungibile pubblicamente.- internal: una parte del servizio di TikTok non era disponibile, e un nuovo tentativo va bene.
spam_risk_too_many_posts,spam_risk,spam_risk_text: TikTok ha bloccato il post per volume, comportamento o contenuto della didascalia.auth_removed: l'account ha revocato l'accesso dell'app durante l'elaborazione, e TikTok dice di non riprovare.spam_risk_user_banned_from_posting: l'account è escluso dalla pubblicazione di nuovi post.
A cosa serve l'ID del post?
A ritrovare il post in seguito. Il riferimento di TikTok passa gli ID dei post a /business/video/list/ in filters.video_ids per leggerne le metriche. Le chiamate sui commenti, invece, prendono l'item_id di un post dalla lista video dell'account come video_id, che è anche ciò che gli strumenti di commento di easyCoexistence ricevono come post_id.
Come segue easyCoexistence un post?
publish_tiktok_post restituisce lo share_id di TikTok con una nota che TikTok sta elaborando il post, e get_tiktok_publish_status prende quello share_id e restituisce lo stato di TikTok così com'è in quel momento, con il motivo quando c'è. Chiedi alla tua AI di ricontrollare dopo qualche minuto, invece che subito.
Errori comuni
- Pubblicare di nuovo perché non è ancora comparso nulla. La prima chiamata ha solo avviato l'attività, quindi controlla lo stato prima di inviare di nuovo il post.
- Considerare PUBLISH_COMPLETE senza post_ids come un errore. Gli ID possono richiedere fino a tre minuti in più, quindi ricontrolla allora.
- Riprovare un errore di formato con lo stesso file. file_format_check_failed e gli altri controlli falliti richiedono un file corretto.
- Rendere irraggiungibile l'URL durante il download. TikTok fa fallire il post con video_pull_failed o photo_pull_failed quando non riesce a recuperare il file.
Da US$ 9 a US$ 0,75 per connessione al mese, con prezzo che scende man mano che aggiungi connessioni, e i primi 3 giorni di prova gratuita.
Domande frequenti
Cos'è uno share_id su TikTok?
L'ID di un'attività di pubblicazione, restituito dagli endpoint di pubblicazione di video e foto. Va nella chiamata di stato come publish_id.
C'è un webhook per lo stato di pubblicazione su TikTok?
Sì. Un'app iscritta con event_type VIDEO tramite /business/webhook/update/ riceve gli eventi di pubblicazione dei post di TikTok, come post.publish.failed con il suo reason e publish_id, al posto dei controlli di stato ripetuti.
Perché un post pubblicato non ha ancora un ID?
TikTok può impiegare fino a tre minuti dopo PUBLISH_COMPLETE per restituire post_ids, e li restituisce solo per i post visibili pubblicamente.
Un post TikTok fallito si può riprovare?
Dipende dal motivo. Gli errori di download e interni possono essere ritentati; gli errori su formato, durata, frequenza dei fotogrammi e dimensione dell'immagine richiedono un file corretto.
Continua a leggere
Collega il tuo primo canale in due minuti.
Nessuna revisione delle piattaforme da aspettare. Collega WhatsApp, Instagram, TikTok o un altro canale, poi chiedi alla tua AI di pubblicare, rispondere o fare un report, e guardala al lavoro.
- 3 giorni gratis
- Disdici quando vuoi
- Solo API ufficiali
- Monitorato 24/7
Verificato il