TikTokScrapingTutorial de API

Cómo extraer videos, perfiles y comentarios de TikTok con una API

Recopile perfiles, videos, comentarios, búsquedas y hashtags públicos de TikTok con endpoints asíncronos, depuración de entradas y JSON normalizado.

SocQActualizado el 10 de septiembre de 202612 min de lectura

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.

API de TikTok de SocQ

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.

RecursoEndpointEntrada pública aceptadaUso típico
Perfiles/v1/tiktok/profilesNombres de usuario, con o sin @Identidad, biografía, conteos visibles
Videos/v1/tiktok/videosURL directas de videosUn video conocido y sus métricas
Videos de un usuario/v1/tiktok/user-videosNombres de usuarioUna ventana del feed público de un creador
Comentarios/v1/tiktok/commentsURL de videosSolo comentarios de primer nivel
Búsqueda/v1/tiktok/searchConsultaDescubrimiento solo de videos
Hashtags/v1/tiktok/hashtagsEtiquetas, con o sin #Ventanas de videos por hashtag

También están disponibles, y es fácil usarlos mal si se adivina:

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:

  1. 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.
  2. Elimine los espacios en blanco sobrantes y rechace los valores vacíos.
  3. 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.
  4. Elimine duplicados de los nombres de usuario sin distinguir mayúsculas de minúsculas y de las URL por ruta canónica.
  5. Enrute por tipo de entidad. Un nombre de usuario no es una URL de video. Un hashtag no es una consulta de búsqueda.
  6. Mantenga results_limit como 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:

  • platform sea igual a tiktok.
  • resource coincida 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_at y collected_at se 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

EntidadFrecuencia inicial razonableMotivo
PerfilSemanal o mensualLa biografía pública y los campos de identidad cambian lentamente
Video conocidoDe cada hora a diaria mientras esté activoLa interacción se mueve rápido después de la publicación
Ventana de videos de un usuarioDiaria para el monitoreoLos feeds están clasificados y son incompletos
ComentariosDe cada hora a diaria mientras un video esté activoLos comentarios nuevos de primer nivel llegan en ráfagas
Búsqueda / hashtagsDiaria o bajo demandaLa clasificación y las ventanas cambian
Seguidores / seguidosSemanalLas listas de relaciones son grandes y parciales
Sala en vivoSolo mientras ya conozca la salaEl 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)

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