Listar os vídeos de uma conta TikTok através da API
A API for Business do TikTok lista as publicações públicas de uma conta com GET /business/video/list/, a partir da mais recente, até 20 por página. Indique os campos a devolver, como item_id, caption, share_url e video_views, e percorra as páginas com cursor enquanto has_more for verdadeiro. filters.video_ids seleciona publicações específicas, e cada item_id é o ID que as chamadas de comentários usam.
A easyCoexistence lista as publicações recentes de uma conta TikTok com list_social_posts através do Claude, do ChatGPT ou do seu próprio código, com o item_id, a legenda, a ligação e as contagens de cada publicação, e get_social_credentials dá ao seu próprio código o token para as páginas seguintes e outros campos.
O número máximo de publicações que /business/video/list/ devolve por página; max_count assume 10 por predefinição.
Unidade do cursor: um timestamp Unix em UTC; o endpoint devolve as publicações publicadas antes desse momento.
O campo predefinido, que um pedido com vários campos deve incluir, sob pena de ocorrer um erro.
Chamadas permitidas por conta autorizada neste endpoint, tal como em cada endpoint da Accounts API.
O que devolve o endpoint?
As publicações públicas da conta: vídeos apresentados no seu perfil, publicações de fotografia e texto, e vídeos Only show in ads, que correm como anúncios sem aparecer no perfil. media_type distingue VIDEO de PHOTO, que abrange as publicações de fotografia e texto. As publicações que o TikTok filtrou por violações, como direitos de autor de música, ficam de fora da lista.
Como se faz o pedido?
Com GET e parâmetros no URL: business_id, fields como um array JSON e, opcionalmente, filters, cursor e max_count, que assume 10 por predefinição. O token vai no cabeçalho Access-Token, e a aplicação de programador precisa da permissão Get Account Media em TikTok Accounts:
curl -G 'https://business-api.tiktok.com/open_api/v1.3/business/video/list/' \
-H 'Access-Token: <ACCESS_TOKEN>' \
--data-urlencode 'business_id=<OPEN_ID>' \
--data-urlencode 'fields=["item_id","create_time","media_type","caption","share_url","thumbnail_url","video_views","likes","comments","shares"]' \
--data-urlencode 'max_count=20'Que campos descrevem uma publicação?
Para além das métricas, que vão de video_views a impression_sources, a lista inclui estes campos, todos sob o âmbito video.list:
item_id: o ID da publicação, usado pelas chamadas de comentários e por filters.video_ids.media_type: VIDEO, ou PHOTO para uma publicação de fotografia ou texto.is_ad: indica se a publicação está a ser usada num anúncio.create_time: a data de publicação, em segundos Unix em UTC.- caption: a legenda da publicação, com as hashtags incluídas.
share_url: uma ligação partilhável, que se comporta de forma diferente no telemóvel e no computador.embed_url: uma ligação de leitor para outros sites, que não reproduz publicações definidas como Amigos ou Apenas eu.thumbnail_url: uma imagem de pré-visualização temporária, cuja validade está no parâmetro x-expires.video_duration: a duração em segundos, com três casas decimais.
Como é uma página de resultados?
Um array videos pela ordem devolvida pelo TikTok, mais cursor, o valor a enviar para a página seguinte, e has_more, que indica se existe uma. create_time chega como uma cadeia de segundos Unix. Exemplo do TikTok, reduzido aos campos descritivos e às contagens:
{
"code": 0,
"message": "OK",
"request_id": "2021080307532501024502410704A7306F",
"data": {
"videos": [
{
"item_id": "6990565363377392901",
"create_time": "1627617835",
"caption": "little coco",
"share_url": "https://www.tiktok.com/@feather_in_the_w1nd/video/6990565363377392901?utm_campaign=tt4d_open_api&utm_source=6979330045630218242",
"likes": 10,
"comments": 2,
"shares": 0,
"video_views": 1231
}
],
"cursor": 0,
"has_more": false
}
}Como funciona a paginação?
Pelo tempo. cursor assume por predefinição o momento atual em milissegundos, pelo que a primeira página contém as publicações mais recentes, e cada resposta devolve o cursor para o pedido seguinte. Envie-o enquanto has_more for verdadeiro. Um timestamp personalizado lista as publicações publicadas antes desse momento, e as regras de confiança e segurança do TikTok podem tornar uma página mais curta do que max_count mesmo quando ainda há publicações.
import json, requests
API = "https://business-api.tiktok.com/open_api/v1.3"
def all_posts(token: str, business_id: str, fields: list[str]):
params = {"business_id": business_id, "fields": json.dumps(fields), "max_count": 20}
while True:
r = requests.get(f"{API}/business/video/list/", headers={"Access-Token": token},
params=params, timeout=30).json()
if r["code"] != 0:
raise RuntimeError(f"{r['code']}: {r['message']}")
yield from r["data"].get("videos", [])
if not r["data"].get("has_more"):
return
params["cursor"] = r["data"]["cursor"]Como se obtêm publicações específicas?
Com filters, um objeto JSON: video_ids lista os IDs de publicação a devolver, como os post_ids de um estado de publicação. ad_post_only, válido apenas junto de video_ids, mantém só as publicações autorizadas para anunciantes nos Spark Ads. Um pedido filtrado recebe os mesmos campos que qualquer outro, pelo que uma chamada pode devolver os números mais recentes de algumas publicações conhecidas.
filters={"video_ids":["6995316737801538821","8015388216995316737"]}Que limites se aplicam?
A Accounts API permite 40 chamadas por minuto para cada conta autorizada neste endpoint, e as chamadas à Accounts API de uma aplicação somam 600 por minuto no nível Basic e 1000 acima dele. Os campos descritivos são em tempo real, as contagens costumam atrasar 24 a 48 horas, e os dados de uma publicação deixam de ser atualizados 365 dias depois de publicada.
Como é que a easyCoexistence lista os vídeos?
Com list_social_posts, que recebe o account_id e um limit opcional, de 1 a 20 para o TikTok. Devolve a primeira página do TikTok: as publicações mais recentes com item_id, create_time, caption, share_url, thumbnail_url, video_views, likes, comments e shares, mais cursor e has_more. As páginas seguintes e os outros campos vêm do seu próprio código, com o token e o business_id de get_social_credentials:
GET https://business-api.tiktok.com/open_api/v1.3/business/video/list/
?business_id=<BUSINESS_ID>
&fields=["item_id","media_type","caption","embed_url"]
&cursor=1793404800000
&max_count=20
Access-Token: <ACCESS_TOKEN>Erros comuns
- Pedir campos sem item_id. A referência do TikTok avisa que um pedido com vários campos sem ele pode falhar.
- Parar quando uma página vem com menos publicações. O TikTok pode devolver menos do que max_count mesmo com has_more ainda verdadeiro; siga antes has_more.
- Guardar thumbnail_url para mais tarde. É uma ligação temporária que expira à hora indicada no parâmetro x-expires, por isso obtenha uma nova quando for preciso.
- Procurar publicações privadas na lista. O endpoint devolve apenas publicações públicas.
De US$ 9 a US$ 0,75 por ligação por mês, descendo à medida que acrescenta ligações, com os primeiros 3 dias grátis.
Perguntas frequentes
Quantos vídeos do TikTok a API consegue listar de uma vez?
Até 20 por página em /business/video/list/. max_count define o tamanho da página e assume 10 por predefinição; siga o cursor para obter mais.
A API do TikTok lista também as publicações de fotografia?
Sim. /business/video/list/ devolve publicações públicas de vídeo, fotografia e texto, e media_type distingue VIDEO de PHOTO.
A lista de vídeos do TikTok inclui publicações só para anúncios?
Sim. /business/video/list/ devolve também os vídeos Only show in ads, que correm como anúncios sem aparecer no perfil, e is_ad indica se uma publicação está a ser usada num anúncio.
Porque falta uma publicação do TikTok na lista da API?
O endpoint lista apenas publicações públicas, e o TikTok deixa de fora as publicações filtradas por violações, como direitos de autor de música.
Continue a ler
Ligue o seu primeiro canal em dois minutos.
Sem revisões de plataformas para esperar. Ligue o WhatsApp, o Instagram, o TikTok ou outro canal, peça depois à sua IA que publique, responda ou faça um relatório, e veja-a trabalhar.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorizado 24/7
Verificado em