Communitygithub.com

ericrisco/rsc-harness

Úsalo para conectar una cuenta real de TikTok al código a través de las APIs de Content Posting, Display y Business Account: OAuth, publicación de video fragmentado con sondeo de estado, y extracción de vistas, tiempo de visualización y fuentes de impresión, registrando ese rendimiento en la wiki como un registro de retroalimentación fechado. Cubre tokens de corta duración que rompen un cron, propiedad no verificada de pull-from-URL y límites de tasa. NO decide qué publicar ni cómo empaquetarlo (eso es `shortform-strategy` y `shortform-packaging`).

¿Qué es rsc-harness?

Este skill habilita la integración técnica completa con las APIs de TikTok para cuentas reales, cubriendo autenticación OAuth, publicación de videos (con carga fragmentada y sondeo de estado), y extracción de métricas de rendimiento. Está diseñado para desarrolladores y agentes de IA que necesitan conectar una cuenta de TikTok auténtica al código, gestionando tokens de corta duración, límites de tasa (6 solicitudes/minuto) y la verificación de propiedad de URL para `PULL_FROM_URL`. El skill distingue claramente entre tres APIs de TikTok: Content Posting (escritura), Display (lectura básica de contadores) y Business Account (lectura enriquecida con tiempo de visualización, finalización y fuentes de tráfico). Una vez obtenidos los datos, los ingiere en la wiki como archivos fechados (ej. `02-DOCS/wiki/shortform/tiktok-account-2026-06-02.md`), creando un registro histórico consultable que otros skills de estrategia y empaquetado pueden usar. Es parte de un ecosistema modular: no decide qué publicar ni cómo empaquetarlo, sino que proporciona el transporte y la ingesta de datos limpios. Soporta Python y JavaScript con ejemplos de código para refresh de tokens y publicación de videos.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

API de TikTok — Transporte e Ingesta para una Cuenta Real

Tú controlas el cable: autentícate en una cuenta de TikTok, publica un video, extrae los números y escríbelos en la wiki como un registro de retroalimentación duradero. No decides qué crear, cuándo publicarlo ni cómo subtitularlo — eso es responsabilidad de la familia de estrategia/empaquetado de shortform. Proporciona un transporte limpio y un registro consultable; deja que los hermanos lo interpreten.

TikTok se divide en tres APIs separadas, y una cuenta real las toca todas:

  • API de Content Posting — https://open.tiktokapis.com/v2/post/publish/... — el lado de escritura: iniciar una publicación, transferir el archivo, sondear el estado. Sujeto a auditoría.
  • API de Display — https://open.tiktokapis.com/v2/video/... — el lado de lectura económica: tu propio perfil y contadores básicos por video (view_count, like_count, comment_count, share_count).
  • API de TikTok para Empresas — el lado de lectura enriquecida: tiempo de visualización, finalización, fuentes de impresión. Se habilita a través de un portal empresarial separado, no la aplicación de desarrollador estándar.

La autenticación es OAuth v2 de usuario a través de Login Kit, nunca un token de servicio. Un ser humano es dueño de la cuenta; tú actúas en su nombre con un token de actualización. No hay un SDK oficial de TikTok — llamas a los endpoints REST directamente con cualquier cliente HTTP. Trata el token de acceso como un objeto de credencial de corta duración y actualizable, nunca como un literal codificado.

Cuándo usar / Cuándo NO

Úsalo cuando:

  • Conectes un script o agente para publicar en una cuenta: Publicación Directa o subida a borrador mediante /v2/post/publish/video/init/ (o /inbox/ para un borrador), luego FILE_UPLOAD PUT fragmentado o PULL_FROM_URL, y luego sondeo de /v2/post/publish/status/fetch/.
  • Extraigas estadísticas de videos propios de una cuenta: contadores a través de Display POST /v2/video/query/ (o /v2/video/list/); tiempo de visualización / finalización / fuente de impresión a través de la API de Business Account.
  • Construyas el bucle recurrente "obtener rendimiento → escribir en 02-DOCS/wiki/shortform/" que convierte las respuestas de la API en un registro de retroalimentación de la cuenta que los hermanos puedan leer.
  • Depures fallos específicos de TikTok: scope_not_authorized, url_ownership_unverified, rate_limit_exceeded (6 solicitudes/min), caducidad del token de acceso en 24 horas, video.publish no aprobado en auditoría, publicación privada solo para aplicaciones no auditadas.

