API

API de Xonaplay

API REST para subir, procesar y entregar tus videos. Pedís un ticket de subida, subís el archivo directo al engine, y obtenés un stream HLS adaptativo (360p a 1080p) con cifrado AES-128 listo para embeber. JSON sobre HTTPS, autenticada con API keys por workspace.

Base URLhttps://api.xonaplay.com/v1

Quickstart

1

Creá una API key y autenticá tu primera llamada

Generá una API key desde el panel (Workspace → API Keys). Las keys de producción tienen el prefijo xpl_live_. Mandala como Bearer token y verificá la conexión listando tus videos.

curl https://api.xonaplay.com/v1/videos \
  -H "Authorization: Bearer xpl_live_8f3c2a9b41d7e6..." \
  -H "X-Xona-Workspace: ws_4a7f21c9"
2

Pedí un upload-ticket y subí el archivo al engine

Pedí un ticket de subida al control plane. Te devuelve un uploadUrl del engine y un token corto (X-Upload-Token) de un solo uso. Subís el archivo binario directo al engine con ese token, sin pasar por el control plane.

# 1) Pedir el ticket
curl -X POST https://api.xonaplay.com/v1/videos/upload-ticket \
  -H "Authorization: Bearer xpl_live_8f3c2a9b41d7e6..." \
  -H "X-Xona-Workspace: ws_4a7f21c9" \
  -H "Content-Type: application/json" \
  -d '{"filename":"demo.mp4","title":"Mi demo"}'
# => { "videoId":"vid_92ab", "uploadUrl":"https://engine.xonaplay.com/upload", "uploadToken":"ut_3f..." }

# 2) Subir el archivo directo al engine
curl -X POST https://engine.xonaplay.com/upload \
  -H "X-Upload-Token: ut_3f..." \
  -F "[email protected]"
3

Consultá el estado y obtené la URL HLS

Hacé polling del video (o suscribite a un webhook) hasta que status sea ready. Cuando termina la transcodificación, la respuesta incluye la URL del master.m3u8 con las variantes adaptativas, lista para tu player.

curl https://api.xonaplay.com/v1/videos/vid_92ab \
  -H "Authorization: Bearer xpl_live_8f3c2a9b41d7e6..." \
  -H "X-Xona-Workspace: ws_4a7f21c9"
# => { "id":"vid_92ab", "status":"ready",
#      "hls":"https://api.xonaplay.com/v1/hls/ws_4a7f21c9/vid_92ab/master.m3u8",
#      "variants":["360p","480p","720p","1080p"] }

Autenticación

Cada request se autentica con una API key enviada como Bearer token en el header Authorization. Las keys de producción usan el prefijo xpl_live_; las de prueba, xpl_test_. Además, indicá el workspace al que pertenecen tus recursos con el header X-Xona-Workspace (id ws_...). Tratá las keys como secretos: no las publiques en código cliente ni en el navegador. Si una key se filtra, revocala y rotala desde el panel. Las llamadas sin key válida devuelven 401; con la key correcta pero el workspace equivocado, 403.

Authorization: Bearer xpl_live_8f3c2a9b41d7e6c5a0d2
X-Xona-Workspace: ws_4a7f21c9
Content-Type: application/json

Endpoints

Auth

GET/auth/whoamiDevuelve el workspace y los permisos asociados a la API key actual.
GET/auth/usageConsumo del período: almacenamiento, minutos transcodificados y ancho de banda.

Videos

POST/videos/upload-ticketCrea un video y devuelve uploadUrl + uploadToken de un solo uso para subir al engine.
GET/videos/:idEstado del video (uploading, processing, ready, failed), metadata y URL HLS.
GET/videosLista paginada de videos del workspace, con filtros por estado y fecha.
DELETE/videos/:idElimina el video, sus variantes HLS y los assets del storage.

Playback

GET/hls/:tenant/:video/master.m3u8Playlist HLS master con las variantes adaptativas. Segmentos cifrados con AES-128.

Webhooks

POST/webhooksRegistra un endpoint para recibir eventos (video.ready, video.failed, video.deleted).
GET/webhooksLista los webhooks configurados y su estado de entrega.
DELETE/webhooks/:idElimina un webhook registrado.

API Keys

POST/api-keysCrea una nueva API key. El secreto completo se muestra una sola vez.
GET/api-keysLista las keys del workspace (prefijo y últimos 4 dígitos, sin el secreto).
DELETE/api-keys/:idRevoca una key de inmediato; las llamadas con esa key pasan a devolver 401.

Esta página resume los endpoints principales. La referencia interactiva completa, con esquemas de request/response, códigos de error y un cliente de prueba, se genera con OpenAPI (Scalar) directamente desde el engine Elysia y siempre refleja la versión en producción. La especificación OpenAPI cruda está disponible en /v1/openapi.json.