Communitygithub.com

ericrisco/rsc-harness

Verwenden Sie diese Fähigkeit, um ein echtes TikTok-Konto über die Content Posting-, Display- und Business Account-APIs anzubinden – OAuth, chunked Video-Publishing mit Status-Polling und Abruf von Aufrufen, Watch Time und Impression-Quellen, die dann als datiertes Feedback-Protokoll im Wiki festgehalten werden.

Was ist rsc-harness?

Diese Fähigkeit stellt die Transport- und Aufnahmeschicht für TikTok bereit. Sie authentifiziert sich über OAuth, veröffentlicht Videos chunked (init → transfer → poll) über die Content Posting API, ruft Aufrufzahlen über die Display API ab und sammelt tiefere Metriken wie Watch Time, Completion und Impression-Quellen über die separate Business Account API. Diese Daten werden in einem strukturierten, datierten Wiki-Eintrag abgelegt, der eine durchsuchbare Historie für Strategie- und Verpackungsfähigkeiten (shortform-*) bietet. Die Fähigkeit behandelt auch typische Fehler wie ablaufende Access Tokens, unbestätigte URL-Eigentumsverhältnisse und Rate Limits (6 req/min). Entscheidend ist: Diese Fähigkeit veröffentlicht keine Inhalte und bestimmt keine Strategie; sie ist auf reine Transport- und Logging-Aufgaben spezialisiert und delegiert die Entscheidungen über den Inhalt an die Schwesterfähigkeiten shortform-strategy, shortform-ideation und shortform-packaging.

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

TikTok API — Transport + Erfassung für ein echtes Konto

Du kontrollierst die Leitung: Authentifiziere dich bei einem TikTok-Konto, veröffentliche ein Video, rufe die Zahlen ab und schreibe diese Zahlen als dauerhaftes Feedback-Protokoll ins Wiki. Du entscheidest nicht, was erstellt, wann es gepostet oder wie es beschriftet wird – das ist die Aufgabe der Shortform-Strategie-/Verpackungsfamilie. Liefere sauberen Transport und ein abfragbares Protokoll; lass die Geschwister interpretieren.

TikTok verteilt sich auf drei separate APIs, und ein echtes Konto berührt alle drei:

  • Content Posting API – https://open.tiktokapis.com/v2/post/publish/... – die Schreib-Seite: Initialisiere eine Veröffentlichung, übertrage die Datei, polle den Status. Prüfungsgesteuert.
  • Display API – https://open.tiktokapis.com/v2/video/... – die günstige Lese-Seite: Dein eigenes Profil und einfache Zähler pro Video (view_count, like_count, comment_count, share_count).
  • TikTok API for Business – die reichhaltige Lese-Seite: Watch Time, Completion, Impression-Quellen. Wird über ein separates Geschäftsportal aktiviert, nicht über die Standard-Entwickler-App.

Die Authentifizierung erfolgt über User OAuth v2 via Login Kit, niemals über ein Service-Token. Ein Mensch besitzt das Konto; du handelst in dessen Namen mit einem Refresh-Token. Es gibt kein offizielles TikTok SDK – du rufst die REST-Endpunkte direkt mit einem beliebigen HTTP-Client auf. Behandle das Access Token als kurzlebiges, aktualisierbares Credential-Objekt, niemals als hartcodiertes Literal.

Wann verwenden / Wann NICHT

