API local

La API local comparte el mismo servidor que tus overlays de OBS, en el puerto de overlay. Responde únicamente a programas ejecutados en este mismo ordenador y solo cuando aportan tu token de acceso.

Activar la API local

El botón Generar token sustituye el token actual. Cualquier script que continúe utilizando el token anterior quedará desconectado al instante, mientras que los overlays y tus conexiones en directo seguirán funcionando sin alteración. También puedes escribir tu propio token personalizado: entre 32 y 256 letras, dígitos, guiones o guiones bajos.

El puerto se configura en la misma tarjeta en Puerto del servidor compartido. Un cambio de puerto surte efecto tras reiniciar Vfinity. Si el puerto está ocupado al arrancar, Vfinity elegirá otro libre y la tarjeta mostrará la dirección real en uso.

Comprobación de solicitudes

Cada petición HTTP y cada conexión por WebSocket requiere la siguiente cabecera:

Authorization: Bearer TU_TOKEN

Una solicitud se rechaza si proviene de otro equipo, si el token falta o es incorrecto, o si contiene una cabecera Origin de navegador web. Esta última regla impide que una página web llame a la API, incluso si se abre en este mismo equipo. Utiliza scripts locales o herramientas de escritorio con capacidad de definir cabeceras.

Activar el acceso de overlay para OBS en otro PC no expone la API a la red local, y la clave de acceso de overlay no es un token de API.

Vfinity debe estar en ejecución para responder peticiones. Permanecer oculto en la bandeja del sistema cuenta como ejecución activa; si cierras la app, nada estará escuchando.

Enviar peticiones por HTTP

Envía siempre la cabecera Content-Type: application/json con cada petición POST. El cuerpo puede ocupar hasta 64 KiB.

# ¿Qué puedo ejecutar?
curl -H "Authorization: Bearer TU_TOKEN" http://127.0.0.1:21424/api/state

# Añadir 30 segundos al temporizador del subathon
curl -X POST http://127.0.0.1:21424/api/command \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"timer.add","args":30}'

$headers = @{ Authorization = "Bearer TU_TOKEN" }

# ¿Qué puedo ejecutar?
Invoke-RestMethod -Uri http://127.0.0.1:21424/api/state -Headers $headers

