API para obter detalhes do usuário

Você precisa puxar o perfil de um usuário do TikTok e as estatísticas de seguidores para o seu aplicativo sem construir um scraper ou reverter cabeçalhos. Ao final deste guia, você fará uma consulta a um endpoint real que retorna metadados do usuário (seguidores, seguindo, campos de perfil) pelo nome de usuário, e você saberá como encadeá-lo para buscar seu conteúdo para fluxos de trabalho de gerenciamento de usuários, como painéis de perfil e filas de moderação.

O que esta API faz e quando usá-la

A API de Mídia Pública do TikTok expõe endpoints somente leitura para trabalhar com dados públicos de usuários do TikTok. A principal capacidade de gerenciamento de usuários é recuperar o perfil detalhado de um usuário pelo seu nome de usuário, que inclui contagens de seguidores e seguindo, campos de perfil e IDs que você pode usar para chamadas subsequentes. Aplicações típicas incluem:

Ilustração: API para obter detalhes do usuário

Construir um painel de perfil de usuário mostrando tendências de seguidores e estatísticas básicas.
Verificar uma conexão de conta do TikTok procurando um nome de usuário e confirmando os metadados esperados.
Semear o fluxo de conteúdo de um usuário resolvendo seus identificadores imutáveis (por exemplo, secUid) para buscar seus vídeos.

Todos os endpoints estão disponíveis no Zyla API Hub sob a API de Mídia Pública do TikTok, e você pode explorar mais de 10.000 APIs públicas no Zyla API Hub com uma conta, uma chave de API e um modelo de assinatura + cota.

Começando no Zyla API Hub

Abra a página de listagem da API no Zyla API Hub e selecione Inscrever-se ou Iniciar teste de 7 dias quando disponível. A primeira API pode ser testada com um teste de 7 dias ou 50 solicitações. Não há plano gratuito; verifique a página da API para opções de acesso e preços atuais. Após se inscrever, você receberá uma chave de API.

Autenticação: passe sua chave usando o cabeçalho Authorization: Bearer YOUR_API_KEY
Padrão de chamada base: use os URLs de endpoint exatos documentados abaixo em zylalabs.com
Faturamento: assinatura + cota (não pago por chamada)

Endpoints que você usará para gerenciamento de usuários

1) Obter Detalhes do Usuário

Recupere informações detalhadas do perfil de um usuário do TikTok usando seu nome de usuário. Isso retorna metadados do usuário, como contagem de seguidores, contagem de seguindo e detalhes do perfil.

Método: GET
URL: https://zylalabs.com/api/12389/tiktok-public-media-api/23413/get-user-detail
Parâmetro de solicitação obrigatório:
- username (string): o identificador do TikTok, por exemplo: _ttqueen

Exemplo oficial de cURL (copiar/colar):

curl -s -X GET "https://zylalabs.com/api/12389/tiktok-public-media-api/23413/get-user-detail?username=_ttqueen" \
-H "Authorization: Bearer YOUR_API_KEY"

Resposta JSON oficial:

{
"data": {
"id": "6644110999556227073",
"nickname": "Quynh Truong",
"signature": "Thấy mình đáng iu thì fl mình nhé hehee
💬For work: 097.136.3242",
"hdAvatarUrlList": [
"https://p16-common-sign.tiktokcdn-eu.com/tos-alisg-avt-0068/dcb917fff48aacab462620b08f13b4e0~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=10399&refresh_token=c1870c0f&x-expires=1790154000&x-signature=nO62jhA4bUQvXuz5YAr8WEwl6ns%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=no1a"
],
"uniqueId": "_ttqueen",
"secUid": "MS4wLjABAAAA6e26Ok_w7ReVcKXUIZoygasHXTl9ZPPvhmuTQz1GGRaMU5RLQk6-yftHzzfIfr9L",
"isVerified": false,
"statistics": {
"followerCount": 3100000,
"followingCount": 139,
"friendCount": 84,
"heartCount": 117100000,
"videoCount": 559,
"diggCount": 0
}
}
}

Anotações de campo que você realmente usará:

data.id: ID numérico do usuário (string). Use como uma chave estável em seu banco de dados.
data.uniqueId: o nome de usuário público que você pesquisou.
data.secUid: identificador único com escopo de segurança exigido por outros endpoints (por exemplo, buscando a lista de vídeos do usuário).
data.hdAvatarUrlList: lista de URLs de imagens de avatar para exibições de perfil.
data.statistics.*: followerCount, followingCount, heartCount, videoCount são essenciais para KPIs de perfil.
data.isVerified: flag booleano para exibições de badge e roteamento de moderação.

