API TikTok — Transport + Ingestion pour un compte réel
Vous maîtrisez le câble : authentifiez-vous sur un compte TikTok, publiez une vidéo, récupérez les chiffres et écrivez ces chiffres dans le wiki comme un journal de retour durable. Vous ne décidez pas quoi fabriquer, quand le publier ni comment le légender — cela relève de la famille stratégie/conditionnement court. Fournissez un transport propre et un journal interrogeable ; laissez les frères et sœurs interpréter.
TikTok se divise en trois API distinctes, et un compte réel touche aux trois :
- API Content Posting —
https://open.tiktokapis.com/v2/post/publish/...— le côté écriture : initier une publication, transférer le fichier, interroger l'état. Nécessite un audit. - API Display —
https://open.tiktokapis.com/v2/video/...— le côté lecture bon marché : votre propre profil et compteurs de base par vidéo (view_count, like_count, comment_count, share_count). - API TikTok for Business — le côté lecture riche : temps de visionnage, achèvement, sources d'impression. Activé via un portail professionnel séparé, et non via l'application développeur standard.
L'authentification est OAuth v2 utilisateur via Login Kit, jamais un jeton de service. Un humain possède le compte ; vous agissez en son nom avec un jeton d'actualisation. Il n'y a aucun SDK officiel TikTok — vous appelez les points de terminaison REST directement avec n'importe quel client HTTP. Traitez le jeton d'accès comme un objet d'identification à courte durée de vie et actualisable, jamais comme un littéral codé en dur.
Quand utiliser / Quand NE PAS utiliser
À utiliser lorsque :
- Vous connectez un script ou un agent pour publier sur un compte : publication directe ou téléchargement en brouillon via
/v2/post/publish/video/init/(ou/inbox/pour un brouillon), puisFILE_UPLOADPUT par morceaux ouPULL_FROM_URL, puis interrogez/v2/post/publish/status/fetch/. - Vous extrayez les statistiques vidéo de votre propre compte : compteurs via Display
POST /v2/video/query/(ou/v2/video/list/) ; temps de visionnage/achèvement/sources d'impression via l'API Business Account. - Vous construisez la boucle récurrente « récupérer les performances → écrire dans
02-DOCS/wiki/shortform/» qui transforme les réponses API en un journal de retour de compte que les frères et sœurs peuvent lire. - Vous déboguez des échecs spécifiques à TikTok :
scope_not_authorized,url_ownership_unverified,rate_limit_exceeded(6 req/min), expiration du jeton d'accès sur 24 heures, audit/video.publishnon approuvé, publication privée uniquement par application non auditée.
À NE PAS utiliser lorsque (redirigez vers le frère ou la sœur qui possède la compétence) :
| Ce que vous voulez vraiment | Allez vers |
|---|---|
| Quoi publier / cadence / créneau / stratégie d'accroche | shortform-strategy (id catalogue) |
| Idées de clips, accroches, backlog de sujets | shortform-ideation (id catalogue) |
| Légende / couverture / conditionnement du titre, cadrage A/B | shortform-packaging (id catalogue) |
| Couper / légender / rendre le fichier clip réel | shortform-editing (id catalogue) |
| Rendre un fichier vidéo par programmation | ../remotion-video/SKILL.md |
| Publier un actif sur TikTok + IG + YouTube à la fois | ../social-publisher/SKILL.md |
| API Graph / Content Publishing d'Instagram | ../instagram-api/SKILL.md |
| Les deux API YouTube (même famille, autre plateforme) | ../youtube-api/SKILL.md |
| Envelopper un fournisseur REST arbitraire avec OAuth + tentatives | api-connector-builder (id catalogue) |
| Enchaîner publication → ligne Notion → Slack entre outils | automation-flows (id catalogue) |
En une ligne : cette compétence authentifie, appelle et ingère les API Content Posting + Display + Business de TikTok dans le wiki. Quoi publier et comment le conditionner relèvent des frères et sœurs shortform-strategy / shortform-ideation / shortform-packaging ; la publication multi-réseaux relève de social-publisher.
1. Configuration unique (à faire avant tout code)
Une liste de vérification, car chaque étape manquante produit un échec distinct et déroutant plus tard :
- Enregistrez une application développeur TikTok dans le portail développeur.
- Ajoutez les produits dont vous avez besoin : Login Kit (OAuth), API Content Posting (publication), API Display (lecture des comptes). Les Insights se trouvent dans le portail TikTok for Business séparé — activez également l'accès à ce compte si vous avez besoin du temps de visionnage/achèvement.
- Définissez une URI de redirection exacte pour le flux OAuth.
- Soumettez l'application pour audit avant de publier du contenu public. Une application non auditée ne peut publier qu'en privé (
SELF_ONLY) et uniquement vers un ensemble limité d'utilisateurs de test. C'est la surprise n°1 « ça marche sur ma machine, ça casse en prod » — voir la règle ci-dessous. - Si vous publiez par URL (
PULL_FROM_URL), vérifiez le domaine / préfixe d'URL dans le portail (TXT DNS ou préfixe d'URL), sinon chaque init renvoieurl_ownership_unverified.
Les trois portes sont indépendantes. Ne présumez pas qu'une approbation couvre tout :
Mauvais : « Mon application est approuvée, donc la publication et les insights fonctionnent tous les deux. »
Bon : L'*audit* Content Posting verrouille la publication publique ;
Le *scope* Display (video.list) verrouille les comptes de ses propres vidéos ;
L'*accès* au portail Business verrouille le temps de visionnage / achèvement / sources d'impression.
Trois portes distinctes — vérifiez chacune.
Tableau des scopes — ne demandez que ce dont le travail a besoin :
| Scope | Accorde | Utilisation pour |
|---|---|---|
video.publish | Publication directe sur le flux public | /post/publish/video/init/ (nécessite audit) |
video.upload | Téléchargement dans les brouillons/boîte de réception pour que l'utilisateur finalise | /post/publish/inbox/video/init/ |
video.list | Lire vos propres vidéos + compteurs de base | Display POST /v2/video/query/ |
user.info.basic | Lire le profil (open_id, nom d'affichage, avatar) | POST /v2/user/info/ |
La procédure complète d'enregistrement d'application + activation de produits, la porte d'audit et le dépannage scope_not_authorized se trouvent dans references/oauth-setup.md.
2. Obtenir un client authentifié et garder le jeton vivant
OAuth v2 : envoyez l'utilisateur sur https://www.tiktok.com/v2/auth/authorize/, recevez un code sur votre URI de redirection, échangez-le sur https://open.tiktokapis.com/v2/oauth/token/, et stockez le jeton d'actualisation.
Le cycle de vie est le fait prépondérant : le jeton d'accès expire dans 24 heures (expires_in: 86400) ; le jeton d'actualisation dure 365 jours (refresh_expires_in: 31536000) et se renouvelle sans nouveau consentement de l'utilisateur. Ainsi, un cron de récupération quotidien DOIT actualiser le jeton d'accès à chaque exécution, et un compte inactif depuis longtemps meurt silencieusement à la limite d'actualisation de 365 jours.
# python : REST brut, pas de SDK officiel TikTok. requests/httpx conviennent tous les deux.
import time, json, os, requests
TOKEN_URL = "https://open.tiktokapis.com/v2/oauth/token/"
STORE = "tiktok_token.json" # gitignored — contient le refresh_token tournant
def load(): return json.load(open(STORE)) if os.path.exists(STORE) else {}
def save(t): t["obtained_at"] = int(time.time()); json.dump(t, open(STORE, "w"))
def access_token():
t = load()
fresh = t.get("access_token") and time.time() < t.get("obtained_at", 0) + t["expires_in"] - 60
if fresh:
return t["access_token"]
r = requests.post(TOKEN_URL, data={ # actualisation à chaque exécution, expiration 24h
"client_key": os.environ["TIKTOK_CLIENT_KEY"],
"client_secret": os.environ["TIKTOK_CLIENT_SECRET"],
"grant_type": "refresh_token",
"refresh_token": t["refresh_token"], # durée de vie 365 jours ; tourne
}, headers={"Content-Type": "application/x-www-form-urlencoded"})
r.raise_for_status()
new = r.json()
save(new) # persister le NOUVEAU refresh_token
return new["access_token"]
// node : fetch intégré, pas de SDK.
import fs from "node:fs";
const STORE = "tiktok_token.json";
async function accessToken() {
const t = JSON.parse(fs.readFileSync(STORE, "utf8"));
if (t.access_token && Date.now() / 1000 < t.obtained_at + t.expires_in - 60) return t.access_token;
const r = await fetch("https://open.tiktokapis.com/v2/oauth/token/", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
client_key: process.env.TIKTOK_CLIENT_KEY,
client_secret: process.env.TIKTOK_CLIENT_SECRET,
grant_type: "refresh_token",
refresh_token: t.refresh_token,
}),
});
const n = await r.json();
n.obtained_at = Math.floor(Date.now() / 1000);
fs.writeFileSync(STORE, JSON.stringify(n)); // persister le refresh_token tourné
return n.access_token;
}
Règle : persistez le jeton d'actualisation et relisez-le à chaque exécution, jamais un access_token nu. Un littéral access_token=... codé en dur est un échec garanti dans les 24 heures — et c'est exactement ce que verify.sh signale.
Le flux d'échange de jetons complet (paramètres d'URL d'autorisation, PKCE, échange de code) se trouve dans references/oauth-setup.md.
3. Publier une vidéo (initier → transférer → interroger)
La publication est toujours en trois étapes : initier la publication, transférer les octets, interroger jusqu'à ce que le traitement se termine (il est asynchrone). Choisissez d'abord le mode de transfert :
| Situation | Source | Point de terminaison |
|---|---|---|
| Le fichier est local / sous votre contrôle | FILE_UPLOAD | /post/publish/video/init/ |
| Le fichier est à une URL HTTPS vérifiée | PULL_FROM_URL | /post/publish/video/init/ |
| Doit atterrir comme un brouillon que l'utilisateur finalise | FILE_UPLOAD | /post/publish/inbox/video/init/ |
Initier (FILE_UPLOAD) — renvoie publish_id et une upload_url :
import math, requests
CHUNK = 10 * 1024 * 1024 # 10 Mo, dans la fenêtre 5–64 Mo
size = os.path.getsize("clip.mp4")
chunk_count = 1 if size < 5 * 1024 * 1024 else math.ceil(size / CHUNK)
init = requests.post(
"https://open.tiktokapis.com/v2/post/publish/video/init/",
headers={"Authorization": f"Bearer {access_token()}",
"Content-Type": "application/json; charset=UTF-8"},
json={
"post_info": {"title": "légende #fyp", "privacy_level": "SELF_ONLY"}, # public nécessite audit
"source_info": {
"source": "FILE_UPLOAD",
"video_size": size,
"chunk_size": CHUNK if size >= 5 * 1024 * 1024 else size,
"total_chunk_count": chunk_count,
},
}).json()
publish_id = init["data"]["publish_id"]
upload_url = init["data"]["upload_url"]
Transférer — PUT les morceaux séquentiellement vers upload_url avec un en-tête Content-Range. Morceau min 5 Mo, max 64 Mo (dernier morceau jusqu'à 128 Mo), 1–1000 morceaux ; un fichier de moins de 5 Mo est un morceau égal à la taille du fichier. Chaque PUT renvoie 206 (plus à envoyer) ou 201 (dernier morceau accepté) :
with open("clip.mp4", "rb") as f:
for i in range(chunk_count):
first = i * CHUNK
data = f.read(CHUNK)
last = first + len(data) - 1
r = requests.put(upload_url, data=data, headers={
"Content-Type": "video/mp4",
"Content-Range": f"bytes {first}-{last}/{size}", # plage d'octets exacte
})
assert r.status_code in (206, 201), r.text # 206 = continuer, 201 = terminé
Interroger — TikTok traite de manière asynchrone ; vérifiez l'état jusqu'à PUBLISH_COMPLETE. Respectez la limite ci-dessous — ne faites pas de boucle serrée :
import time
while True:
s = requests.post(
"https://open.tiktokapis.com/v2/post/publish/status/fetch/",
headers={"Authorization": f"Bearer {access_token()}",
"Content-Type": "application/json; charset=UTF-8"},
json={"publish_id": publish_id}).json()
status = s["data"]["status"]
if status in ("PUBLISH_COMPLETE", "FAILED"):
break
time.sleep(10) # limite 6/min — dormez, ne tournez jamais
Limite de débit : 6 requêtes/minute par jeton d'accès utilisateur → rate_limit_exceeded. Limitez les appels init/status et reculez ; une boucle d'interrogation d'état serrée épuise le budget en quelques secondes.
PULL_FROM_URL nécessite que le domaine/préfixe d'URL soit vérifié dans le portail (HTTPS uniquement, pas de redirections, délai de téléchargement d'une heure) sinon init renvoie url_ownership_unverified. Le corps init complet de PULL_FROM_URL et les étapes de vérification se trouvent dans references/metrics-and-publish.md.
4. Extraire les performances (deux API, une règle)
La distinction importante : Display vous donne des compteurs ; seule l'API Business vous donne le temps de visionnage, l'achèvement et le trafic.
# (a) API Display — compteurs de base uniquement. scope video.list, jusqu'à 20 ids/requête.
counts = requests.post(
"https://open.tiktokapis.com/v2/video/query/",
params={"fields": "id,title,view_count,like_count,comment_count,share_count,duration,create_time"},
headers={"Authorization": f"Bearer {access_token()}",
"Content-Type": "application/json"},
json={"filters": {"video_ids": ["<id1>", "<id2>"]}}).json()
# renvoie : view_count, like_count, comment_count, share_count, duration, title, create_time
# (b) API Business Account — le vrai signal d'engagement.
# Renvoie les métriques que Display NE PEUT PAS : average_time_watched, total_time_watched,
# full_video_watched_rate (achèvement), impression_sources (FYP / Abonnements / profil /
# recherche), audience_countries. (Forme du point de terminaison dans references/metrics-and-publish.md.)
Mauvais : s'attendre à average_time_watched / full_video_watched_rate de /v2/video/query/
Bon : compteurs depuis Display /v2/video/query/ ;
temps de visionnage + achèvement + impression_sources depuis l'API Business Account.
Attention : les métriques d'insight Business accusent un retard de 24 à 48 heures et peuvent différer des chiffres dans l'application. Considérez une extraction fraîche comme provisoire — le journal wiki (section suivante) est l'endroit où vous les regardez se stabiliser. Le catalogue complet des métriques réparties par API se trouve dans references/metrics-and-publish.md.
5. Ingérer dans le wiki — le véritable livrable
Une extraction qui imprime sur stdout et disparaît est gaspillée. Chaque extraction ajoute une entrée datée sous 02-DOCS/wiki/shortform/, avec espace de noms de plateforme, afin que les chiffres du compte deviennent un historique interrogeable que les frères et sœurs de stratégie/conditionnement peuvent lire.
02-DOCS/wiki/shortform/
index.md # pointeur courant vers le dernier instantané + questions ouvertes
tiktok-account-2026-06-02.md # instantané de compte daté (un par extraction)
videos/tiktok-<video_id>.md # journal courant par vidéo, entrée la plus récente en haut
Les noms de fichiers portent le préfixe tiktok- car le même wiki shortform/ peut également contenir des extractions Instagram et YouTube — l'espace de noms empêche les plateformes d'entrer en collision.
Modèle d'entrée par extraction. Le frontmatter est conforme à OKF v0.1 — un type non vide est la seule exigence stricte ; title/tags/timestamp
…
[tronqué pour la traduction]