Communitygithub.com

ericrisco/rsc-harness

Use para conectar uma conta real do TikTok ao código por meio das APIs de Postagem de Conteúdo, Exibição e Contas Comerciais — OAuth, publicação de vídeo fragmentada com sondagem de status e obtenção de visualizações, tempo de exibição e fontes de impressão, registrando esse desempenho no wiki como um registro de feedback datado. Abrange tokens de curta duração que quebram um cron, propriedade não verificada de pull-from-URL e limites de taxa. NÃO é o que postar ou como empacotar (isso é para `shortform-strategy` e `shortform-packaging`).

O que é rsc-harness?

O skill ericrisco/rsc-harness é uma ferramenta especializada para desenvolvedores e agentes de IA que precisam interagir diretamente com as APIs do TikTok a partir de contas reais. Ele gerencia todo o ciclo de vida de transporte e ingestão de dados, desde a autenticação OAuth (com refresh tokens que duram 365 dias e access tokens que expiram em 24 horas) até a publicação de vídeos via upload fragmentado (FILE_UPLOAD) ou pull de URL (PULL_FROM_URL), com sondagem de status assíncrona. Além disso, o skill coleta métricas de desempenho usando duas APIs distintas: a API de Exibição (Display) para contadores básicos (visualizações, curtidas, comentários) e a API de Negócios (Business) para métricas avançadas como tempo de exibição, taxa de conclusão e fontes de tráfego (FYP, Seguindo, Perfil). O resultado de cada coleta é registrado de forma persistente no wiki do projeto, em arquivos datados e organizados por plataforma, criando um histórico consultável para outros skills (como `shortform-strategy` e `shortform-packaging`) interpretarem. O skill é compatível com Python e JavaScript, usa REST diretamente (sem SDK oficial) e impõe boas práticas como refresh de token a cada execução, tratamento de limites de taxa (6 requisições/minuto) e separação clara de responsabilidades.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

API do TikTok — Transporte + Ingestão para uma Conta Real

Você controla o fio: autentique-se em uma conta do TikTok, publique vídeo, obtenha os números e escreva esses números no wiki como um registro de feedback durável. Você não decide o que fazer, quando postar ou como escrever a legenda — isso é da família shortform strategy/packaging. Entregue um transporte limpo e um log consultável; deixe os irmãos interpretarem.

O TikTok é dividido em três APIs separadas, e uma conta real toca em todas as três:

  • API de Postagem de Conteúdo — https://open.tiktokapis.com/v2/post/publish/... — o lado de escrita: iniciar uma publicação, transferir o arquivo, sondar o status. Controlado por auditoria.
  • API de Exibição — https://open.tiktokapis.com/v2/video/... — o lado de leitura barata: seu próprio perfil e contadores básicos por vídeo (view_count, like_count, comment_count, share_count).
  • API do TikTok para Negócios — o lado de leitura rica: tempo de exibição, conclusão, fontes de impressão. Habilitada por meio de um portal de negócios separado, não pelo aplicativo de desenvolvedor padrão.

A autenticação é OAuth v2 do usuário via Login Kit, nunca um token de serviço. Um humano é o dono da conta; você age em nome dele com um token de atualização. Não há SDK oficial do TikTok — você chama os endpoints REST diretamente com qualquer cliente HTTP. Trate o token de acesso como um objeto de credencial de curta duração e atualizável, nunca um literal fixo.

Quando usar / Quando NÃO usar

Use quando:

  • Conectando um script ou agente para publicar em uma conta: Postagem Direta ou upload para rascunho via /v2/post/publish/video/init/ (ou /inbox/ para um rascunho), depois FILE_UPLOAD PUT fragmentado ou PULL_FROM_URL, em seguida, sonde /v2/post/publish/status/fetch/.
  • Obtendo estatísticas de vídeo da própria conta: contadores via Exibição POST /v2/video/query/ (ou /v2/video/list/); tempo de exibição / conclusão / fonte de impressão via API de Conta Comercial.
  • Construindo o loop recorrente "buscar desempenho → escrever em 02-DOCS/wiki/shortform/" que transforma respostas da API em um log de feedback da conta que os irmãos podem ler.
  • Depurando falhas específicas do TikTok: scope_not_authorized, url_ownership_unverified, rate_limit_exceeded (6 req/min), expiração do token de acesso em 24 horas, video.publish não aprovado na auditoria, postagem privada apenas para aplicativos não auditados.

NÃO use quando (encaminhe para o irmão que é responsável por isso):