2) Obter lista de vídeos

Recupere uma lista de vídeos postados por um usuário do TikTok usando seu secUid. Retorna metadados de vídeo, incluindo IDs, descrições e estatísticas.

Método: GET
URL: https://zylalabs.com/api/12389/tiktok-public-media-api/23414/get-video-list
Parâmetro de solicitação obrigatório:
- secUid (string): use o valor exato retornado de Obter Detalhes do Usuário (data.secUid)

Anotações:

A resposta inclui um array data.awemeList. Cada item tem campos como id, url, descrição, createdAt (timestamp UNIX, segundos), contentType e detalhes do autor.
Use createdAt para ordenar o conteúdo cronologicamente. Timestamps são inteiros representando segundos desde a época UNIX; converta para seu fuso horário local em sua interface.

3) Obter Detalhes de Vídeo ou Foto

Recupere detalhes de vídeo do TikTok por ID ou URL, incluindo descrição, estatísticas, informações do autor e URLs de mídia.

Método: GET
URL: https://zylalabs.com/api/12389/tiktok-public-media-api/23415/get-video-or-photo-details
Parâmetro de solicitação obrigatório:
- idOrUrl (string): passe uma URL ou ID de vídeo do TikTok

Anotações:

Use isso para enriquecer a página de detalhes do conteúdo de um usuário quando um item for selecionado na visualização da lista.
A resposta inclui campos de autor e links de mídia que são adequados para visualizar conteúdo em painéis de moderação ou administração.

Fluxo de ponta a ponta para um painel de gerenciamento de usuários

Resolva o usuário pelo nome de usuário usando Obter Detalhes do Usuário.
Armazene identificadores (id, uniqueId, secUid) juntamente com estatísticas para seu registro de usuário.
Quando necessário, busque seu conteúdo usando Obter lista de vídeos com o secUid retornado.
Para um post selecionado, chame Obter Detalhes de Vídeo ou Foto com sua URL ou ID para renderizar uma visualização de detalhes.

Isso espelha como a maioria dos painéis de produção mantém um registro canônico de usuários chaveado por id e secUid, atualizando periodicamente as estatísticas enquanto busca conteúdo sob demanda para controlar latência e custos.

Detalhes de implementação prática que economizam tempo

Autenticação: Cada solicitação deve incluir Authorization: Bearer YOUR_API_KEY.
Timestamps: campos createdAt retornados pelos endpoints de conteúdo são segundos da época UNIX (UTC). Converta de acordo com a política de fuso horário do seu produto.
Cache: Armazene em cache as respostas de Obter Detalhes do Usuário (por exemplo, 5–15 minutos) se você consultar contagens de seguidores para muitos perfis. Isso reduz solicitações duplicadas e suaviza cargas na interface.
Identificadores: secUid é necessário para busca de conteúdo. Persista-o imediatamente após sua primeira pesquisa para evitar uma chamada extra mais tarde.
Cotas: O acesso é por assinatura + cota. A primeira API pode ser testada com um teste de 7 dias ou 50 solicitações. Monitore o uso em seu painel Zyla.

Exemplo em Python: resolver um usuário e exibir estatísticas de perfil

Este exemplo chama Obter Detalhes do Usuário, extrai campos principais de gerenciamento de usuários e imprime um resumo compacto do perfil. Substitua YOUR_API_KEY pela sua chave.

import os
import requests

API_KEY = os.getenv("ZYLA_API_KEY", "YOUR_API_KEY")
USERNAME = "_ttqueen"

url = "https://zylalabs.com/api/12389/tiktok-public-media-api/23413/get-user-detail"
params = {"username": USERNAME}
headers = {"Authorization": f"Bearer {API_KEY}"}

resp = requests.get(url, params=params, headers=headers, timeout=20)
resp.raise_for_status()
data = resp.json().get("data", {})

user_id = data.get("id")
unique_id = data.get("uniqueId")
sec_uid = data.get("secUid")
nickname = data.get("nickname")
avatar_urls = data.get("hdAvatarUrlList", [])
stats = data.get("statistics", {}) or {}

summary = {
"id": user_id,
"username": unique_id,
"nickname": nickname,
"followers": stats.get("followerCount"),
"following": stats.get("followingCount"),
"videos": stats.get("videoCount"),
"hearts": stats.get("heartCount"),
"verified": data.get("isVerified"),
"secUid": sec_uid,
"avatar": avatar_urls[0] if avatar_urls else None
}

