API para obtener detalles del usuario

Necesitas obtener el perfil y las estadísticas de seguidores de un usuario de TikTok en tu aplicación sin construir un scraper o hacer ingeniería inversa de los encabezados. Al final de esta guía, consultarás un endpoint real que devuelve metadatos del usuario (seguidores, seguidos, campos de perfil) por nombre de usuario, y sabrás cómo encadenarlo para obtener su contenido para flujos de trabajo de gestión de usuarios como paneles de perfil y colas de moderación.

Qué hace esta API y cuándo usarla

La API de Medios Públicos de TikTok expone endpoints de solo lectura para trabajar con datos públicos de usuarios de TikTok. La capacidad clave de gestión de usuarios es recuperar el perfil detallado de un usuario por su nombre de usuario, que incluye conteos de seguidores y seguidos, campos de perfil e IDs que puedes usar para llamadas posteriores. Las aplicaciones típicas incluyen:

Ilustración: API para obtener detalles del usuario

Construir un panel de perfil de usuario que muestre tendencias de seguidores y estadísticas básicas.
Verificar una conexión de cuenta de TikTok buscando un nombre de usuario y confirmando los metadatos esperados.
Sembrar el flujo de contenido de un usuario resolviendo sus identificadores inmutables (por ejemplo, secUid) para obtener sus videos.

Todos los endpoints están disponibles en Zyla API Hub bajo la API de Medios Públicos de TikTok, y puedes explorar más de 10,000 APIs públicas en Zyla API Hub con una cuenta, una clave API y un modelo de suscripción + cuota.

Comenzando en Zyla API Hub

Abre la página de listado de la API en Zyla API Hub y selecciona Suscribirse o Comenzar prueba de 7 días cuando esté disponible. La primera API se puede probar con una prueba de 7 días o 50 solicitudes. No hay un plan gratuito; consulta la página de la API para opciones de acceso y precios actuales. Después de suscribirte, recibirás una clave API.

Autenticación: pasa tu clave usando el encabezado Authorization: Bearer YOUR_API_KEY
Patrón de llamada base: usa las URLs de endpoint exactas documentadas a continuación en zylalabs.com
Facturación: suscripción + cuota (no pago por llamada)

Endpoints que usarás para la gestión de usuarios

1) Obtener detalles del usuario

Recupera información detallada del perfil de un usuario de TikTok usando su nombre de usuario. Esto devuelve metadatos del usuario como conteo de seguidores, conteo de seguidos y detalles del perfil.

Método: GET
URL: https://zylalabs.com/api/12389/tiktok-public-media-api/23413/get-user-detail
Parámetro de solicitud requerido:
- username (string): el identificador de TikTok, por ejemplo: _ttqueen

Ejemplo oficial de cURL (copia/pega):

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"

Respuesta 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
}
}
}

Notas de campo que realmente usarás:

data.id: ID de usuario numérico (string). Úsalo como una clave estable en tu base de datos.
data.uniqueId: el nombre de usuario público que buscaste.
data.secUid: identificador único con alcance de seguridad requerido por otros endpoints (por ejemplo, obtener la lista de videos del usuario).
data.hdAvatarUrlList: lista de URLs de imágenes de avatar para mostrar en el perfil.
data.statistics.*: followerCount, followingCount, heartCount, videoCount son esenciales para los KPI del perfil.
data.isVerified: bandera boolean para mostrar insignias y enrutamiento de moderación.

2) Obtener lista de videos

Recupera una lista de videos publicados por un usuario de TikTok usando su secUid. Devuelve metadatos de video incluyendo IDs, descripciones y estadísticas.

Método: GET
URL: https://zylalabs.com/api/12389/tiktok-public-media-api/23414/get-video-list
Parámetro de solicitud requerido:
- secUid (string): usa el valor exacto devuelto de Obtener Detalles del Usuario (data.secUid)

Notas:

La respuesta incluye un array data.awemeList. Cada elemento tiene campos como id, url, descripción, createdAt (timestamp UNIX, segundos), contentType y detalles del autor.
Usa createdAt para ordenar el contenido cronológicamente. Los timestamps son enteros que representan segundos desde la época UNIX; conviértelos a tu zona horaria local en tu UI.

3) Obtener detalles de video o foto

Recupera detalles de video de TikTok por ID o URL, incluyendo descripción, estadísticas, información del autor y URLs de medios.

Método: GET
URL: https://zylalabs.com/api/12389/tiktok-public-media-api/23415/get-video-or-photo-details
Parámetro de solicitud requerido:
- idOrUrl (string): pasa una URL o ID de video de TikTok

Notas:

Usa esto para enriquecer la página de detalles del contenido de un usuario cuando se selecciona un elemento de la vista de lista.
La respuesta incluye campos de autor y enlaces de medios que son adecuados para previsualizar contenido en paneles de moderación o administración.

Flujo de extremo a extremo para un panel de gestión de usuarios

Resuelve el usuario por nombre de usuario usando Obtener Detalles del Usuario.
Almacena identificadores (id, uniqueId, secUid) junto con estadísticas para tu registro de usuario.
Cuando sea necesario, obtén su contenido usando Obtener lista de videos con el secUid devuelto.
Para una publicación seleccionada, llama a Obtener Detalles de Video o Foto con su URL o ID para renderizar una vista de detalles.

Esto refleja cómo la mayoría de los paneles de producción mantienen un registro canónico de usuario claveado por id y secUid, actualizando periódicamente las estadísticas mientras obtienen contenido bajo demanda para controlar la latencia y los costos.

Detalles de implementación práctica que ahorran tiempo