NO lo uses cuando (dirígete al hermano que lo posee):

Lo que realmente quieresVe a
Qué publicar / cadencia / nicho / estrategia de ganchoshortform-strategy (id de catálogo)
Ideas de clips, ganchos, un backlog de temasshortform-ideation (id de catálogo)
Empaquetado de subtítulos / portada / título, marco A/Bshortform-packaging (id de catálogo)
Cortar/subtitular/renderizar el archivo de clip realshortform-editing (id de catálogo)
Renderizar un archivo de video programáticamente../remotion-video/SKILL.md
Publicar un activo en TikTok + IG + YouTube a la vez../social-publisher/SKILL.md
API de Graph / Content Publishing de Instagram../instagram-api/SKILL.md
Las dos APIs de YouTube (misma familia, otra plataforma)../youtube-api/SKILL.md
Envolver un proveedor REST arbitrario con OAuth + reintentosapi-connector-builder (id de catálogo)
Encadenar publicación → fila de Notion → Slack entre herramientasautomation-flows (id de catálogo)

En una línea: este skill autentica, llama e ingiere las APIs de Content Posting + Display + Business de TikTok en la wiki. Qué publicar y cómo empaquetarlo pertenecen a los hermanos shortform-strategy / shortform-ideation / shortform-packaging; la publicación en múltiples redes pertenece a social-publisher.

1. Configuración única (haz esto antes de cualquier código)

Una lista de verificación, porque cada paso faltante produce un error confuso y distinto más adelante:

  1. Registra una aplicación de desarrollador de TikTok en el portal de desarrolladores.
  2. Agrega los productos que necesitas: Login Kit (OAuth), API de Content Posting (publicar), API de Display (leer conteos). Insights viven en el portal separado de TikTok para Empresas — habilita también el acceso a esa cuenta si necesitas tiempo de visualización/finalización.
  3. Establece una URI de redirección exacta para el flujo OAuth.
  4. Envía la aplicación para auditoría antes de publicar contenido público. Una aplicación no auditada solo puede publicar en privado (SELF_ONLY) y solo para un conjunto limitado de usuarios de prueba. Esta es la sorpresa #1 "funciona en mi máquina, se rompe en producción" — mira la regla a continuación.
  5. Si publicas por URL (PULL_FROM_URL), verifica el dominio / prefijo de URL en el portal (TXT de DNS o prefijo de URL), o cada inicio devolverá url_ownership_unverified.

Las tres puertas son independientes. No asumas que una aprobación cubre todo:

Mal:  "Mi aplicación está aprobada, así que tanto publicación como insights funcionan."
Bien: La *auditoría* de Content Posting controla la publicación pública;
      el *ámbito* (scope) de Display (video.list) controla los conteos de videos propios;
      el *acceso* al portal empresarial controla el tiempo de visualización / finalización / fuentes de impresión.
      Tres puertas separadas — verifica cada una.

Tabla de ámbitos — solicita solo lo que el trabajo necesita:

ÁmbitoOtorgaUsar para
video.publishPublicación Directa en el feed público/post/publish/video/init/ (controlado por auditoría)
video.uploadSubida a borradores/inbox para que el usuario finalice/post/publish/inbox/video/init/
video.listLeer tus propios videos + contadores básicosDisplay POST /v2/video/query/
user.info.basicLeer perfil (open_id, nombre mostrado, avatar)POST /v2/user/info/

El tutorial completo de registro de aplicación + habilitación de productos, la puerta de auditoría y la solución de problemas de scope_not_authorized se encuentran en references/oauth-setup.md.

2. Obtén un cliente autenticado y mantén el token vivo

OAuth v2: envía al usuario a https://www.tiktok.com/v2/auth/authorize/, recibe un code en tu URI de redirección, cámbialo en https://open.tiktokapis.com/v2/oauth/token/ y almacena el token de actualización.

El ciclo de vida es el hecho fundamental: el token de acceso caduca en 24 horas (expires_in: 86400); el token de actualización dura 365 días (refresh_expires_in: 31536000) y se renueva sin necesidad de nuevo consentimiento del usuario. Por lo tanto, un cron de extracción diaria DEBE actualizar el token de acceso en cada ejecución, y una cuenta inactiva durante mucho tiempo muere silenciosamente en el límite de actualización de 365 días.