print(summary)

A partir daqui, você pode persistir id e secUid para chamadas de conteúdo a jusante e exibir summary["avatar"] no cabeçalho do perfil da sua interface.

Tratamento de erros e dicas operacionais

Orçamento de tentativas: Falhas de rede acontecem. Use uma pequena política de tentativas com retrocesso exponencial para GETs idempotentes (por exemplo, 2–3 tentativas).
Validação de entrada: Passe apenas os parâmetros documentados. Para pesquisas de usuários, certifique-se de que a string do nome de usuário corresponda ao formato esperado do identificador do TikTok que você coleta dos usuários.
Dados parciais: Arrays como hdAvatarUrlList podem estar vazios; proteja-se contra campos ausentes, como mostrado no exemplo.
Agendamento: Se você atualizar periodicamente as estatísticas de seguidores, espalhe as solicitações para evitar picos e para permanecer dentro da cota.

Casos de uso de gerenciamento de usuários no mundo real

Resolução de identidade: Quando um usuário conecta seu TikTok em seu produto, chame Obter Detalhes do Usuário pelo nome de usuário para verificar a propriedade (exiba o apelido, avatar, contagem de seguidores para confirmação).
Perfis de administrador: Construa páginas internas que mostrem a identidade do usuário (id, uniqueId, nickname), um badge de verificação e estatísticas resumidas (seguidores, corações, vídeos) para revisões rápidas.
Instantâneas de crescimento: Persista agregados diários das estatísticas para rastrear mudanças em followerCount e videoCount ao longo do tempo.
Filas de moderação: Combine Obter lista de vídeos com o secUid de Obter Detalhes do Usuário para pré-carregar conteúdo recente em uma fila de revisão.

Chamando a API de um agente de IA via MCP

Se você orquestra tarefas com um cliente compatível com MCP (Claude Code, Cursor, Windsurf), pode chamar as APIs Zyla através do endpoint MCP. O mesmo cabeçalho de Autorização se aplica; seu cliente gerencia a invocação da ferramenta.

Endpoint MCP: MCP (anexe sua apikey como um parâmetro de consulta quando sua ferramenta exigir: apikey=YOUR_API_KEY)
Use os URLs de hub exatos mostrados acima para ferramentas que aceitam chamadas HTTP diretas, com o cabeçalho de Autorização definido.

Isso permite que um agente recupere detalhes do usuário pelo nome de usuário, extraia secUid e, em seguida, busque vídeos, tudo dentro de uma sessão de codificação ou automação sem sair do seu editor.

Lista de verificação de integração

Inscreva-se no Zyla e obtenha sua chave de API.
Implemente Obter Detalhes do Usuário pelo nome de usuário; persista id e secUid.
Renderize o perfil: nickname, avatar (primeiro item em hdAvatarUrlList), badge isVerified, estatísticas.
Adicione um trabalho ou chamada sob demanda para buscar os vídeos do usuário usando secUid quando necessário.
Envolva solicitações com tentativas e cache mínimo (por exemplo, 5–15 minutos) para estatísticas de perfil.
Monitore a cota em seu painel Zyla e ajuste a frequência de polling de acordo.

FAQ

Q: Qual cabeçalho é necessário para autenticação?
A: Use Authorization: Bearer YOUR_API_KEY em cada solicitação.

Q: Como busco os vídeos de um usuário depois de procurá-los pelo nome de usuário?
A: Chame Obter Detalhes do Usuário para obter data.secUid, em seguida, passe esse secUid para o endpoint Obter lista de vídeos.

Q: Em que fuso horário estão os timestamps createdAt?
A: Os valores createdAt são segundos da época UNIX (UTC). Converta para o fuso horário desejado em sua interface.

Q: O preço é pago por chamada?
A: Não. A Zyla usa um modelo de assinatura + cota. A primeira API pode ser testada com um teste de 7 dias ou 50 solicitações. Verifique a página da API para opções de acesso e preços atuais.

Q: Posso usar isso em um agente de codificação de IA?
A: Sim. Chame os mesmos endpoints do hub através do endpoint MCP da Zyla com sua chave de API; clientes compatíveis com MCP podem invocar as ferramentas diretamente.

Pronto para integrar isso ao seu aplicativo? Comece com a listagem oficial, pegue sua chave e faça sua primeira solicitação agora: Iniciar teste de 7 dias na API de Mídia Pública do TikTok. Explore mais APIs a qualquer momento no Zyla API Hub.