# Quickstart

XonaPlay encodes your videos to HLS and gives you a link any HLS player can
play: hls.js, Safari, AVPlayer, ExoPlayer, VLC or your own. There is no SDK.
You make one HTTP call and hand the URL to the player.

## 1. Get a playback URL

```bash
curl https://api.xonaplay.com/v1/videos/{VIDEO_ID}/playback
```

```json
{
  "status": "ok",
  "data": {
    "video_id": "0f8e2c7a-5d1b-4c3e-9a77-2b1f0c9d4e21",
    "short_id": "9KfR2mQx",
    "hls_url": "https://play.xonaplay.com/hls/t/Xk3qL9…/master.m3u8",
    "original_url": "https://…",
    "poster_url": "https://play.xonaplay.com/hls/t/Xk3qL9…/poster",
    "thumbnails_url": "https://play.xonaplay.com/hls/t/Xk3qL9…/thumbnails/thumbnails.vtt",
    "embed_url": "https://xonaplay.com/v/9KfR2mQx",
    "expires_at": "2026-10-09T03:00:00.000Z",
    "security": "protected",
    "delivery": "hls",
    "duration_sec": 3600
  }
}
```

`{VIDEO_ID}` is the video `id` or its `short_id` (the one in
`xonaplay.com/v/{short_id}`).

`original_url` is the file exactly as you uploaded it. Play `hls_url` unless you
know your player supports the format; see [Original or HLS](/playback#original-or-hls).

- **Public video, workspace on Open or Protected:** call it without a key, from
  your site or your app.
- **Private video, or workspace on Strict:** call it from your backend with your
  secret key. See [Authentication](#authentication).

## 2. Play it

```js
import Hls from "hls.js"

const video = document.querySelector("video")
const { data } = await fetch(playbackUrl).then((r) => r.json())

if (video.canPlayType("application/vnd.apple.mpegurl")) {
  video.src = data.hls_url // Safari
} else {
  const hls = new Hls()
  hls.loadSource(data.hls_url)
  hls.attachMedia(video)
}
```

Audio tracks and subtitles come inside the playlist, so your player shows them
without extra work.

## 3. Recover when it fails

Links expire on purpose. When the player hits a fatal error, ask for a new
`hls_url` and resume at the same second. Read [Playback](/playback#reload) for
the exact rule; every recipe already includes it.

## Authentication {#authentication}

Create a secret key in the dashboard: **Settings → API**. You see it once.

```bash
curl https://api.xonaplay.com/v1/videos/{VIDEO_ID}/playback \
  -H "Authorization: Bearer $XONAPLAY_SECRET_KEY"
```

- Keep the key on your server. Never ship it in a web page or a mobile app.
- A key acts on its whole workspace. Revoke it from the dashboard at any time.

## No code? Use the iframe

```html
<iframe src="https://xonaplay.com/v/9KfR2mQx" allow="autoplay; fullscreen" allowfullscreen></iframe>
```

The `embed_url` from `/playback` already carries our player, ads and
analytics, and it refreshes its own link when it expires.