# python: REST puro, sin SDK oficial de TikTok. requests/httpx ambos funcionan.
import time, json, os, requests

TOKEN_URL = "https://open.tiktokapis.com/v2/oauth/token/"
STORE = "tiktok_token.json"   # en gitignore — contiene el refresh_token rotatorio

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={                 # actualizar cada ejecución, caducidad en 24h
        "client_key": os.environ["TIKTOK_CLIENT_KEY"],
        "client_secret": os.environ["TIKTOK_CLIENT_SECRET"],
        "grant_type": "refresh_token",
        "refresh_token": t["refresh_token"],            # vida útil de 365 días; rota
    }, headers={"Content-Type": "application/x-www-form-urlencoded"})
    r.raise_for_status()
    new = r.json()
    save(new)                                           # persistir el NUEVO refresh_token
    return new["access_token"]
// node: fetch integrado, sin 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));          // persistir el refresh_token rotado
  return n.access_token;
}

Regla: persiste el token de actualización y vuelve a leerlo en cada ejecución, nunca un access_token simple. Un literal access_token=... codificado es un fallo garantizado en 24 horas — y es exactamente lo que verify.sh señala.

El flujo completo de intercambio de tokens (parámetros de URL de autorización, PKCE, intercambio de código) está en references/oauth-setup.md.

3. Publicar un video (inicio → transferencia → sondeo)

Publicar siempre es tres pasos: iniciar la publicación, transferir los bytes, sondear hasta que el procesamiento termine (es asíncrono). Primero elige el modo de transferencia:

SituaciónFuenteEndpoint
El archivo está local / bajo tu controlFILE_UPLOAD/post/publish/video/init/
El archivo está en una URL HTTPS verificadaPULL_FROM_URL/post/publish/video/init/
Debe llegar como borrador que el usuario finalizaFILE_UPLOAD/post/publish/inbox/video/init/

Inicio (FILE_UPLOAD) — devuelve publish_id y una upload_url:

import math, requests

CHUNK = 10 * 1024 * 1024                      # 10 MB, dentro de la ventana de 5–64 MB
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"},  # público necesita auditoría
        "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"]

Transferencia — PUT fragmentos secuencialmente a upload_url con un encabezado Content-Range. Fragmento mín. 5 MB, máx. 64 MB (fragmento final hasta 128 MB), 1–1000 fragmentos; un archivo de menos de 5 MB es un fragmento igual al tamaño del archivo. Cada PUT devuelve 206 (más para enviar) o 201 (último fragmento aceptado):

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}",  # rango exacto de bytes
        })
        assert r.status_code in (206, 201), r.text     # 206 = continuar, 201 = terminado

Sondeo — TikTok procesa de forma asíncrona; verifica el estado hasta PUBLISH_COMPLETE. Respeta el límite a continuación — no hagas un bucle cerrado:

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)                                      # límite de 6/min — duerme, nunca gires

Límite de tasa: 6 solicitudes/minuto por token de acceso de usuario → rate_limit_exceeded. Regula las llamadas de inicio/estado y retrocede; un bucle cerrado de sondeo de estado consume el presupuesto en segundos.

PULL_FROM_URL requiere que el dominio/prefijo de URL esté verificado en el portal (solo HTTPS, sin redirecciones, tiempo de espera de descarga de 1 hora) o el inicio devuelve url_ownership_unverified. El cuerpo completo de inicio de PULL_FROM_URL y los pasos de verificación están en references/metrics-and-publish.md.

4. Extraer rendimiento (dos APIs, una regla)

La distinción fundamental: Display te da contadores; solo la API de Business te da tiempo de visualización, finalización y tráfico.

# (a) API de Display — solo contadores básicos. Ámbito video.list, hasta 20 ids/solicitud.
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()
# devuelve: view_count, like_count, comment_count, share_count, duration, title, create_time
# (b) API de Business Account — la señal real de engagement.
# Devuelve las métricas que Display NO puede: average_time_watched, total_time_watched,
# full_video_watched_rate (finalización), impression_sources (FYP / Siguiendo / perfil /
# búsqueda), audience_countries. (Forma del endpoint en references/metrics-and-publish.md.)
Mal:  esperar average_time_watched / full_video_watched_rate de /v2/video/query/
Bien: contadores de Display /v2/video/query/;
      tiempo de visualización + finalización + fuentes de impresión de la API de Business Account.