Você realmente querVá para
O que postar / cadência / nicho / estratégia de ganchoshortform-strategy (id do catálogo)
Ideias de clipes, ganchos, um backlog de tópicosshortform-ideation (id do catálogo)
Legenda / capa / título / empacotamento, enquadramento A/Bshortform-packaging (id do catálogo)
Cortar / legendar / renderizar o arquivo de clipe realshortform-editing (id do catálogo)
Renderizar um arquivo de vídeo programaticamente../remotion-video/SKILL.md
Postar um ativo no TikTok + IG + YouTube de uma só vez../social-publisher/SKILL.md
API do Graph / Publicação de Conteúdo do Instagram../instagram-api/SKILL.md
Duas APIs do YouTube (mesma família, outra plataforma)../youtube-api/SKILL.md
Encapsular um provedor REST arbitrário com OAuth + tentativasapi-connector-builder (id do catálogo)
Encadear publicar → linha do Notion → Slack entre ferramentasautomation-flows (id do catálogo)

Uma linha: este skill autentica, chama e ingere as APIs de Postagem de Conteúdo + Exibição + Negócios do TikTok no wiki. O que postar e como empacotar pertencem aos irmãos shortform-strategy / shortform-ideation / shortform-packaging; a postagem em várias redes pertence ao social-publisher.

1. Configuração única (faça isso antes de qualquer código)

Uma lista de verificação, porque cada etapa ausente produz uma falha confusa e distinta posteriormente:

  1. Registre um aplicativo de desenvolvedor do TikTok no portal do desenvolvedor.
  2. Adicione os produtos que você precisa: Login Kit (OAuth), API de Postagem de Conteúdo (publicar), API de Exibição (ler contagens). Os Insights estão no portal separado do TikTok for Business — habilite o acesso a essa conta também se precisar de tempo de exibição/conclusão.
  3. Defina um URI de redirecionamento exato para o fluxo OAuth.
  4. Envie o aplicativo para auditoria antes de postar conteúdo público. Um aplicativo não auditado só pode postar de forma privada (SELF_ONLY) e apenas para um conjunto limitado de usuários de teste. Esta é a surpresa nº 1 "funciona na minha máquina, quebra em produção" — veja a regra abaixo.
  5. Se você publicar por URL (PULL_FROM_URL), verifique o domínio / prefixo de URL no portal (DNS TXT ou prefixo de URL), ou cada inicialização retornará url_ownership_unverified.

Os três portões são independentes. Não presuma que uma aprovação cobre tudo:

Ruim: "Meu aplicativo foi aprovado, então publicar e insights funcionam."
Bom: A *auditoria* de Postagem de Conteúdo controla a publicação pública;
     O *escopo* da Exibição (video.list) controla as contagens dos próprios vídeos;
     O *acesso* ao portal de Negócios controla o tempo de exibição / conclusão / fontes de impressão.
     Três portões separados — verifique cada um.

Tabela de escopos — solicite apenas o que o trabalho precisa:

EscopoConcedeUso
video.publishPostagem Direta no feed público/post/publish/video/init/ (controlado por auditoria)
video.uploadUpload para rascunhos/inbox para o usuário finalizar/post/publish/inbox/video/init/
video.listLer seus próprios vídeos + contadores básicosExibição POST /v2/video/query/
user.info.basicLer perfil (open_id, nome de exibição, avatar)POST /v2/user/info/

O passo a passo completo de registro de aplicativo + habilitação de produto, o portão de auditoria e a solução de problemas scope_not_authorized estão em references/oauth-setup.md.

2. Obtenha um cliente autenticado e mantenha o token ativo

OAuth v2: envie o usuário para https://www.tiktok.com/v2/auth/authorize/, receba um code no seu URI de redirecionamento, troque-o em https://open.tiktokapis.com/v2/oauth/token/ e armazene o refresh token.

O ciclo de vida é o fato central: o access token expira em 24 horas (expires_in: 86400); o refresh token dura 365 dias (refresh_expires_in: 31536000) e renova sem novo consentimento do usuário. Portanto, um cron de busca diária DEVE atualizar o access token a cada execução, e uma conta inativa por muito tempo morre silenciosamente no limite de renovação de 365 dias.

# python: REST puro, sem SDK oficial do TikTok. requests/httpx ambos funcionam.
import time, json, os, requests

TOKEN_URL = "https://open.tiktokapis.com/v2/oauth/token/"
STORE = "tiktok_token.json"   # gitignored — contém o refresh_token rotativo

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={                 # atualizar a cada execução, expira em 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 dias; gira
    }, headers={"Content-Type": "application/x-www-form-urlencoded"})
    r.raise_for_status()
    new = r.json()
    save(new)                                           # persistir o NOVO refresh_token
    return new["access_token"]
// node: fetch nativo, sem 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 refresh_token rotacionado
  return n.access_token;
}

