Como Rastrar publicações e métricas de vídeo do TikTok com Python

TL;DR:

• Um scraper de vídeos do TikTok começa com uma conta pública conhecida. Resolva o nome de usuário com scraper.tiktok.user.detail, depois passe seu sec_uid para scraper.tiktok.user.work.
• A resposta dos posts é uma amostra delimitada. A solicitação documentada aceita cursor e count, mas uma resposta não deve ser descrita como o histórico completo de posts de um criador.
• Métricas de posts públicos precisam de contexto. Armazene o tempo de coleta ao lado das contagens de visualizações, curtidas, comentários, compartilhamentos, coletas e repostagens, porque esses valores podem mudar.
• Posts de fotos e campos opcionais precisam de análise tolerante. Um item válido pode ter campos de mídia ou legenda em branco, e o tipo de post deve vir do registro retornado em vez de uma suposição.
• Exportações estáveis mantêm identificadores como strings. Preserve o JSON bruto e escreva um CSV normalizado para análise.
• Gratuito para começar. Novas contas Scrapeless incluem crédito grátis; crie uma conta no painel do Scrapeless.

Introdução: uma lista de posts é uma amostra com marca temporal

O feed público de um criador mistura identificadores, legendas, metadados de mídia, hashtags, músicas e contagens de engajamento cumulativo. Transformar esse feed em uma tabela útil requer duas chamadas de API e uma pequena quantidade de normalização cuidadosa.

Este guia constrói um scraper de vídeos do TikTok para uma conta conhecida. Ele resolve o sec_uid da conta, solicita um conjunto delimitado de posts públicos e escreve uma linha CSV por item. O fluxo de trabalho não rotula a primeira resposta como um arquivo completo e não trata as contagens de visualizações públicas como alcance único.

Para um mapa dos atores disponíveis de perfil, post e Shop, leia o guia da API do Scraper do TikTok.

O que Você Pode Coletar de uma Conta Conhecida

O ator scraper.tiktok.user.work retorna um array items para um sec_uid fornecido. Um item de post pode conter seu ID e URL, descrição, texto do adesivo, hora de criação, contagens de engajamento público, detalhes da mídia, hashtags, idioma, sinalizadores de fixação e anúncios, música, legendas, permissões e contexto de perfil.

Essa estrutura suporta várias saídas práticas:

• Um inventário de posts para uma conta pública selecionada
• Uma tabela de descrições, hashtags, datas e URLs de posts
• Um instantâneo de engajamento em um ponto no tempo
• Uma fila de revisão para posts fixados, promocionais ou relacionados ao comércio eletrônico
• Uma tabela de entrada limpa para posterior classificação de conteúdo

O ator não documenta texto de comentários, demografia da audiência, listas de seguidores, visualizadores únicos, conversões ou atribuição de receita. Esses campos não devem aparecer na saída normalizada como substitutos inferidos.

Por que Usar uma API de Scraper do TikTok

Um ator gerenciado retorna JSON estruturado de uma solicitação HTTP estável. O chamador trabalha com campos nomeados em vez de manter seletores para uma página renderizada, lidando com layouts específicos de mídia ou traduzindo cada alteração visual em atualizações do analisador.

A solicitação ainda precisa de um escopo claro. Um scraper de posts do TikTok deve começar com uma conta selecionada pelo usuário, registrar quando a amostra foi coletada e reter contexto suficiente para auditar cada linha. A troca HTTP segue as semânticas definidas por RFC 9110, enquanto a documentação JSON do Python descreve a serialização usada abaixo.

Pré-requisitos

• Uma conta Scrapeless e token de API do Painel do Scrapeless
• Python 3 com sua biblioteca padrão
• O nome de usuário público da conta a ser inspecionada
• Um propósito permitido, um tamanho de amostra definido e uma política de retenção
• Um token de API ativo para os blocos de código abaixo; exporte-o como SCRAPELESS_API_KEY

Os exemplos estão marcados como uma lacuna de pré-requisito porque nenhum token de API está incorporado neste artigo. Eles são caminhos de solicitação completos, mas os leitores devem fornecer sua própria credencial e nome de usuário de destino.

Como Funciona o Scraper de Posts do TikTok

O fluxo de trabalho usa um endpoint e dois atores:

POST https://api.scrapeless.com/api/v1/scraper/request

1. Envie unique_id para scraper.tiktok.user.detail.
2. Leia sec_uid da resposta do perfil.
3. Envie esse valor para scraper.tiktok.user.work com um count delimitado.
4. Normalize o items retornado sem inventar campos ausentes.

A documentação oficial de desenvolvedor do TikTok também separa a listagem de vídeos autorizados pela conta em uma operação de lista de vídeos dedicada, que é um lembrete útil de que a resolução de identidade e a recuperação de conteúdo são etapas distintas. Veja a documentação de Lista de Vídeos do TikTok para essa interface de primeira parte.

Parâmetros de Solicitação