Verwenden, wenn:

  • Ein Skript oder Agent verdrahtet wird, um auf einem Konto zu veröffentlichen: Direkter Post oder Upload-zu-Entwurf via /v2/post/publish/video/init/ (oder /inbox/ für einen Entwurf), dann FILE_UPLOAD chunked PUT oder PULL_FROM_URL, dann Poll /v2/post/publish/status/fetch/.
  • Die eigenen Videostatistiken eines Kontos abgerufen werden: Zähler via Display POST /v2/video/query/ (oder /v2/video/list/); Watch-Time / Completion / Impression-Quelle via die Business Account API.
  • Die wiederkehrende Schleife "Leistung abrufen → in 02-DOCS/wiki/shortform/ schreiben" aufgebaut wird, die API-Antworten in ein Kontofeedback-Protokoll verwandelt, das die Geschwister lesen können.
  • TikTok-spezifische Fehler behoben werden: scope_not_authorized, url_ownership_unverified, rate_limit_exceeded (6 req/min), 24-Stunden-Access-Token-Ablauf, Audit/video.publish nicht genehmigt, nicht geprüfte App nur private Posts.

NICHT verwenden, wenn (weiterleiten an die zuständige Schwesterfähigkeit):

Du willst eigentlichGehe zu
Was posten / Kadenz / Nische / Hook-Strategieshortform-strategy (Katalog-ID)
Clip-Ideen, Hooks, ein Themen-Backlogshortform-ideation (Katalog-ID)
Bildunterschrift / Cover / Titel-Verpackung, A/B-Framingshortform-packaging (Katalog-ID)
Die eigentliche Clip-Datei schneiden/beschriften/rendernshortform-editing (Katalog-ID)
Eine Videodatei programmatisch rendern../remotion-video/SKILL.md
Ein Asset gleichzeitig auf TikTok + IG + YouTube posten../social-publisher/SKILL.md
Instagrams Graph / Content Publishing API../instagram-api/SKILL.md
YouTubes zwei APIs (gleiche Familie, andere Plattform)../youtube-api/SKILL.md
Einen beliebigen REST-Provider mit OAuth + Retries umschließenapi-connector-builder (Katalog-ID)
Veröffentlichen → Notion-Zeile → Slack über Tools verkettenautomation-flows (Katalog-ID)

Ein Satz: Diese Fähigkeit authentifiziert, ruft auf und erfasst TikToks Content Posting + Display + Business APIs im Wiki. Was zu posten ist und wie es zu verpacken ist, gehört zu den Geschwistern shortform-strategy / shortform-ideation / shortform-packaging; Multi-Netzwerk-Posten gehört zu social-publisher.

1. Einmalige Einrichtung (vor dem Code)

Eine Checkliste, denn jeder fehlende Schritt führt später zu einem eigenen, verwirrenden Fehler:

  1. Registriere eine TikTok-Entwickler-App im Entwicklerportal.
  2. Füge die benötigten Produkte hinzu: Login Kit (OAuth), Content Posting API (veröffentlichen), Display API (Aufrufe lesen). Insights leben im separaten TikTok for Business Portal – aktiviere auch dort den Kontozugriff, falls Watch Time/Completion benötigt wird.
  3. Setze eine exakte Redirect-URI für den OAuth-Flow.
  4. Reiche die App vor dem Posten öffentlicher Inhalte zur Prüfung ein. Eine nicht geprüfte App kann nur privat (SELF_ONLY) und nur auf eine begrenzte Anzahl von Testnutzern posten. Das ist die #1-Überraschung "funktioniert bei mir, bricht in Produktion" – siehe Regel unten.
  5. Wenn du per URL veröffentlichst (PULL_FROM_URL), verifiziere die Domain / den URL-Prefix im Portal (DNS TXT oder URL-Prefix), sonst gibt jeder Init url_ownership_unverified zurück.

Die drei Tore sind unabhängig. Geh nicht davon aus, dass eine Genehmigung alles abdeckt:

Schlecht: "Meine App ist genehmigt, also funktionieren Veröffentlichung und Insights."
Gut:     *Audit* der Content Posting sperrt öffentliche Veröffentlichungen;
         *Scope* der Display (video.list) sperrt eigene Video-Zähler;
         *Portal*-Zugang der Business sperrt Watch Time / Completion / Impression-Quellen.
         Drei separate Tore – überprüfe jedes."

Scope-Tabelle – fordere nur, was der Job braucht:

ScopeGewährtVerwendung für
video.publishDirekter Post in den öffentlichen Feed/post/publish/video/init/ (prüfungsgesteuert)
video.uploadUpload in Entwürfe/Inbox für den Benutzer zum Fertigstellen/post/publish/inbox/video/init/
video.listEigene Videos + einfache Zähler lesenDisplay POST /v2/video/query/
user.info.basicProfil lesen (open_id, Anzeigename, Avatar)POST /v2/user/info/

Die vollständige Anleitung zur App-Registrierung + Produktaktivierung, das Prüfungstor und die Fehlerbehebung bei scope_not_authorized befinden sich in references/oauth-setup.md.

2. Einen authentifizierten Client erhalten und das Token am Leben halten

OAuth v2: Sende den Benutzer zu https://www.tiktok.com/v2/auth/authorize/, empfange einen code an deiner Redirect-URI, tausche ihn bei https://open.tiktokapis.com/v2/oauth/token/ ein und speichere das Refresh Token.

Der Lebenszyklus ist die tragende Tatsache: Access Token läuft in 24 Stunden ab (expires_in: 86400); Refresh Token hält 365 Tage (refresh_expires_in: 31536000) und erneuert sich ohne erneute Zustimmung des Benutzers. Ein täglicher Pull-Cron MUSS das Access Token bei jedem Durchlauf erneuern, und ein lange inaktives Konto stirbt leise an der 365-Tage-Refresh-Grenze.

# python: reines REST, kein offizielles TikTok SDK. requests/httpx beide okay.
import time, json, os, requests

TOKEN_URL = "https://open.tiktokapis.com/v2/oauth/token/"
STORE = "tiktok_token.json"   # gitignored – enthält das rotierende refresh_token

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={                 # bei jedem Durchlauf erneuern, 24h Ablauf
        "client_key": os.environ["TIKTOK_CLIENT_KEY"],
        "client_secret": os.environ["TIKTOK_CLIENT_SECRET"],
        "grant_type": "refresh_token",
        "refresh_token": t["refresh_token"],            # 365 Tage Lebensdauer; rotiert
    }, headers={"Content-Type": "application/x-www-form-urlencoded"})
    r.raise_for_status()
    new = r.json()
    save(new)                                           # das NEUE refresh_token speichern
    return new["access_token"]
// node: built-in fetch, kein 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));          // rotiertes refresh_token speichern
  return n.access_token;
}

Regel: Speichere das Refresh Token und lies es bei jedem Durchlauf neu, niemals ein reines access_token. Ein hartcodiertes access_token=...-Literal ist ein garantierter Fehler innerhalb von 24 Stunden – und genau das, was verify.sh markiert.

Der vollständige Token-Austausch-Flow (Authorize-URL-Parameter, PKCE, Code-Austausch) ist in references/oauth-setup.md.

3. Ein Video veröffentlichen (init → transfer → poll)

Die Veröffentlichung besteht immer aus drei Schritten: Initialisiere die Veröffentlichung, übertrage die Bytes, polle, bis die Verarbeitung abgeschlossen ist (sie ist asynchron). Wähle zuerst den Übertragungsmodus:

SituationQuelleEndpunkt
Datei ist lokal / in deiner KontrolleFILE_UPLOAD/post/publish/video/init/
Datei ist unter einer verifizierten HTTPS-URLPULL_FROM_URL/post/publish/video/init/
Soll als Entwurf landen, den der Benutzer finalisiertFILE_UPLOAD/post/publish/inbox/video/init/

Init (FILE_UPLOAD) – gibt publish_id und eine upload_url zurück:

import math, requests

CHUNK = 10 * 1024 * 1024                      # 10 MB, innerhalb des 5–64 MB Fensters
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": "caption #fyp", "privacy_level": "SELF_ONLY"},  # öffentlich benötigt 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"]