Advertencia: Las métricas de insights empresariales tienen un retraso de 24–48h y pueden diferir de los números en la aplicación. Trata una extracción reciente como provisional — el registro de la wiki (siguiente sección) es donde las ves asentarse. El catálogo completo de métricas dividido por API está en references/metrics-and-publish.md.

5. Ingestar en la wiki — el entregable real

Una extracción que imprime en stdout y desaparece es un desperdicio. Cada extracción añade una entrada fechada bajo 02-DOCS/wiki/shortform/, con espacio de nombres de plataforma, para que los números de la cuenta se conviertan en un historial consultable que los hermanos de estrategia/empaquetado puedan leer.

02-DOCS/wiki/shortform/
  index.md                       # puntero rodante a la última instantánea + preguntas abiertas
  tiktok-account-2026-06-02.md   # instantánea de cuenta fechada (una por extracción)
  videos/tiktok-<video_id>.md    # registro continuo por video, entrada más nueva arriba

Los nombres de archivo llevan el prefijo tiktok- porque la misma wiki shortform/ también puede contener extracciones de Instagram y YouTube — el espacio de nombres evita colisiones entre plataformas.

Plantilla de entrada por extracción. El frontmatter es conforme a OKF v0.1 — un type no vacío es el único requisito estricto; title/tags/timestamp se deducen del contexto o se establecen por omisión.

// 02-DOCS/wiki/shortform/tiktok-account-2026-06-02.md
---
type: platform-pull
platform: tiktok
accountId: "<open_id>"
timestamp: 2026-06-02T10:20:30Z
pullScope: all-public
---

# TikTok — Instantánea de Cuenta (2026-06-02)

## Resumen Agregado

- **Vistas totales (últimos 28 días):** ...
- **Tiempo de visualización total (últimos 28 días):** ...
- **Tasa de finalización media:** ...
- **Videos publicados (últimos 28 días):** ...

## Videos Publicados Recientemente

| Video ID | Título | Vistas | Me gusta | Comentarios | Tasa de finalización | Fuente principal |
| --- | --- | --- | --- | --- | --- | --- |
| `<id>` | `...` | ... | ... | ... | ... | `FYP` |

## Desglose de Fuentes de Tráfico

...

## Preguntas Abiertas / Anomalías

- El video `<id>` muestra una tasa de finalización del 120 % — ¿error de la API o conteo doble?

El index.md en ese directorio rastrea la última instantánea e imita la estructura pulls-and-tags de los motores wiki: un archivo de puntero ligero que los hermanos leen para encontrar el estado actual sin escanear directorios.

videos/tiktok-<video_id>.md es un registro continuo — cada extracción añade una nueva línea o sección en la parte superior. Así, el historial de rendimiento de un video es auto-contenido y navegable. Formato exacto en references/metrics-and-publish.md.

Ejemplo de flujo completo (publicar y registrar)

# 1. Obtener un token de acceso vivo
token = access_token()

# 2. Iniciar publicación
init_resp = requests.post("https://open.tiktokapis.com/v2/post/publish/video/init/", ...)

# 3. Transferir archivo (fragmentos)
...

# 4. Sondear hasta completar
...

# 5. Extraer métricas
counts = requests.post("https://open.tiktokapis.com/v2/video/query/", ...)
business_data = ...  # llamada a API de Business Account

# 6. Escribir registro en wiki
os.makedirs("02-DOCS/wiki/shortform", exist_ok=True)
with open(f"02-DOCS/wiki/shortform/tiktok-account-{date.today()}.md", "w") as f:
    f.write(f"---\ntype: platform-pull\n...\n---\n")

Referencias

DocumentoContenido
references/oauth-setup.mdRegistro de aplicación, tutorial de productos, flujo de autorización, PKCE, intercambio de código, renovación de token, solución de problemas de scope_not_authorized
references/metrics-and-publish.mdCatálogo completo de métricas para Display y Business APIs, cuerpo de inicio de PULL_FROM_URL, verificación de URL, formato de registro wiki por video, comportamiento de retraso (lag) de insights

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 relacionados