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), luegoFILE_UPLOADPUT fragmentado oPULL_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.publishno 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 quieres | Ve a |
|---|---|
| Qué publicar / cadencia / nicho / estrategia de gancho | shortform-strategy (id de catálogo) |
| Ideas de clips, ganchos, un backlog de temas | shortform-ideation (id de catálogo) |
| Empaquetado de subtítulos / portada / título, marco A/B | shortform-packaging (id de catálogo) |
| Cortar/subtitular/renderizar el archivo de clip real | shortform-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 + reintentos | api-connector-builder (id de catálogo) |
| Encadenar publicación → fila de Notion → Slack entre herramientas | automation-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:
- Registra una aplicación de desarrollador de TikTok en el portal de desarrolladores.
- 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.
- Establece una URI de redirección exacta para el flujo OAuth.
- 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. - 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:
| Ámbito | Otorga | Usar para |
|---|---|---|
video.publish | Publicación Directa en el feed público | /post/publish/video/init/ (controlado por auditoría) |
video.upload | Subida a borradores/inbox para que el usuario finalice | /post/publish/inbox/video/init/ |
video.list | Leer tus propios videos + contadores básicos | Display POST /v2/video/query/ |
user.info.basic | Leer 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ón | Fuente | Endpoint |
|---|---|---|
| El archivo está local / bajo tu control | FILE_UPLOAD | /post/publish/video/init/ |
| El archivo está en una URL HTTPS verificada | PULL_FROM_URL | /post/publish/video/init/ |
| Debe llegar como borrador que el usuario finaliza | FILE_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
| Documento | Contenido |
|---|---|
references/oauth-setup.md | Registro 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.md | Catá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 |