Transfer – Sende Chunks sequentiell an upload_url mit einem Content-Range-Header. Chunk min 5 MB, max 64 MB (letzter Chunk bis 128 MB), 1–1000 Chunks; eine Datei unter 5 MB ist ein Chunk, der der Dateigröße entspricht. Jedes PUT gibt 206 (mehr zu senden) oder 201 (letzter Chunk akzeptiert) zurück:

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}",  # exakter Byte-Bereich
        })
        assert r.status_code in (206, 201), r.text     # 206 = weiter, 201 = fertig

Poll – TikTok verarbeitet asynchron; überprüfe den Status, bis PUBLISH_COMPLETE. Respektiere die Obergrenze unten – keine enge Schleife:

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)                                      # 6/min Obergrenze – schlafen, niemals rotieren

Rate Limit: 6 Anfragen/Minute pro Benutzer-Access-Token → rate_limit_exceeded. Drossle Init/Status-Aufrufe und führe Backoff durch; eine enge Status-Poll-Schleife sprengt das Budget in Sekunden.

PULL_FROM_URL erfordert, dass die Domain/der URL-Prefix im Portal verifiziert ist (nur HTTPS, keine Weiterleitungen, 1-Stunden-Download-Timeout), sonst gibt Init url_ownership_unverified zurück. Der vollständige PULL_FROM_URL-Init-Body und die Verifizierungsschritte sind in references/metrics-and-publish.md.

4. Leistung abrufen (zwei APIs, eine Regel)

Die tragende Unterscheidung: Display gibt dir Zähler; nur die Business API gibt dir Watch Time, Completion und Traffic.

# (a) Display API – nur einfache Zähler. Scope video.list, bis zu 20 IDs/Anfrage.
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()
# gibt zurück: view_count, like_count, comment_count, share_count, duration, title, create_time
# (b) Business Account API – das echte Engagement-Signal.
# Gibt die Metriken zurück, die Display NICHT kann: average_time_watched, total_time_watched,
# full_video_watched_rate (Completion), impression_sources (FYP / Following / profile /
# search), audience_countries. (Endpoint-Form in references/metrics-and-publish.md.)
Schlecht:  Erwarte average_time_watched / full_video_watched_rate von /v2/video/query/
Gut:      Zähler von Display /v2/video/query/;
          Watch Time + Completion + impression_sources von der Business Account API.

Einschränkung: Business Insight-Metriken haben eine Verzögerung von 24–48h und können von den In-App-Zahlen abweichen. Behandle einen frischen Pull als vorläufig – das Wiki-Protokoll (nächster Abschnitt) ist der Ort, an dem du sie sich setzen siehst. Der vollständige Metrik-Katalog, aufgeteilt nach API, befindet sich in references/metrics-and-publish.md.

5. Ins Wiki aufnehmen – das eigentliche Ergebnis

Ein Pull, der auf stdout ausgibt und verschwindet, ist verschwendet. Jeder Pull fügt einen datierten Eintrag unter 02-DOCS/wiki/shortform/ hinzu, plattform-namensräumig, sodass die Kontonummern zu einer durchsuchbaren Historie werden, die die Strategie-/Verpackungs-Geschwister lesen können.

02-DOCS/wiki/shortform/
  index.md                       # rollender Zeiger auf den letzten Snapshot + offene Fragen
  tiktok-account-2026-06-02.md   # datierter Kontoschnappschuss (einer pro Pull)
  videos/tiktok-<video_id>.md    # fortlaufendes Protokoll pro Video, neuester Eintrag oben

Dateinamen tragen das tiktok--Präfix, weil dasselbe shortform/-Wiki auch Instagram- und YouTube-Pulls enthalten kann – Namespacing verhindert Kollisionen zwischen Plattformen.

Vorlage für den Eintrag pro Pull. Das Frontmatter ist OKF v0.1 konform – ein nicht-leeres type ist die einzige harte Anforderung; title/tags/timestamp sind optional, aber setze sie bitte dennoch, damit die Geschwister die Einträge automatisch parsen können.

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`).

Verwandte Skills