Autenticación: Cada solicitud debe incluir Authorization: Bearer YOUR_API_KEY.
Timestamps: los campos createdAt devueltos por los endpoints de contenido son segundos de época UNIX (UTC). Conviértelos de acuerdo con la política de zona horaria de tu producto.
Cacheo: Almacena en caché las respuestas de Obtener Detalles del Usuario (por ejemplo, 5–15 minutos) si consultas conteos de seguidores para muchos perfiles. Esto reduce solicitudes duplicadas y suaviza las cargas de UI.
Identificadores: secUid es necesario para la obtención de contenido. Persistelo inmediatamente después de tu primera búsqueda para evitar una llamada extra más tarde.
Cuotas: El acceso es por suscripción + cuota. La primera API se puede probar con una prueba de 7 días o 50 solicitudes. Monitorea el uso en tu panel de Zyla.

Ejemplo en Python: resolver un usuario y mostrar estadísticas de perfil

Este ejemplo llama a Obtener Detalles del Usuario, extrae campos clave de gestión de usuarios y imprime un resumen compacto del perfil. Reemplaza YOUR_API_KEY con tu clave.

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 de aquí, puedes persistir id y secUid para llamadas de contenido posteriores, y mostrar summary["avatar"] en el encabezado del perfil de tu UI.

Manejo de errores y consejos operativos

Presupuesto de reintentos: Los problemas de red ocurren. Usa una pequeña política de reintentos con retroceso exponencial para GETs idempotentes (por ejemplo, 2–3 reintentos).
Validación de entrada: Solo pasa los parámetros documentados. Para búsquedas de usuarios, asegúrate de que la cadena de nombre de usuario coincida con el formato de identificador de TikTok esperado que recolectas de los usuarios.
Datos parciales: Arrays como hdAvatarUrlList pueden estar vacíos; protege los campos faltantes como se muestra en el ejemplo.
Programación: Si actualizas periódicamente las estadísticas de seguidores, escalona las solicitudes para evitar picos y mantenerte dentro de la cuota.

Casos de uso de gestión de usuarios en el mundo real

Resolución de identidad: Cuando un usuario conecta su TikTok en tu producto, llama a Obtener Detalles del Usuario por nombre de usuario para verificar la propiedad (muestra el apodo, avatar, conteo de seguidores para confirmación).
Perfiles de administrador: Construye páginas internas que muestren la identidad del usuario (id, uniqueId, nickname), una insignia de verificación y estadísticas resumidas (seguidores, corazones, videos) para revisiones rápidas.
Instantáneas de crecimiento: Persiste agregados diarios de estadísticas para rastrear cambios en followerCount y videoCount a lo largo del tiempo.
Colas de moderación: Combina Obtener lista de videos con el secUid de Obtener Detalles del Usuario para prefetch contenido reciente en una cola de revisión.

Llamando a la API desde un agente de IA a través de MCP

Si orquestas tareas con un cliente compatible con MCP (Claude Code, Cursor, Windsurf), puedes llamar a las APIs de Zyla a través del endpoint MCP. El mismo encabezado de Autorización se aplica; tu cliente maneja la invocación de herramientas.

Endpoint MCP: MCP (agrega tu apikey como un parámetro de consulta cuando tu herramienta lo requiera: apikey=YOUR_API_KEY)
Usa las URLs de hub exactas mostradas arriba para herramientas que acepten llamadas HTTP directas, con el encabezado de Autorización configurado.

Esto permite que un agente recupere detalles de usuario por nombre de usuario, extraiga secUid y luego obtenga videos, todo dentro de una sesión de codificación o automatización sin salir de tu editor.

Lista de verificación de integración

Suscríbete en Zyla y obtén tu clave API.
Implementa Obtener Detalles del Usuario por nombre de usuario; persiste id y secUid.
Renderiza el perfil: apodo, avatar (primer elemento en hdAvatarUrlList), insignia isVerified, estadísticas.
Agrega un trabajo o llamada bajo demanda para obtener los videos del usuario usando secUid cuando sea necesario.
Envuelve las solicitudes con reintentos y cacheo mínimo (por ejemplo, 5–15 minutos) para estadísticas de perfil.
Monitorea la cuota en tu panel de Zyla y ajusta la frecuencia de sondeo en consecuencia.

FAQ

Q: ¿Qué encabezado es requerido para la autenticación?
A: Usa Authorization: Bearer YOUR_API_KEY en cada solicitud.

Q: ¿Cómo obtengo los videos de un usuario después de buscarlos por nombre de usuario?
A: Llama a Obtener Detalles del Usuario para obtener data.secUid, luego pasa ese secUid al endpoint Obtener lista de videos.

Q: ¿En qué zona horaria están los timestamps createdAt?
A: Los valores createdAt son segundos de época UNIX (UTC). Conviértelos a tu zona horaria deseada en tu UI.

Q: ¿El precio es por llamada?
A: No. Zyla utiliza un modelo de suscripción + cuota. La primera API se puede probar con una prueba de 7 días o 50 solicitudes. Consulta la página de la API para opciones de acceso y precios actuales.

Q: ¿Puedo usar esto en un agente de codificación de IA?
A: Sí. Llama a los mismos endpoints del hub a través del endpoint MCP de Zyla con tu clave API; los clientes compatibles con MCP pueden invocar las herramientas directamente.

¿Listo para integrar esto en tu aplicación? Comienza con el listado oficial, obtén tu clave y haz tu primera solicitud ahora: Comienza la prueba de 7 días en la API de Medios Públicos de TikTok. Explora más APIs en cualquier momento en Zyla API Hub.