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), dannFILE_UPLOADchunked PUT oderPULL_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.publishnicht genehmigt, nicht geprüfte App nur private Posts.
NICHT verwenden, wenn (weiterleiten an die zuständige Schwesterfähigkeit):
| Du willst eigentlich | Gehe zu |
|---|---|
| Was posten / Kadenz / Nische / Hook-Strategie | shortform-strategy (Katalog-ID) |
| Clip-Ideen, Hooks, ein Themen-Backlog | shortform-ideation (Katalog-ID) |
| Bildunterschrift / Cover / Titel-Verpackung, A/B-Framing | shortform-packaging (Katalog-ID) |
| Die eigentliche Clip-Datei schneiden/beschriften/rendern | shortform-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ßen | api-connector-builder (Katalog-ID) |
| Veröffentlichen → Notion-Zeile → Slack über Tools verketten | automation-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:
- Registriere eine TikTok-Entwickler-App im Entwicklerportal.
- 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.
- Setze eine exakte Redirect-URI für den OAuth-Flow.
- 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. - 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 Initurl_ownership_unverifiedzurü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:
| Scope | Gewährt | Verwendung für |
|---|---|---|
video.publish | Direkter Post in den öffentlichen Feed | /post/publish/video/init/ (prüfungsgesteuert) |
video.upload | Upload in Entwürfe/Inbox für den Benutzer zum Fertigstellen | /post/publish/inbox/video/init/ |
video.list | Eigene Videos + einfache Zähler lesen | Display POST /v2/video/query/ |
user.info.basic | Profil 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:
| Situation | Quelle | Endpunkt |
|---|---|---|
| Datei ist lokal / in deiner Kontrolle | FILE_UPLOAD | /post/publish/video/init/ |
| Datei ist unter einer verifizierten HTTPS-URL | PULL_FROM_URL | /post/publish/video/init/ |
| Soll als Entwurf landen, den der Benutzer finalisiert | FILE_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.