LosPerris Twitch API Docs

Bienvenido a la guía oficial. Aquí encontrarás todo lo necesario para configurar tus comandos y herramientas automáticas para tu chat de Twitch.

Compatible: Nightbot, StreamElements, Fossabot y Wizebot.

Actualización: Datos frescos cada 30 segundos de forma automática.

Tu API Key

La mayoría de los endpoints requieren una apiKey para funcionar. Puedes obtener tu Clave Permanente conectando tu cuenta en el panel principal.

¿Por qué verificar? Solo necesitamos permiso para leer datos públicos y crear clips en tu nombre. No tocamos tu clave de transmisión ni datos privados.

Perfil y Seguridad

Gestiona tu identidad en la plataforma y configura las opciones de seguridad de tu cuenta.

API Key Manager: Visualiza y regenera tu clave permanente usada para los comandos de chat.

Resumen de Actividad: Consulta tus estadísticas de uso: total de requests, latencia promedio, tasa de éxito y actividad reciente.

Tu Identidad: Visualiza tu ID de Twitch, nombre de usuario y fecha de última conexión. Puedes copiar tu ID directamente desde el panel.

Zona de Peligro: Accede a opciones críticas como el borrado de cuenta mediante el toggle de advertencia y confirmación de seguridad.

Rate Limiting

Para asegurar la estabilidad del servicio para todos los streamers, aplicamos los siguientes límites:

Requests / minuto

Req/min (Pesados)

60s

Caché de Respuestas

Headers de Respuesta: Incluimos X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset en todas las respuestas para que puedas monitorear tu consumo.

¿Qué son los Endpoints "Pesados"?

Son comandos complejos que requieren mayor procesamiento o realizar múltiples consultas en tiempo real a los servidores de Twitch. Actualmente, los endpoints pesados son:

Crear Clip: Requiere verificar el estado del stream en vivo y ordenar el procesamiento del video.
Shoutout (!so): Descarga la información actualizada del canal objetivo y su categoría de juego en tiempo real.
Tendencias: Analiza grandes volúmenes de mensajes recientes del chat para calcular estadísticas.

Nota: Los comandos normales (como Followage, Bola 8 o Ruleta) son muy rápidos y utilizan el límite general de 60 peticiones por minuto.

¡Comienza Ya!

Obtén tu API Key

Inicia sesión en el Dashboard para obtener tu clave única.

Elige un Comando

Selecciona una herramienta del menú (ej: Bola 8, Clips).

Copia y Pega

Copia el código generado y pégalo en el chat de tu bot.

¡Disfruta!

Tus viewers ya pueden interactuar con los nuevos comandos.

Followage

Calcula cuánto tiempo lleva un usuario siguiendo al canal.

Parámetro	Requerido	Descripción
channel	Sí	Canal a verificar.
user	Sí	Usuario seguidor.
template	No	Personaliza la respuesta. Ej: `{user} lleva {time} siguiendo a {channel}`

!addcom !followage $(urlfetch {baseURL}/api/twitch/followage?channel=$(channel)&user=$(touser)&apiKey=TU_API_KEY)

Crear Clip

Genera un clip instantáneo del canal. Ideal para capturar momentos épicos.

Requisito: El canal debe estar en vivo para poder generar un clip. Si el stream está offline, recibirás un mensaje de error.

1 Selecciona tu bot2 Copia el código3 Pega en el chat

!addcom !clip 🎬 Clip creado por $(user): $(urlfetch {baseURL}/api/twitch/create-clip?channel=$(channel)&apiKey=TU_API_KEY)

Shoutout (!so)

Genera un mensaje promocionando a otro streamer con su último juego y enlace directo.

GET/api/twitch/shoutout?channel={canal}&touser={objetivo}&apiKey={clave}&template={mensaje}

Parámetro	Tipo	Descripción
template	String	(Opcional) Personaliza el shoutout. Variables: `{user}`, `{game}`, `{url}`.

!addcom !so 📢 $(urlfetch {baseURL}/api/twitch/shoutout?channel=$(channel)&touser=$(touser)&apiKey=TU_API_KEY)

Tendencias

