Referencia · v1

API de TikTok Archives

Acceso programático a perfiles, regiones, descargas de videos, sliders y audios, historias y directos, con chat y video en tiempo real y avisos automáticos cuando un usuario empieza a transmitir.

Base URLhttps://geometryamerica.xyz/api/v1
Obtener una API key Ver métodos
15métodos
100peticiones / día
10keys por cuenta
SSEtiempo real

Tu panel

Gestiona tus API keys, revisa tu consumo del día y tus avisos de directo.

Cargando…

Inicio rápido

Tres pasos para hacer tu primera petición.

01

Crea tu cuenta

Es la misma cuenta de la web. Si ya tienes una, inicia sesión.

02

Genera una key

Desde tu panel. Puedes tener hasta 10, por ejemplo una por proyecto.

03

Haz la petición

Envía la key en el header Authorization y llama a cualquier método.

curl "https://geometryamerica.xyz/api/v1/getProfileInfo?username=tiktok" \
  -H "Authorization: Bearer TU_API_KEY"

Autenticación

Todas las peticiones a /api/v1/ requieren una API key. Se puede enviar de tres formas:

Header (recomendado)
Authorization: Bearer ga_…
Header alternativo
X-API-Key: ga_…
Parámetro
?key=ga_… — para EventSource (chat) y reproductores de video, que no pueden enviar headers.
Trata tu key como una contraseña. No la incluyas en el código de una web pública ni en repositorios. Si se filtra, revócala desde tu panel y crea otra; el resto de tus keys siguen funcionando.

Límites y cuota

El límite es global por cuenta: todas tus keys comparten las mismas 100 peticiones diarias.

Peticiones
100 al día por cuenta. Se reinicia a las 00:00 UTC.
Qué cuenta
Solo las respuestas correctas (2xx). Los errores no consumen cuota.
Chat y stream
getLiveChat y getLiveBuffer cuentan 1 al conectar y 1 más por cada hora abierta. Sin cuota, la conexión se cierra.
Conexiones abiertas
Máximo 3 simultáneas por cuenta (chat, stream, liveEvents y clips de downloadLive).
Keys
Hasta 10 activas por cuenta.
Avisos de directo
Hasta 10 callbacks por cuenta; los avisos por callback no consumen cuota. Con liveEvents conectarse es gratis y cada aviso entregado cuenta 1.
Descargas
Los enlaces que devuelve downloadTT son válidos 6 horas y no consumen cuota.

Cada respuesta incluye tu consumo en el campo usage y en estos headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 2026-10-05T00:00:00Z

Errores

Las respuestas JSON tienen siempre la misma estructura. En caso de error, ok es false y error.code identifica la causa.

{
  "ok": false,
  "error": { "code": "not_live", "message": "@usuario no está en directo ahora mismo." },
  "usage": { "used": 13, "limit": 100, "remaining": 87, "resetsAt": "2026-10-05T00:00:00Z" }
}
HTTPcodeSignificado
400bad_requestFalta un parámetro o no es válido.
401missing_key · invalid_keyNo se envió la key, o es incorrecta o está revocada.
404not_found · not_liveEl recurso no existe, o el usuario no está en directo.
409limit_reached · duplicateMáximo de callbacks alcanzado, o el callback ya existe.
410expired_linkEl enlace de descarga caducó; vuelve a llamar a downloadTT.
429daily_limit · too_many_streamsCuota diaria agotada, o 3 conexiones abiertas.
502upstream_errorTikTok no respondió. Reintenta en unos segundos.
503busyEl servidor tiene demasiados directos abiertos a la vez.

Métodos

Todos responden JSON, salvo los que devuelven archivos o streams.

Formato de los avisos

Cuando un usuario vigilado con liveCallback empieza o termina un directo, se envía un POST con JSON a tu URL. La comprobación se hace cada minuto. liveEvents entrega este mismo cuerpo por SSE. ongoing es true cuando el directo ya estaba en curso al empezar a vigilar al usuario.

Evento live_start

{
  "event": "live_start",
  "username": "usuario",
  "roomId": "7312345678901234567",
  "title": "En vivo",
  "cover": "https://…/cover.jpeg",
  "startedAt": "2026-10-04T18:02:11Z",
  "url": "https://www.tiktok.com/@usuario/live",
  "watchUrl": "https://geometryamerica.xyz/live/usuario",
  "ongoing": false,
  "callbackId": 4,
  "sentAt": "2026-10-04T18:02:40Z"
}

Evento live_end

{
  "event": "live_end",
  "username": "usuario",
  "roomId": "7312345678901234567",
  "title": "En vivo",
  "startedAt": "2026-10-04T18:02:11Z",
  "endedAt": "2026-10-04T19:40:03Z",
  "durationSeconds": 5872,
  "url": "https://www.tiktok.com/@usuario/live",
  "callbackId": 4,
  "sentAt": "2026-10-04T19:41:10Z"
}
Webhooks de Discord. Si la URL es https://discord.com/api/webhooks/…, el aviso se envía como mensaje de Discord con la portada del directo, sin necesidad de programar nada.

Verificar la firma

Cada aviso incluye X-GA-Signature: sha256=…, un HMAC-SHA256 del cuerpo con el secret que recibiste al crear el callback.

// Node.js (Express)
const crypto = require('crypto');
app.post('/aviso', express.raw({ type: '*/*' }), (req, res) => {
  const esperado = 'sha256=' + crypto
    .createHmac('sha256', process.env.GA_SECRET)
    .update(req.body).digest('hex');
  if (req.get('X-GA-Signature') !== esperado)
    return res.sendStatus(401);
  const ev = JSON.parse(req.body);
  console.log(ev.event, ev.username);
  res.sendStatus(200);
});
# Python (Flask)
import hmac, hashlib, os
from flask import Flask, request

app = Flask(__name__)

@app.post("/aviso")
def aviso():
    firma = "sha256=" + hmac.new(
        os.environ["GA_SECRET"].encode(),
        request.get_data(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(firma, request.headers.get("X-GA-Signature", "")):
        return "", 401
    ev = request.get_json()
    print(ev["event"], ev["username"])
    return "", 200

Tu servidor debe responder 2xx en menos de 8 segundos. Tras 20 fallos consecutivos el callback se pausa; puedes reactivarlo con «Probar» desde tu panel.