API

API do Xonaplay

Uma API REST para enviar, processar e entregar seus vídeos. Você pede um ticket de upload, envia o arquivo direto para o engine e recebe um stream HLS adaptativo (360p a 1080p) com criptografia AES-128 pronto para incorporar. JSON sobre HTTPS, autenticado com API keys por workspace.

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

Quickstart

1

Crie uma API key e autentique sua primeira chamada

Gere uma API key no painel (Workspace → API Keys). As keys de produção têm o prefixo xpl_live_. Envie-a como Bearer token e confirme a conexão listando seus vídeos.

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

Peça um upload-ticket e envie o arquivo ao engine

Peça um ticket de upload ao control plane. Ele retorna uma uploadUrl do engine e um token curto de uso único (X-Upload-Token). Você envia o arquivo binário direto ao engine com esse token, sem passar pelo control plane.

# 1) Pedir o 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":"Meu demo"}'
# => { "videoId":"vid_92ab", "uploadUrl":"https://engine.xonaplay.com/upload", "uploadToken":"ut_3f..." }

# 2) Enviar o arquivo direto ao engine
curl -X POST https://engine.xonaplay.com/upload \
  -H "X-Upload-Token: ut_3f..." \
  -F "[email protected]"
3

Consulte o status e obtenha a URL HLS

Faça polling do vídeo (ou assine um webhook) até que status seja ready. Quando a transcodificação termina, a resposta inclui a URL do master.m3u8 com as variantes adaptativas, pronta para o seu 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"] }

Autenticação

Cada requisição é autenticada com uma API key enviada como Bearer token no header Authorization. As keys de produção usam o prefixo xpl_live_; as de teste, xpl_test_. Além disso, informe o workspace ao qual seus recursos pertencem pelo header X-Xona-Workspace (id ws_...). Trate as keys como segredos: nunca as inclua em código do cliente nem as exponha no navegador. Se uma key vazar, revogue e gere outra no painel. Chamadas sem uma key válida retornam 401; uma key válida no workspace errado retorna 403.

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

Endpoints

Auth

GET/auth/whoamiRetorna o workspace e as permissões associados à API key atual.
GET/auth/usageConsumo do período: armazenamento, minutos transcodificados e banda.

Videos

POST/videos/upload-ticketCria um vídeo e retorna uploadUrl + uploadToken de uso único para o engine.
GET/videos/:idStatus do vídeo (uploading, processing, ready, failed), metadados e URL HLS.
GET/videosLista paginada dos vídeos do workspace, com filtros por status e data.
DELETE/videos/:idRemove o vídeo, suas variantes HLS e os assets no storage.

Playback

GET/hls/:tenant/:video/master.m3u8Playlist HLS master com as variantes adaptativas. Segmentos com criptografia AES-128.

Webhooks

POST/webhooksRegistra um endpoint para receber eventos (video.ready, video.failed, video.deleted).
GET/webhooksLista os webhooks configurados e seu status de entrega.
DELETE/webhooks/:idRemove um webhook registrado.

API Keys

POST/api-keysCria uma nova API key. O segredo completo é exibido apenas uma vez.
GET/api-keysLista as keys do workspace (prefixo e últimos 4 dígitos, nunca o segredo).
DELETE/api-keys/:idRevoga uma key imediatamente; chamadas com ela passam a retornar 401.

Esta página resume os endpoints principais. A referência interativa completa, com esquemas de request/response, códigos de erro e um cliente de teste, é gerada com OpenAPI (Scalar) diretamente do engine Elysia e sempre reflete o que está em produção. A especificação OpenAPI bruta está disponível em /v1/openapi.json.