# Añadir 30 segundos al temporizador del subathon
Invoke-RestMethod -Method Post -Uri http://127.0.0.1:21424/api/command `
  -Headers $headers -ContentType "application/json" `
  -Body '{"name":"timer.add","args":30}'

Activar uno de tus eventos

Configura un evento con el disparador Disparador de la API y asígnale un Nombre del disparador, luego envía ese nombre mediante POST a /api/trigger. La coincidencia de nombre no distingue entre mayúsculas y minúsculas.

curl -X POST http://127.0.0.1:21424/api/trigger \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"alarma_raid","data":{"message":"Llega una raid","level":3}}'

Cada campo dentro de data se convierte en una variable de plantilla accesible por los pasos del evento; por ejemplo, un paso de voz con {message} pronunciará "Llega una raid". Se admiten cadenas de texto, números y valores booleanos; los objetos y listas anidados no se procesan. El nombre de un campo debe comenzar por una letra, y se tienen en cuenta los primeros 50 campos.

La respuesta {"ok":true} confirma que Vfinity aceptó el disparador. Un evento desactivado, en pausa o retenido por su tiempo de espera no ejecutará acciones; escucha el evento actionResult en el WebSocket si necesitas verificar qué pasos se ejecutaron realmente.

Ejecutar un comando

Los comandos son las mismas acciones con nombre empleadas por los atajos globales, los botones del Panel rápido y los pasos de acción de comando. GET /api/state enumera los comandos ofrecidos en ese momento exacto, dado que algunos solo existen mientras su módulo correspondiente está activo.

{ "name": "control.panic" }
{ "name": "deck.press", "args": "Aplausos" }
{ "name": "giveaway.draw" }
{ "name": "sceneCard.showBrb" }
{ "name": "mapping.trigger", "args": "TU_ID_DE_EVENTO" }

mapping.trigger ejecuta uno de tus eventos como si su disparador se hubiera activado externamente, respondiendo con cuántas ejecuciones inició. Acepta el ID del evento o el nombre de su disparador de API. Para obtener el ID, haz clic derecho sobre el evento en la pestaña Eventos y elige Copiar ID del evento.

Todos los comandos se detallan junto a sus argumentos en Comandos.

Conectar TikTok LIVE desde un script

{
  "name": "tiktok.connect",
  "args": { "username": "tu_usuario", "autoRejoin": true, "waitForLive": true }
}

La respuesta {"ok":true,"result":{"accepted":true}} significa que la solicitud se encoló, no que ya se haya entrado a la sala LIVE. Consulta el bloque tiktok de /api/state, o el evento tiktokStatus en el WebSocket: room.state indicará "connected" en cuanto Vfinity esté dentro de la emisión.

Escuchar mediante WebSocket

Conéctate a ws://127.0.0.1:21424/api/ws incluyendo la misma cabecera Authorization. Puedes enviar las mismas peticiones que por HTTP (cada una con un requestId que tú elijas) y Vfinity te transmitirá en directo todo lo que suceda en tu directo.

// npm install ws
const WebSocket = require('ws');

const socket = new WebSocket('ws://127.0.0.1:21424/api/ws', {
  headers: { Authorization: 'Bearer TU_TOKEN' },
});

socket.on('open', () => {
  socket.send(JSON.stringify({ type: 'command', name: 'timer.add', args: 30, requestId: '1' }));
});

socket.on('message', (raw) => {
  const message = JSON.parse(raw);
  if (message.type === 'event' && message.event === 'gift') {
    console.log(`${message.data.nickname} envió ${message.data.giftName}`);
  }
  if (message.type === 'response') console.log(message.requestId, message.data);
});

Mensajes que envías

{ "type": "state", "requestId": "1" }
{ "type": "command", "name": "timer.add", "args": 30, "requestId": "2" }
{ "type": "trigger", "name": "alarma_raid", "data": {}, "requestId": "3" }

Cada petición recibe su correspondiente respuesta: {"type":"response","requestId":"2","data":{"ok":true}}.

Mensajes que envía Vfinity

Un regalo que forma parte de un combo (giftType 1) envía actualizaciones mientras dura la racha. Actúa sobre él únicamente cuando repeatEnd no sea false, tal como hace el motor interno de Vfinity. Las marcas de tiempo son milisegundos en formato Unix.

El flujo es exclusivamente en tiempo real: no hay retransmisión de eventos pasados, y un cliente que lea con demasiada lentitud puede perder mensajes.

Límites y códigos de error

Las copias de seguridad estándar no incluyen el token y se restauran con la API desactivada por seguridad. Marca Incluir contraseñas y tokens al crear la copia si deseas preservarlo.

Hacer que Vfinity se conecte a tu servidor

La tarjeta API de disparadores, también bajo Avanzado, invierte la dirección de la conexión: Vfinity se conecta como cliente al servidor WebSocket que tú ejecutes. Resulta idóneo para servidores preexistentes, como los de un videojuego o un bot.

Activa API de disparadores, introduce el Host del WebSocket y el Puerto del WebSocket, y haz clic en Conectar API. Tu servidor podrá enviar mensajes como:

{ "type": "trigger", "name": "alarma_raid", "data": { "message": "Llega una raid" } }
{ "type": "command", "name": "timer.add", "args": 30, "requestId": "abc-1" }
{ "type": "request", "requestType": "event_list", "requestId": "abc-2" }

Un comando con requestId recibe una respuesta del tipo {"type":"response","requestType":"command","requestId":"abc-1","data":{"name":"timer.add","ok":true}}. event_list responde con todos los eventos que poseen disparador de API, sus pasos y su estado de activación, mientras que stats devuelve los estados de conexión y recuentos de eventos.

Cualquier proceso con acceso a tu servidor podrá ejecutar estos comandos; mantén el servidor confinado en este equipo o implementa tu propia capa de autenticación previa.

Relacionado