Regra: persista o refresh token e releia-o a cada execução, nunca um access_token simples. Um literal access_token=... codificado é uma falha garantida em 24 horas — e é exatamente o que verify.sh sinaliza.

O fluxo completo de troca de token (parâmetros de URL de autorização, PKCE, troca de código) está em references/oauth-setup.md.

3. Publicar um vídeo (iniciar → transferir → sondar)

Publicar é sempre três etapas: iniciar a publicação, transferir os bytes, sondar até que o processamento termine (é assíncrono). Escolha o modo de transferência primeiro:

SituaçãoFonteEndpoint
O arquivo está local / sob seu controleFILE_UPLOAD/post/publish/video/init/
O arquivo está em uma URL HTTPS verificadaPULL_FROM_URL/post/publish/video/init/
Deve cair como rascunho para o usuário finalizarFILE_UPLOAD/post/publish/inbox/video/init/

Iniciar (FILE_UPLOAD) — retorna publish_id e um upload_url:

import math, requests

CHUNK = 10 * 1024 * 1024                      # 10 MB, dentro da janela 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": "legenda #fyp", "privacy_level": "SELF_ONLY"},  # público precisa de auditoria
        "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"]

Transferir — PUT fragmentos sequencialmente para upload_url com um cabeçalho Content-Range. Fragmento mín. 5 MB, máx. 64 MB (fragmento final até 128 MB), 1–1000 fragmentos; um arquivo abaixo de 5 MB é um fragmento igual ao tamanho do arquivo. Cada PUT retorna 206 (mais para enviar) ou 201 (último fragmento aceito):

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}",  # intervalo exato de bytes
        })
        assert r.status_code in (206, 201), r.text     # 206 = continuar, 201 = concluído

Sondar — O TikTok processa de forma assíncrona; verifique o status até PUBLISH_COMPLETE. Respeite o limite abaixo — não faça loop apertado:

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 de 6/min — durma, nunca gire

Limite de taxa: 6 requisições/minuto por access token do usuário → rate_limit_exceeded. Limite as chamadas de init/status e recue; um loop apertado de sondagem de status explode o orçamento em segundos.

PULL_FROM_URL exige que o domínio/prefixo de URL seja verificado no portal (HTTPS apenas, sem redirecionamentos, tempo limite de download de 1 hora) ou o init retorna url_ownership_unverified. O corpo completo do PULL_FROM_URL init e as etapas de verificação estão em references/metrics-and-publish.md.

4. Obter desempenho (duas APIs, uma regra)

A distinção fundamental: A Exibição fornece contadores; apenas a API de Negócios fornece tempo de exibição, conclusão e tráfego.

# (a) API de Exibição — apenas contadores básicos. escopo video.list, até 20 ids/requisição.
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()
# retorna: view_count, like_count, comment_count, share_count, duration, title, create_time
# (b) API de Conta Comercial — o sinal real de engajamento.
# Retorna as métricas que a Exibição NÃO PODE: average_time_watched, total_time_watched,
# full_video_watched_rate (conclusão), impression_sources (FYP / Seguindo / perfil /
# pesquisa), audience_countries. (Forma do endpoint em references/metrics-and-publish.md.)
Ruim:  esperar average_time_watched / full_video_watched_rate de /v2/video/query/
Bom: contadores da Exibição /v2/video/query/;
      tempo de exibição + conclusão + impression_sources da API de Conta Comercial.

Ressalva: As métricas de insight de negócios têm um atraso de 24–48h e podem diferir dos números no aplicativo. Trate uma coleta recente como provisória — o log do wiki (próxima seção) é onde você observa a estabilização. O catálogo completo de métricas dividido por API está em references/metrics-and-publish.md.

5. Ingerir no wiki — a entrega real

Uma coleta que imprime no stdout e desaparece é desperdiçada. Cada coleta anexa uma entrada datada em 02-DOCS/wiki/shortform/, com namespace de plataforma, para que os números da conta se tornem um histórico consultável que os irmãos de estratégia/embalagem podem ler.

02-DOCS/wiki/shortform/
  index.md                       # ponteiro rolante para o snapshot mais recente + perguntas em aberto
  tiktok-account-2026-06-02.md   # snapshot datado da conta (um por coleta)
  videos/tiktok-<video_id>.md    # log contínuo por vídeo, entrada mais recente no topo

Os nomes de arquivo carregam o prefixo tiktok- porque o mesmo wiki shortform/ também pode conter coletas do Instagram e YouTube — o namespace evita colisões entre plataformas.

Modelo de entrada por coleta. O frontmatter é conforme OKF v0.1 — um type não vazio é o único requisito obrigatório; title/tags/`timestamp

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

Habilidades Relacionadas