O ator de perfil requer unique_id, escrito sem o @ à frente. Sua resposta pode incluir account_id, unique_id e sec_uid junto com campos públicos de perfil e estatísticas.

O ator de posts requer sec_uid. Ele também aceita cursor como uma string e count como um número inteiro positivo. Os padrões documentados são "0" e 35. A documentação confirma a entrada do cursor, mas a resposta exibida não estabelece um campo de continuidade universal ou uma garantia de histórico completo.

Captura Rápida Com curl

Essa primeira solicitação resolve o identificador da conta necessário pelo ator de posts.

Nota: O código abaixo requer um token da API Scrapeless ativo em SCRAPELESS_API_KEY e um nome de usuário público escolhido pelo leitor.

curl --request POST 'https://api.scrapeless.com/api/v1/scraper/request' \
  --header "x-api-token: ${SCRAPELESS_API_KEY}" \
  --header 'content-type: application/json' \
  --data '{
    "actor": "scraper.tiktok.user.detail",
    "input": {"unique_id": "tiktok"}
  }'

Copie o sec_uid retornado em uma solicitação scraper.tiktok.user.work, ou deixe que o programa Python realize ambas as chamadas.

Envelope de Resposta

A resposta dos posts contém um array items. Trate cada elemento como um registro de post público observado. Os seguintes grupos são úteis ao construir uma tabela:

Comece a Raspagem com Scrapeless

Potencialize seu fluxo de trabalho de raspagem da web e automação com Scrapeless!
Inscreva-se hoje e ganhe $5 em crédito gratuito — sem necessidade de cartão de crédito.

Reivindique seu crédito gratuito agora no Painel do Scrapeless.

Integrando a API em Python

O programa abaixo resolve o perfil, coleta até 20 itens do cursor documentado inicial, salva a resposta bruta e exporta uma tabela de métricas compacta. A documentação do módulo CSV do Python explica o escritor usado para o arquivo normalizado.

Nota: O código abaixo requer um token da API Scrapeless ativo em SCRAPELESS_API_KEY; a parte da solicitação não poderia ser executada sem essa credencial externa.

import csv
import json
import os
from datetime import datetime, timezone
from urllib.request import Request, urlopen

ENDPOINT = "https://api.scrapeless.com/api/v1/scraper/request"
TOKEN = os.environ["SCRAPELESS_API_KEY"]
USERNAME = os.environ.get("TIKTOK_USERNAME", "tiktok").lstrip("@")


def run_actor(actor, actor_input):
    payload = json.dumps({"actor": actor, "input": actor_input}).encode()
    request = Request(
        ENDPOINT,
        data=payload,
        headers={
            "x-api-token": TOKEN,
            "content-type": "application/json",
        },
        method="POST",
    )
    with urlopen(request, timeout=60) as response:
        return json.load(response)


profile = run_actor(
    "scraper.tiktok.user.detail",
    {"unique_id": USERNAME},
)

posts = run_actor(
    "scraper.tiktok.user.work",
    {"sec_uid": profile["sec_uid"], "cursor": "0", "count": 20},
)

collected_at = datetime.now(timezone.utc).isoformat()
items = posts.get("items") or []

with open("tiktok-posts-raw.json", "w", encoding="utf-8") as raw_file:
    json.dump(posts, raw_file, ensure_ascii=False, indent=2)

fieldnames = [
    "collected_at",
    "account_unique_id",
    "post_id",
    "post_url",
    "description",
    "created_at",
    "play_count",
    "like_count",
    "comment_count",
    "share_count",
    "collect_count",
    "repost_count",
    "is_pinned",
    "hashtags",
]

with open("tiktok-post-metrics.csv", "w", newline="", encoding="utf-8") as csv_file:
    writer = csv.DictWriter(csv_file, fieldnames=fieldnames)
    writer.writeheader()
    for item in items:
        writer.writerow({
            "collected_at": collected_at,
            "account_unique_id": profile.get("unique_id", USERNAME),
            "post_id": str(item.get("id") or item.get("post_id") or ""),
            "post_url": item.get("url") or item.get("post_url") or "",
            "description": item.get("description") or "",
            "created_at": item.get("create_time") or item.get("date") or "",
            "play_count": item.get("play_count"),
            "like_count": item.get("like_count"),
            "comment_count": item.get("comment_count"),
            "share_count": item.get("share_count"),
            "collect_count": item.get("collect_count"),
            "repost_count": item.get("repost_count"),
            "is_pinned": item.get("is_pinned"),
            "hashtags": "|".join(
                str(tag.get("name", tag)) if isinstance(tag, dict) else str(tag)
                for tag in (item.get("hashtags") or [])
            ),
        })

print(f"Saved {len(items)} sampled post records for @{USERNAME}")

Os nomes de campos de fallback no normalizador impedem que uma chave opcional faça a exportação falhar. Compare-os com a resposta do ator atual antes de corrigir um esquema de produção e mantenha o JSON bruto para que a transformação possa ser revisada mais tarde.

