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), depoisFILE_UPLOADPUT fragmentado ouPULL_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.publishnã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 quer | Vá para |
|---|---|
| O que postar / cadência / nicho / estratégia de gancho | shortform-strategy (id do catálogo) |
| Ideias de clipes, ganchos, um backlog de tópicos | shortform-ideation (id do catálogo) |
| Legenda / capa / título / empacotamento, enquadramento A/B | shortform-packaging (id do catálogo) |
| Cortar / legendar / renderizar o arquivo de clipe real | shortform-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 + tentativas | api-connector-builder (id do catálogo) |
| Encadear publicar → linha do Notion → Slack entre ferramentas | automation-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:
- Registre um aplicativo de desenvolvedor do TikTok no portal do desenvolvedor.
- 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.
- Defina um URI de redirecionamento exato para o fluxo OAuth.
- 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. - 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:
| Escopo | Concede | Uso |
|---|---|---|
video.publish | Postagem Direta no feed público | /post/publish/video/init/ (controlado por auditoria) |
video.upload | Upload para rascunhos/inbox para o usuário finalizar | /post/publish/inbox/video/init/ |
video.list | Ler seus próprios vídeos + contadores básicos | Exibição POST /v2/video/query/ |
user.info.basic | Ler 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ção | Fonte | Endpoint |
|---|---|---|
| O arquivo está local / sob seu controle | FILE_UPLOAD | /post/publish/video/init/ |
| O arquivo está em uma URL HTTPS verificada | PULL_FROM_URL | /post/publish/video/init/ |
| Deve cair como rascunho para o usuário finalizar | FILE_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