Una página pública de TikTok parece simple: un nombre de usuario, un video, un hilo de comentarios. El contrato de recopilación no lo es. Los perfiles no son un feed de videos. Los comentarios no son un árbol completo de respuestas. La búsqueda es solo de videos. La consulta de una sala en vivo no descubre transmisiones en vivo.
Este tutorial construye un flujo de datos públicos mantenible con las API de TikTok de SocQ. Abarca la selección de endpoints, la depuración de entradas, las tareas asíncronas, los registros normalizados, la frecuencia de actualización y el uso responsable.

Respuesta rápida: dirija cada entrada pública a
POST /v1/tiktok/{resource}, guarde el ID de tarea devuelto y consulte/v1/tasks/{id}hasta que termine. No envíe el nombre de usuario de un perfil al endpoint de videos y no trate un campo público faltante como cero.
¿API oficial de TikTok o una API de datos públicos?
Los productos oficiales de TikTok (Research, Display y Content Posting) son la opción correcta cuando se tiene una solicitud de investigación aprobada, un flujo de creadores o anunciantes autorizado mediante inicio de sesión, o la necesidad de publicar. Esos productos usan revisión de la aplicación, OAuth y alcances contractuales. No son una extracción general de videos públicos arbitrarios.
Los endpoints de SocQ de este tutorial aceptan nombres de usuario, URL de videos, consultas o hashtags públicos conocidos y realizan una recopilación de solo lectura. No se autentican como un usuario de TikTok, no otorgan derechos para reutilizar los medios devueltos ni reemplazan los productos oficiales de publicación e investigación. Elija primero el modelo de acceso: API oficiales para el trabajo autorizado o aprobado y una API de datos públicos compatible para lecturas públicas de alcance limitado.
Los listados de comercio viven en otra superficie. Para la búsqueda de productos y las reseñas, use las API de TikTok Shop, no los endpoints sociales que se describen a continuación.
Elegir el endpoint de TikTok correcto
Actualmente SocQ expone doce recursos de TikTok. Este tutorial se centra en las seis tareas de recopilación más comunes. El resto existe y debe enrutarse de forma explícita cuando lo necesite.
| Recurso | Endpoint | Entrada pública aceptada | Uso típico |
|---|---|---|---|
| Perfiles | /v1/tiktok/profiles | Nombres de usuario, con o sin @ | Identidad, biografía, conteos visibles |
| Videos | /v1/tiktok/videos | URL directas de videos | Un video conocido y sus métricas |
| Videos de un usuario | /v1/tiktok/user-videos | Nombres de usuario | Una ventana del feed público de un creador |
| Comentarios | /v1/tiktok/comments | URL de videos | Solo comentarios de primer nivel |
| Búsqueda | /v1/tiktok/search | Consulta | Descubrimiento solo de videos |
| Hashtags | /v1/tiktok/hashtags | Etiquetas, con o sin # | Ventanas de videos por hashtag |
También están disponibles, y es fácil usarlos mal si se adivina:
video-transcriptpara URL de videos públicos que se puedan resolver.comment-repliespara la URL de un video más uncomment_idconocido.trending-feedpara unregionobligatorio.followers-listyfollowing-listpara nombres de usuario públicos.live-room-infopara unroom_idy unuser_idconocidos. No descubre salas en vivo ni espera a que una cuenta inicie una transmisión en vivo.
Son operaciones públicas de lectura. Compare los modelos de proveedores en API de scraping de TikTok y alternativas a la API de TikTok cuando la tarea sea elegir un proveedor y no implementar.
Normalizar las entradas antes de gastar una solicitud
Guarde la entrada sin procesar como registro de origen y luego canonice una copia:
- Quite el
@inicial de los nombres de usuario y el#inicial de los hashtags, o consérvelos – se aceptan ambas formas, pero su registro debe usar una sola forma canónica. - Elimine los espacios en blanco sobrantes y rechace los valores vacíos.
- Convierta las URL de perfil en nombres de usuario en su capa de entrada. Convierta los hosts de compartir y de la versión para teléfono en una URL
www.tiktok.com/@user/video/{id}cuando el ID del video esté presente. - Elimine duplicados de los nombres de usuario sin distinguir mayúsculas de minúsculas y de las URL por ruta canónica.
- Enrute por tipo de entidad. Un nombre de usuario no es una URL de video. Un hashtag no es una consulta de búsqueda.
- Mantenga
results_limitcomo un tope de la solicitud, no como una garantía de que los resultados estén completos.
user-videos acepta results_limit de 20 a 2000, sort_by con valor latest o popular, y un region opcional. La búsqueda es solo de videos y acepta sort_by con valor relevance, date o likes, además de published_within con valor day, week, month, three_months o six_months.
Enviar una tarea de recopilación
Recopile perfiles públicos:
curl -X POST "https://api.socq.ai/v1/tiktok/profiles" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"usernames":["tiktok","@natgeo"]}'
Recopile videos conocidos:
curl -X POST "https://api.socq.ai/v1/tiktok/videos" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.tiktok.com/@tiktok/video/7234567890123456789"]}'
Recopile una ventana del feed de un creador:
curl -X POST "https://api.socq.ai/v1/tiktok/user-videos" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"usernames":["@tiktok"],"results_limit":20,"sort_by":"latest","region":"US"}'
Recopile comentarios de primer nivel y obtenga las respuestas solo cuando ya tenga el ID de un comentario:
curl -X POST "https://api.socq.ai/v1/tiktok/comments" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.tiktok.com/@tiktok/video/7234567890123456789"],"results_limit":100}'
curl -X POST "https://api.socq.ai/v1/tiktok/comment-replies" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://www.tiktok.com/@scout2015/video/6718335390845095173","comment_id":"6718335906996502534","results_limit":20}'
La búsqueda y el descubrimiento por hashtag usan la misma autenticación y el mismo contenedor de tarea:
curl -X POST "https://api.socq.ai/v1/tiktok/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"python tutorial","results_limit":50,"sort_by":"relevance","published_within":"month"}'
La respuesta crea una tarea asíncrona. Guarde su ID junto con el ID del lote interno y las entradas.
Consultar la tarea sin crear duplicados
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
Considere esperados los estados queued y running. Consulte con retroceso exponencial y un retraso máximo. Cuando la tarea termina con éxito, procese data.results.items; si has_more es true, continúe con next_cursor.
Su tabla de trabajos debe registrar:
- El ID del lote interno y el ID de la tarea de SocQ.
- El tipo de recurso y las entradas canónicas.
- Las marcas de tiempo de envío, de la última consulta y de finalización.
- El estado terminal y la categoría de error normalizada.
- El último cursor de resultados confirmado.
No vuelva a enviar solo porque un worker se reinició. Primero reanude desde el estado de la tarea guardado.
Los campos devueltos
Todos los registros comparten campos de identidad normalizados como id, platform, resource, type, url, created_at, collected_at y extra. Los campos específicos de cada recurso se mantienen explícitos.
Un perfil incluye username, name, description, avatar_url, is_verified, is_private y métricas visibles. No es una lista de los videos de ese creador.
Un video incluye caption, author, métricas visibles de reproducciones, Me gusta, comentarios y veces compartido, media, duration_seconds, hashtags, mentions y music cuando son públicos. Las URL de los medios son referencias de origen, no descargas permanentes.
Un comentario incluye text, author, metrics.likes_count y, con frecuencia, metrics.replies_count. Los conteos de respuestas no son el texto de las respuestas. El contenido de las respuestas requiere comment-replies y un comment_id del mismo video.
Los resultados de búsqueda y de hashtags reutilizan la estructura de video. Son resultados de descubrimiento clasificados o por ventanas, no un archivo exhaustivo.
Los datos faltantes deben permanecer como null o ausentes. Un conteo de reproducciones oculto no es cero. Una transcripción no disponible no es una cadena vacía que pueda interpretarse como “sin voz”.
Worker en Python para entradas mixtas de TikTok
import time
import requests
BASE = "https://api.socq.ai/v1"
HEADERS = {
"Authorization": f"Bearer {SOCQ_API_KEY}",
"Content-Type": "application/json",
}
def collect(resource, payload):
created = requests.post(
f"{BASE}/tiktok/{resource}",
headers=HEADERS,
json=payload,
timeout=30,
)
created.raise_for_status()
task_id = created.json()["data"]["task_id"]
delay = 2
while True:
response = requests.get(
f"{BASE}/tasks/{task_id}",
headers=HEADERS,
timeout=30,
)
response.raise_for_status()
task = response.json()["data"]
if task["status"] == "succeeded":
return task["results"]["items"]
if task["status"] in {"failed", "cancelled"}:
raise RuntimeError(task)
time.sleep(delay)
delay = min(delay * 1.5, 15)
profiles = collect("profiles", {"usernames": ["tiktok"]})
videos = collect("user-videos", {
"usernames": ["tiktok"],
"results_limit": 20,
"sort_by": "latest",
})
En producción, guarde la tarea antes de consultar su estado, pagine con next_cursor y reintente solo las fallas transitorias.
Modelar por separado las entidades y las instantáneas
Los perfiles cambian lentamente. Las métricas de los videos y el volumen de comentarios cambian rápido.
tiktok_entity
platform_id
resource
canonical_url_or_username
stable public fields
first_seen_at
last_seen_at
tiktok_snapshot
platform_id
collected_at
visible metrics
mutable public fields
source_task_id
Haga upsert de la entidad por resource + id cuando exista un ID. Use como alternativa de respaldo una URL canónica o un nombre de usuario y mantenga una vía de fusión para cuando se descubra el ID más adelante. Agregue instantáneas solo después de una recopilación exitosa y de la validación del esquema.
No calcule el crecimiento cuando a alguna de las dos instantáneas le falte la métrica. Un conteo oculto no es cero.
Validar antes de cargar en producción
Como mínimo, verifique que:
platformsea igual atiktok.resourcecoincida con el endpoint usado.- Los registros de perfiles no se traten como un feed de videos.
- Los registros de comentarios sean de primer nivel, salvo que provengan de
comment-replies. - Los resultados de búsqueda sean videos, no usuarios ni sonidos.
- Los conteos no sean negativos cuando estén presentes.
created_atycollected_atse interpreten como marcas de tiempo.- Cada registro pueda rastrearse hasta una entrada y una tarea.
Ponga en cuarentena los registros no válidos en lugar de forzar su conversión en silencio. Conserve la respuesta sin procesar, el error de validación y la hora de recopilación.
Elegir un calendario de actualización por entidad
| Entidad | Frecuencia inicial razonable | Motivo |
|---|---|---|
| Perfil | Semanal o mensual | La biografía pública y los campos de identidad cambian lentamente |
| Video conocido | De cada hora a diaria mientras esté activo | La interacción se mueve rápido después de la publicación |
| Ventana de videos de un usuario | Diaria para el monitoreo | Los feeds están clasificados y son incompletos |
| Comentarios | De cada hora a diaria mientras un video esté activo | Los comentarios nuevos de primer nivel llegan en ráfagas |
| Búsqueda / hashtags | Diaria o bajo demanda | La clasificación y las ventanas cambian |
| Seguidores / seguidos | Semanal | Las listas de relaciones son grandes y parciales |
| Sala en vivo | Solo mientras ya conozca la sala | El endpoint no descubre transmisiones en vivo |
Use la necesidad del negocio y la minimización de datos para reducir la recopilación innecesaria.
Modos de falla comunes
El endpoint no devuelve ningún elemento
Confirme que el nombre de usuario o la URL sea público, siga disponible y esté enrutado al recurso correcto. Un video privado o eliminado debe seguir siendo un error a nivel de la entrada, no un perfil vacío.
Los perfiles parecen “vacíos” de videos
Es lo esperado. profiles devuelve únicamente registros de perfiles. Use user-videos para una ventana del feed.
Los comentarios tienen un conteo de respuestas pero no el texto de las respuestas
El endpoint de comentarios recopila comentarios de primer nivel. Obtenga el texto de las respuestas con url más comment_id. El endpoint de respuestas no descubre el comment_id solo a partir de la URL del video.
La búsqueda no encontró un sonido o un usuario
La búsqueda es solo de videos. No la trate como un directorio de usuarios, sonidos o transmisiones en vivo.
Las métricas no coinciden con las del navegador
Los conteos son instantáneas del momento de la recopilación y pueden estar redondeados, ocultos, almacenados en caché o actualizados entre solicitudes. Compare las marcas de tiempo y las definiciones de los campos.
Las URL de los medios fallan más adelante
Trate las URL del video, la portada y el avatar como referencias de origen temporales. Actualícelas solo cuando el caso de uso y los términos lo permitan.
Uso responsable de los datos de TikTok
Recopile solo los campos públicos necesarios para un propósito legítimo. No eluda los muros de inicio de sesión, las cuentas privadas, las restricciones de edad ni las restricciones técnicas. Evite las inferencias sensibles y las decisiones automatizadas que puedan afectar de manera material a una persona sin las salvaguardas adecuadas.
Los datos de TikTok pueden ser datos personales. Establezca una base legal cuando se requiera, defina procedimientos de retención y eliminación, proteja las claves de API y los registros almacenados, respete los derechos aplicables y revise los términos vigentes de TikTok y la legislación local con asesoría legal calificada. Una API de datos públicos no otorga derechos adicionales sobre la música, la imagen de las personas ni los archivos de video.
El mismo patrón de catálogo se describe en la guía de la API unificada de redes sociales cuando TikTok es una fuente entre muchas.
Scraping de TikTok: preguntas frecuentes (FAQ)
¿Es legal hacer scraping de TikTok?
No hay una respuesta universal. Depende de la jurisdicción, los datos, el método de acceso, el propósito, el contrato y las salvaguardas. Este tutorial no constituye asesoría legal.
¿Las API oficiales de TikTok son gratuitas?
El acceso oficial a Research, Display y Content Posting se basa en solicitudes o en permisos. Este tutorial es un flujo de lectura pública y no reemplaza esos productos.
¿Puedo hacer scraping de videos privados o eliminados?
No. No eluda los controles de privacidad ni de acceso. Las entradas eliminadas y privadas deben fallar de forma limpia.
¿El endpoint de comentarios devuelve el texto de las respuestas?
No. Devuelve comentarios de primer nivel. Puede haber conteos de respuestas. El texto de las respuestas requiere comment-replies y un comment_id.
¿Puedo enviar la URL de un perfil al endpoint de videos?
No. Videos acepta URL directas de videos. Profiles y user-videos aceptan nombres de usuario.
¿La búsqueda devuelve usuarios o sonidos?
No. La búsqueda actual es solo de videos.
¿Qué clave debo usar para eliminar duplicados?
Prefiera resource + id; use como alternativa de respaldo una URL canónica o un nombre de usuario normalizado cuando el ID público no esté disponible.
TIKTOK API
Probar el flujo de trabajo con una URL pública de TikTok
Envíe entradas públicas y reciba registros normalizados con contexto de origen rastreable.
Ver las API de TikTok