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.
https://api.xonaplay.com/v1Quickstart
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"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]"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/jsonEndpoints
Auth
/auth/whoamiRetorna o workspace e as permissões associados à API key atual./auth/usageConsumo do período: armazenamento, minutos transcodificados e banda.Videos
/videos/upload-ticketCria um vídeo e retorna uploadUrl + uploadToken de uso único para o engine./videos/:idStatus do vídeo (uploading, processing, ready, failed), metadados e URL HLS./videosLista paginada dos vídeos do workspace, com filtros por status e data./videos/:idRemove o vídeo, suas variantes HLS e os assets no storage.Playback
/hls/:tenant/:video/master.m3u8Playlist HLS master com as variantes adaptativas. Segmentos com criptografia AES-128.Webhooks
/webhooksRegistra um endpoint para receber eventos (video.ready, video.failed, video.deleted)./webhooksLista os webhooks configurados e seu status de entrega./webhooks/:idRemove um webhook registrado.API Keys
/api-keysCria uma nova API key. O segredo completo é exibido apenas uma vez./api-keysLista as keys do workspace (prefixo e últimos 4 dígitos, nunca o segredo)./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.