¿Qué está es lo más comentado en tu chat? Esta herramienta analiza los mensajes en vivo y genera un ranking (Top 10) de las palabras o emotes más repetidos.

Uso ideal: Mide el "hype" de un momento específico o descubre qué emote está spameando tu comunidad. Incluye un temporizador para sesiones de análisis.

Stalker

Tu centro de inteligencia. Investiga a cualquier usuario de Twitch al instante para obtener contexto rápido.

Uso ideal: Verifica cuándo se creó una cuenta, cuánto tiempo lleva siguiendo el canal y lee sus últimos mensajes en el chat (logs).

Ruleta

La herramienta definitiva para sorteos y giveaways en tu stream.

Lógica Híbrida: Puedes crear una lista manual de opciones o dejar que la API cargue automáticamente a los usuarios activos del chat en tiempo real.

Bola 8 Mágica (IA)

Respuestas místicas (o sarcásticas) a tus preguntas.

GET/api/twitch/minigames/magic8?question={pregunta}&mood={tono}&apiKey={clave}

Dato	Tipo	Info
`question`	String	La pregunta que quieres hacer a la Bola 8.
`mood`	String	Tono de personalidad: `classic`, `sarcastic`, `toxic`, `helpful`.
`apiKey`	String	Tu Clave Permanente del panel.

!addcom !8ball 🎱 $(user) pregunta: $(query) | La Bola 8 dice: $(urlfetch {baseURL}/api/twitch/minigames/magic8?question=$(query)&mood=sarcastic&apiKey=TU_API_KEY)

Ruleta Rusa

Un juego de alto riesgo para tu chat. Los usuarios prueban su suerte con un revólver virtual de 6 recámaras. Si pierden, reciben un Timeout real.

GET/api/twitch/minigames/russian?user={usuario}&apiKey={clave}

Cuidado: Este comando puede expulsar temporalmente a tus usuarios. Úsalo bajo tu propio riesgo.

!addcom !russian $(urlfetch {baseURL}/api/twitch/minigames/russian?user=$(user)&apiKey=TU_API_KEY)

Duelo

Desafía a otros usuarios a un duelo a muerte (simulado). El ganador se lleva la gloria.

GET/api/twitch/minigames/duel?challenger={retador}&target={oponente}&apiKey={clave}

Parámetros

Dato	Info
`target`	El usuario al que quieres desafiar (ej: @Nightbot).
`challenger`	El usuario que inicia el duelo (opcional).

!addcom !duel $(urlfetch {baseURL}/api/twitch/minigames/duel?challenger=$(user)&target=$(touser)&apiKey=TU_API_KEY)

Listar Clips

Endpoint para desarrolladores: obtén un JSON con los clips más recientes.

GET/api/twitch/dashboard/get-clips?channel={canal}&apiKey={tu_api_key}&limit=10

Ejemplo de Respuesta (JSON)

[
  {
    "id": "FastLivelyTroutKeepo-7s9...",
    "url": "https://clips.twitch.tv/FastLivelyTroutKeepo-7s9...",
    "embed_url": "https://clips.twitch.tv/embed?clip=FastLivelyTroutKeepo-7s9...",
    "broadcaster_id": "12345678",
    "broadcaster_name": "LosPerris",
    "creator_id": "87654321",
    "creator_name": "ponss",
    "video_id": "22334455",
    "game_id": "509658",
    "language": "es",
    "title": "Epic Win en vivo!",
    "view_count": 420,
    "created_at": "2023-11-20T19:30:00Z",
    "thumbnail_url": "https://clips-media-assets2.twitch.tv/...",
    "duration": 30.5,
    "vod_offset": 480
  }
]

Respuestas HTTP

La API utiliza códigos de estado HTTP estándar para indicar el resultado de las solicitudes.

Código	Estado	Descripción
200	OK	Solicitud procesada correctamente.
401	Unauthorized	Tu API Key es inválida.
400	Bad Request	Faltan parámetros obligatorios (ej: canal, usuario).
404	Not Found	El canal o usuario especificado no existe en Twitch.
500 / 503	Server Error	Error interno o red inestable temporalmente.