Communitygithub.com

ericrisco/rsc-harness

Utilisez cette compétence pour connecter un compte TikTok réel au code via les API de publication de contenu, d'affichage et de compte professionnel — OAuth, publication vidéo par morceaux avec suivi d'état, et extraction des vues, du temps de visionnage et des sources d'impression, puis enregistrement de ces performances dans le wiki sous forme d'enregistrement de retour daté. Couvre les jetons de courte durée qui cassent une tâche cron, la propriété non vérifiée d'une URL extraite, et les limites de débit. N'inclut PAS quoi publier ni comment le conditionner (c'est le rôle de `shortform-strategy` et `shortform-packaging`).

Qu'est-ce que rsc-harness ?

Cette compétence fournit une couche de transport et d'ingestion complète pour interagir avec les API TikTok à partir de code automatisé (scripts, agents). Elle couvre les trois API distinctes nécessaires à la gestion d'un compte réel : l'API Content Posting pour la publication vidéo, l'API Display pour les métriques de base (vues, likes), et l'API Business Account pour les indicateurs avancés (temps de visionnage, achèvement). L'authentification s'appuie sur OAuth 2.0 via Login Kit avec des jetons d'accès à courte durée de vie et des jetons d'actualisation longue durée, et l'outillage inclut des exemples de code Python et Node.js pour la gestion des jetons, la publication vidéo par morceaux et la récupération des métriques. Elle est conçue pour être utilisée par des développeurs ou des agents d'IA qui ont besoin de connecter un compte TikTok réel à une chaîne automatisée, en fournissant des fonctionnalités de base telles que la publication, les statistiques et la journalisation, mais en déléguant les décisions de contenu et de paquetage à des compétences sœurs spécialisées. Livrée sur place, la compétence enregistre les résultats de chaque opération dans le Wiki CryoGrid en tant qu'historique durable et interrogeable.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ericrisco/rsc-harness/tree/HEAD/skills/tiktok-api

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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), puis FILE_UPLOAD PUT par morceaux ou PULL_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.publish non 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 vraimentAllez vers
Quoi publier / cadence / créneau / stratégie d'accrocheshortform-strategy (id catalogue)
Idées de clips, accroches, backlog de sujetsshortform-ideation (id catalogue)
Légende / couverture / conditionnement du titre, cadrage A/Bshortform-packaging (id catalogue)
Couper / légender / rendre le fichier clip réelshortform-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 + tentativesapi-connector-builder (id catalogue)
Enchaîner publication → ligne Notion → Slack entre outilsautomation-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 :

  1. Enregistrez une application développeur TikTok dans le portail développeur.
  2. 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.
  3. Définissez une URI de redirection exacte pour le flux OAuth.
  4. 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.
  5. 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 renvoie url_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 :

ScopeAccordeUtilisation pour
video.publishPublication directe sur le flux public/post/publish/video/init/ (nécessite audit)
video.uploadTéléchargement dans les brouillons/boîte de réception pour que l'utilisateur finalise/post/publish/inbox/video/init/
video.listLire vos propres vidéos + compteurs de baseDisplay POST /v2/video/query/
user.info.basicLire 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 :

SituationSourcePoint de terminaison
Le fichier est local / sous votre contrôleFILE_UPLOAD/post/publish/video/init/
Le fichier est à une URL HTTPS vérifiéePULL_FROM_URL/post/publish/video/init/
Doit atterrir comme un brouillon que l'utilisateur finaliseFILE_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]

Individual skills in this repo

This repo contains 9 individual skills — each has its own dedicated page.

ericrisco/rsc-harness

Use when writing the words on a single conversion page — the hero headline and subhead, the offer, the proof and testimonials, and one primary CTA — or diagnosing a page that gets traffic and does not convert, as a copy problem rather than a layout one. NOT the paid ad that drives the click (that is `ads`), NOT the visual layout the words sit in (that is `design`), NOT the experiment that picks the winning variant (that is `ab-testing`).

ericrisco/rsc-harness

Use when you need to render an actual video file with Remotion — React compositions, the Composition/Sequence/TransitionSeries graph, transitions, burned-in word-by-word captions from a transcript, automatic silence removal, b-roll overlays, headless CI renders, and a final MP4 or MOV. NOT writing the script, hook, beats or caption text (that is `video-shorts`), NOT mastering audio to LUFS or building an RSS feed (that is `podcast`), NOT structuring the narrative arc (that is `course-storytelling`).

ericrisco/rsc-harness

Use when you have raw 9:16 footage and need it cut into a post-ready vertical short — dead air removed, fast jump cuts, karaoke word-by-word burned-in captions from a transcript, cuts and zooms snapped to the music beat, safe-area placement so captions clear the platform UI, and a platform-correct MP4 export. NOT writing the script, hook, beats or caption text (that is `video-shorts`), NOT building a Remotion React composition codebase (that is `remotion-video`), NOT deciding when or where to post (that is `social-publisher`).

ericrisco/rsc-harness

Use when a Reels/TikTok/Shorts account needs its next video ideas scored into a ranked backlog, grounded in its own performance log plus dated trending sounds, each bet logged so its outcome feeds the next batch. NOT scripting a chosen idea (that is `video-shorts`), NOT pillars or cadence (that is `shortform-strategy`), NOT packaging a finished cut (that is `shortform-packaging`).

ericrisco/rsc-harness

Use when a vertical short is shot or scripted and you need the upload-form copy and cover that win the feed — the hook line, the first-frame on-screen text, the search-led caption, a tight hashtag set, and the cover frame; it learns from what performed via the 02-DOCS log. NOT inventing the idea (that is `shortform-ideation`), NOT scripting or directing the cuts (that is `video-shorts`), NOT executing the edit (that is `shortform-editing`), NOT scheduling the post (that is `social-publisher`).

ericrisco/rsc-harness

Use when the unit of work is a TikTok/Reels account, not one clip: positioning, sustainable cadence and format mix, ride-or-skip on a trend or sound, recurring series, diagnosing a flat account, and the dated learning loop. NOT the single script or hook variants (that is `video-shorts`), NOT the idea backlog (that is `shortform-ideation`).

ericrisco/rsc-harness

Use when planning a posting schedule, building a multi-platform content calendar, or reshaping one source asset into channel-native posts across X, LinkedIn, Instagram, Threads, Bluesky, TikTok, Facebook or YouTube — cadence, best-time slots, per-platform format limits, API publish caps, and a dated CSV or JSON calendar a scheduler can import. NOT the brand voice the posts speak in (that is `brand-voice`), NOT the editorial strategy of what to make (that is `content-engine`).

ericrisco/rsc-harness

Use when scripting or directing the edit of a single vertical short that has to hold attention from the first frame — turning a topic, a clip or a long video into a shot-by-shot script and an edit decision sheet, fixing a hook that dies in second three, generating hook variants to test, and planning cuts and on-screen text. NOT scheduling or cross-platform cadence (that is `social-publisher`), NOT running the editorial calendar (that is `content-engine`), NOT defining the durable brand tone (that is `brand-voice`).

ericrisco/rsc-harness

Use to judge whether a short-form clip is worth publishing — scores a reel, short or podcast excerpt 0-100 on ten weighted criteria with automatic penalties, then ranks a batch and says where the cut-off falls. Run it on transcript candidates before rendering. NOT writing the hook or caption (that is `shortform-packaging`), NOT inventing the idea (that is `shortform-ideation`), NOT executing the edit (that is `shortform-editing`).

Skills associés