Une page TikTok publique semble simple : un nom d’utilisateur, une vidéo, un fil de commentaires. Le contrat de collecte, lui, ne l’est pas. Un profil n’est pas un flux de vidéos. Les commentaires ne forment pas une arborescence complète de réponses. La recherche ne porte que sur les vidéos. La consultation d’un live ne permet pas de découvrir des lives.
Ce tutoriel construit un workflow de données publiques maintenable avec les API TikTok de SocQ. Il couvre le choix des endpoints, l’hygiène des entrées, les tâches asynchrones, les enregistrements normalisés, la cadence d’actualisation et l’usage responsable.

Réponse rapide : dirigez chaque entrée publique vers
POST /v1/tiktok/{resource}, conservez l’ID de tâche renvoyé et interrogez/v1/tasks/{id}jusqu’à son terme. N’envoyez pas un nom d’utilisateur à l’endpoint des vidéos, et ne considérez pas un champ public manquant comme égal à zéro.
API TikTok officielle ou API de données publiques ?
Les produits officiels Research, Display et Content Posting de TikTok sont le bon choix si vous disposez d’une application de recherche approuvée, d’un workflow de créateur ou d’annonceur autorisé par connexion, ou d’un besoin de publication. Ces produits reposent sur une validation de l’application, sur OAuth et sur des scopes contractuels. Ils ne servent pas à scraper de façon générale des vidéos publiques quelconques.
Les endpoints SocQ de ce tutoriel acceptent des noms d’utilisateur, des URL de vidéos, des requêtes ou des hashtags publics connus, et effectuent une collecte en lecture seule. Ils ne s’authentifient pas comme un utilisateur TikTok, n’accordent aucun droit de réutiliser les médias renvoyés et ne remplacent ni les produits officiels de publication ni ceux de recherche. Choisissez d’abord le modèle d’accès : les API officielles pour un travail autorisé ou approuvé, une API de données publiques prise en charge pour des lectures publiques à périmètre étroit.
Les fiches commerciales relèvent d’une autre surface. Pour la recherche de produits et les avis, utilisez les API TikTok Shop, et non les endpoints sociaux ci-dessous.
Choisir le bon endpoint TikTok
SocQ expose actuellement douze ressources TikTok. Ce tutoriel se concentre sur les six tâches de collecte les plus courantes. Les autres existent et doivent être routées explicitement lorsque vous en avez besoin.
| Ressource | Endpoint | Entrée publique acceptée | Usage typique |
|---|---|---|---|
| Profils | /v1/tiktok/profiles | Noms d’utilisateur, avec ou sans @ | Identité, bio, compteurs visibles |
| Vidéos | /v1/tiktok/videos | URL directes de vidéos | Une vidéo connue et ses métriques |
| Vidéos d’un utilisateur | /v1/tiktok/user-videos | Noms d’utilisateur | Une fenêtre du flux public d’un créateur |
| Commentaires | /v1/tiktok/comments | URL de vidéos | Commentaires de premier niveau uniquement |
| Recherche | /v1/tiktok/search | Requête | Découverte limitée aux vidéos |
| Hashtags | /v1/tiktok/hashtags | Tags, avec ou sans # | Fenêtres de vidéos par hashtag |
Également disponibles, et faciles à mal utiliser si vous devinez :
video-transcriptpour les URL de vidéos publiques résolvables.comment-repliespour une URL de vidéo et uncomment_idconnu.trending-feedpour unregionobligatoire.followers-listetfollowing-listpour des noms d’utilisateur publics.live-room-infopour unroom_idet unuser_idconnus. Il ne découvre pas les lives et n’attend pas qu’un compte passe en direct.
Ce sont des opérations de lecture publique. Comparez les modèles de fournisseurs dans API de scraping TikTok et alternatives aux API TikTok lorsque l’enjeu est le choix d’un fournisseur plutôt que la mise en œuvre.
Normaliser les entrées avant de dépenser une requête
Conservez l’entrée brute comme preuve de provenance, puis canonisez une copie :
- Retirez le
@initial des noms d’utilisateur et le#initial des hashtags, ou conservez-les – les deux formes sont acceptées, mais votre registre doit utiliser une seule forme canonique. - Supprimez les espaces en début et en fin de valeur et rejetez les valeurs vides.
- Convertissez les URL de profils en noms d’utilisateur dans votre couche d’entrée. Convertissez les hôtes de partage et mobiles en URL
www.tiktok.com/@user/video/{id}lorsque l’ID de la vidéo est présent. - Dédupliquez les noms d’utilisateur sans tenir compte de la casse et les URL par chemin canonique.
- Routez par type d’entité. Un nom d’utilisateur n’est pas une URL de vidéo. Un hashtag n’est pas une requête de recherche.
- Gardez
results_limitcomme plafond de requête, pas comme garantie d’exhaustivité.
user-videos accepte results_limit de 20 à 2 000, sort_by valant latest ou popular, et un region facultatif. La recherche ne porte que sur les vidéos et accepte sort_by valant relevance, date ou likes, ainsi que published_within valant day, week, month, three_months ou six_months.
Soumettre une tâche de collecte
Collecter des profils publics :
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"]}'
Collecter des vidéos connues :
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"]}'
Collecter une fenêtre du flux d’un créateur :
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"}'
Collecter les commentaires de premier niveau, puis les réponses uniquement si vous disposez déjà d’un ID de commentaire :
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 recherche et la découverte par hashtag utilisent la même authentification et la même enveloppe de tâche :
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 réponse crée une tâche asynchrone. Conservez son ID à côté de l’ID de lot interne et des entrées.
Interroger la tâche sans créer de doublons
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
Considérez queued et running comme des états attendus. Interrogez avec un backoff exponentiel et un délai maximal. Pour une tâche réussie, traitez data.results.items ; lorsque has_more vaut true, poursuivez avec next_cursor.
Votre table de tâches doit consigner :
- L’ID de lot interne et l’ID de tâche SocQ.
- Le type de ressource et les entrées canoniques.
- Les horodatages de soumission, de dernière interrogation et de fin.
- Le statut final et la catégorie d’erreur normalisée.
- Le dernier curseur de résultats validé.
Ne soumettez pas de nouveau une tâche simplement parce qu’un worker a redémarré. Reprenez d’abord à partir de l’état de tâche conservé.
Comprendre les champs renvoyés
Tous les enregistrements partagent des champs d’identité normalisés comme id, platform, resource, type, url, created_at, collected_at et extra. Les champs propres à chaque ressource restent explicites.
Un profil comprend username, name, description, avatar_url, is_verified, is_private et des métriques visibles. Ce n’est pas la liste des vidéos du créateur.
Une vidéo comprend caption, author, les métriques visibles de lectures, de mentions « J’aime », de commentaires et de partages, media, duration_seconds, hashtags, mentions et music lorsqu’ils sont publics. Les URL de médias sont des références vers la source, pas des téléchargements permanents.
Un commentaire comprend text, author, metrics.likes_count et souvent metrics.replies_count. Un nombre de réponses n’est pas le texte des réponses. Le contenu des réponses exige comment-replies et un comment_id issu de la même vidéo.
Les résultats de recherche et de hashtags reprennent la structure d’une vidéo. Ce sont des résultats de découverte classés ou fenêtrés, pas une archive exhaustive.
Les données manquantes doivent rester null ou absentes. Un nombre de lectures masqué n’est pas égal à zéro. Une transcription indisponible n’est pas une chaîne vide que l’on peut interpréter comme « pas de parole ».
Worker Python pour des entrées TikTok mixtes
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 production, conservez la tâche avant de l’interroger, paginez avec next_cursor et ne relancez que les échecs transitoires.
Modéliser séparément les entités et les instantanés
Les profils changent lentement. Les métriques des vidéos et le volume de commentaires changent vite.
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
Faites un upsert de l’entité par resource + id lorsqu’un ID existe. À défaut, repliez-vous sur une URL canonique ou un nom d’utilisateur, et prévoyez un chemin de fusion pour la découverte ultérieure de l’ID. N’ajoutez des instantanés qu’après une collecte réussie et une validation du schéma.
Ne calculez pas de croissance lorsque la métrique manque dans l’un des deux instantanés. Un compteur masqué n’est pas égal à zéro.
Valider avant de charger en production
Vérifiez au minimum que :
platformest égal àtiktok.resourcecorrespond à l’endpoint utilisé.- Les enregistrements de profils ne sont pas traités comme un flux de vidéos.
- Les enregistrements de commentaires sont de premier niveau, sauf s’ils proviennent de
comment-replies. - Les résultats de recherche sont des vidéos, pas des utilisateurs ni des sons.
- Les compteurs sont positifs ou nuls lorsqu’ils sont présents.
created_atetcollected_atpeuvent être interprétés comme des horodatages.- Chaque enregistrement peut être relié à une entrée et à une tâche.
Placez les enregistrements invalides en quarantaine plutôt que de les convertir silencieusement. Conservez la réponse brute, l’erreur de validation et l’heure de collecte.
Choisir un calendrier d’actualisation par entité
| Entité | Cadence de départ raisonnable | Raison |
|---|---|---|
| Profil | Hebdomadaire ou mensuelle | La bio publique et les champs d’identité évoluent lentement |
| Vidéo connue | Horaire à quotidienne tant qu’elle est active | L’engagement évolue vite après la publication |
| Fenêtre de vidéos d’un utilisateur | Quotidienne pour la surveillance | Les flux sont classés et incomplets |
| Commentaires | Horaire à quotidienne tant qu’une vidéo est active | Les nouveaux commentaires de premier niveau arrivent par vagues |
| Recherche / hashtags | Quotidienne ou à la demande | Le classement et les fenêtres changent |
| Abonnés / abonnements | Hebdomadaire | Les listes de relations sont volumineuses et partielles |
| Live | Uniquement lorsque vous connaissez déjà la salle | L’endpoint ne découvre pas les lives |
Appuyez-vous sur le besoin métier et la minimisation des données pour réduire la collecte inutile.
Modes de défaillance courants
L’endpoint ne renvoie aucun élément
Vérifiez que le nom d’utilisateur ou l’URL est public, toujours disponible et dirigé vers la bonne ressource. Une vidéo privée ou supprimée doit rester une erreur au niveau de l’entrée, pas devenir un profil vide.
Les profils semblent « vides » de vidéos
C’est normal. profiles ne renvoie que des enregistrements de profils. Utilisez user-videos pour obtenir une fenêtre du flux.
Des commentaires ont un nombre de réponses mais pas de texte de réponse
L’endpoint des commentaires collecte les commentaires de premier niveau. Récupérez le texte des réponses avec url et comment_id. L’endpoint des réponses ne découvre pas le comment_id à partir de la seule URL de la vidéo.
La recherche a manqué un son ou un utilisateur
La recherche ne porte que sur les vidéos. Ne la traitez pas comme un annuaire d’utilisateurs, de sons ou de LIVE.
Les métriques ne correspondent pas à celles du navigateur
Les compteurs sont des instantanés pris au moment de la collecte ; ils peuvent être arrondis, masqués, mis en cache ou mis à jour entre deux requêtes. Comparez les horodatages et les définitions des champs.
Les URL de médias échouent plus tard
Considérez les URL de vidéos, de couvertures et d’avatars comme des références temporaires vers la source. N’actualisez que si le cas d’usage et les conditions l’autorisent.
Usage responsable des données TikTok
Ne collectez que les champs publics nécessaires à une finalité légitime. Ne contournez ni les murs de connexion, ni les comptes privés, ni les restrictions d’âge, ni les restrictions techniques. Évitez les déductions sensibles et les décisions automatisées susceptibles d’affecter sensiblement une personne sans garanties appropriées.
Les données TikTok peuvent être des données personnelles. Établissez une base légale lorsque c’est requis, définissez des procédures de conservation et de suppression, sécurisez les clés API et les enregistrements stockés, respectez les droits applicables, et faites examiner les conditions actuelles de TikTok et la législation locale par des conseillers qualifiés. Une API de données publiques n’accorde aucun droit supplémentaire sur la musique, l’image des personnes ou les fichiers vidéo.
Le même schéma de catalogue est décrit dans le guide de l’API unifiée pour les réseaux sociaux, lorsque TikTok n’est qu’une source parmi d’autres.
FAQ
Le scraping de TikTok est-il légal ?
Il n’existe pas de réponse universelle. Cela dépend de la juridiction, des données, de la méthode d’accès, de la finalité, du contrat et des garanties mises en place. Ce tutoriel ne constitue pas un avis juridique.
Les API officielles de TikTok sont-elles gratuites ?
L’accès officiel à Research, Display et Content Posting se fait sur candidature ou sous autorisation. Ce tutoriel décrit un workflow de lecture publique et ne remplace pas ces produits.
Puis-je scraper des vidéos privées ou supprimées ?
Non. Ne contournez pas les contrôles de confidentialité ou d’accès. Les entrées privées et supprimées doivent échouer proprement.
L’endpoint des commentaires renvoie-t-il le texte des réponses ?
Non. Il renvoie les commentaires de premier niveau. Le nombre de réponses peut être présent. Le texte des réponses exige comment-replies et un comment_id.
Puis-je envoyer l’URL d’un profil à l’endpoint des vidéos ?
Non. Les vidéos acceptent des URL directes de vidéos. Les profils et les vidéos d’un utilisateur acceptent des noms d’utilisateur.
La recherche renvoie-t-elle des utilisateurs ou des sons ?
Non. La recherche actuelle ne porte que sur les vidéos.
Quelle clé utiliser pour la déduplication ?
Privilégiez resource + id ; repliez-vous sur une URL canonique normalisée ou un nom d’utilisateur lorsque l’ID public n’est pas disponible.
TIKTOK API
Tester le workflow avec une URL publique TikTok
Envoyez des entrées publiques et recevez des enregistrements normalisés, avec un contexte de source traçable.
Découvrir les API TikTok