Interpretar Posts de Foto, Indicadores Fixados e Campos Vazios

Uma URL de vídeo em branco não prova que a coleta falhou. O TikTok suporta formatos de conteúdo além de um objeto de vídeo convencional, e campos de mídia, música ou legenda opcionais podem estar vazios em uma resposta válida. Baseie o rótulo de formato na estrutura retornada e mantenha um estado unknown quando a evidência estiver incompleta.

Um indicador fixado descreve a colocação no perfil no momento da coleta. Não estabelece quando o criador fixou o post, por que foi fixado ou se permaneceu fixado após o instantâneo.

A mesma disciplina se aplica às métricas públicas. Uma contagem de visualizações é um contador cumulativo da plataforma exposto com o post; não é uma contagem de pessoas únicas. Curtidas, comentários, compartilhamentos, coleções e repostagens descrevem interações visíveis, não atribuição de campanha.

Lidar com Cursor e Escopo de Amostra com Cuidado

A solicitação documentada aceita cursor, mas o exemplo de resposta disponível não confirma uma única regra de paginação que possa ser copiada para cada cliente. Use a primeira resposta como uma amostra limitada, a menos que a resposta ao vivo e a documentação atual forneçam um valor de continuação verificado.

Registre o cursor de solicitação, a contagem solicitada, a contagem de itens retornados e o tempo de coleta ao lado da saída. Esses quatro campos tornam o escopo visível. Eles também impedem que um painel transforme “20 posts observados” em “todos os posts” por meio de um total não rotulado.

Problemas Comuns a Prevenir

• Passar unique_id para o ator de posts. Resolva o perfil primeiro e use seu sec_uid.
• Converter IDs longos em números. Mantenha identificadores de conta e post como strings.
• Tratar o ausente como zero. Um campo métrico ou de mídia opcional em branco deve permanecer desconhecido até que seu significado seja estabelecido.
• Chamar a primeira resposta de um histórico completo. Rotule-a como uma amostra com seu cursor, contagem solicitada e tempo de coleta.
• Descartar a URL de origem. A URL do post fornece aos revisores um caminho direto de volta ao item público observado.
• Misturando contagens cumulativas com crescimento por intervalo. Uma única captura fornece níveis; capturas repetidas com carimbos de tempo são necessárias para deltas.

Scrapeless empacota o ator sob Scraping API. Revise a página de preços atual antes de definir um cronograma de coleta para produção.

Conclusão: preserve a amostra antes de analisá-la

Um scraper de vídeo TikTok confiável resolve uma conta conhecida, solicita uma amostra de postagens delimitadas e preserva a resposta antes de achatá-la. A saída útil é mais do que um CSV de métricas: inclui identificadores de string estáveis, URLs de origem, um carimbo de data/hora da coleção, JSON bruto e uma declaração honesta de escopo.

Pronto para Coletar Métricas de Postagens Públicas do TikTok?

Participe do Scrapeless Discord ou da comunidade do Telegram para comparar notas de implementação. Crie uma conta no Scrapeless Dashboard quando estiver pronto para testar o fluxo de trabalho.

FAQ

P: O que é um scraper de vídeo TikTok?

Um scraper de vídeo TikTok coleta campos de postagens públicas suportadas e os retorna em uma forma estruturada. O fluxo de trabalho neste guia usa um ator de perfil para resolver sec_uid e um ator de postagens para retornar uma amostra de items.

P: Um scraper de postagens do TikTok pode obter todas as postagens de uma conta?

Uma resposta de ator não deve ser descrita como todas as postagens. A documentação do pedido cursor e count, mas a cobertura completa depende de uma regra de continuidade verificada, do conteúdo público acessível da conta e da coleta bem-sucedida dentro do escopo pretendido.

P: Quais métricas de vídeo do TikTok estão disponíveis?

Os itens da postagem podem incluir contagens de reprodução pública, curtidas, comentários, compartilhamentos, coletas e repostagens. Estes são contadores em um ponto no tempo e não representam alcance único, vendas ou atribuição de campanhas.

P: Como os posts de foto devem ser tratados?

Posts de foto devem ser analisados a partir dos campos presentes no item retornado. Mantenha os campos de mídia anuláveis e evite declarar uma coleta falhada apenas porque um campo de vídeo convencional está vazio.

P: O fluxo de trabalho precisa de proxies ou um parser de navegador?

O ator gerenciado lida com sua superfície de coleta por trás da solicitação da API. O chamador fornece identificadores válidos, limita a amostra, valida a resposta e armazena o resultado de forma responsável.

P: É legal coletar postagens públicas do TikTok?

A legalidade depende da jurisdição, propósito, dados, método de acesso e termos aplicáveis. Colete apenas os campos públicos necessários para um uso permitido, minimize a retenção e busque aconselhamento legal para o projeto específico.