Services

Video

A video field is an object, not a URL. Render the player for any value with a videoId — unless it failed.

A full brief for whoever builds against this.

Your customer uploads a video in the dashboard and it is encoded into several qualities. Your site gets an object with an embed URL and a thumbnail URL, both on the same host as everything else. There is no media host to configure, allow-list or add to your image settings — and the player plays from the moment the upload lands, while the qualities are still being prepared.

The field

json

{
  "videoId": "8f2a1c34-...",
  "status": "playable",
  "playable": true,
  "embedUrl": "https://app.cnter.com/embed/8f2a1c34-...",
  "thumbnailUrl": "https://app.cnter.com/api/public/video/8f2a1c34-.../thumbnail",
  "duration": 92,
  "title": "Kitchen tour",
  "width": 1920,
  "height": 1080
}

Field	Notes
`embedUrl`	The player. Use it in an iframe, as given.
`status`	One of `queued`, `processing`, `encoding`, `finished`, `playable`, `failed`. Only `failed` should change what you render.
`playable`	Informational: whether the first prepared quality is ready. Not a render gate — the player already plays before this flips (see below).
`thumbnailUrl`	An ordinary image URL.
`duration`	Seconds. 0 until the video has been analysed.
`title`	What your customer named it.
`width` / `height`	Pixel dimensions, for sizing the frame. 0 until analysed.

Playing it

tsx

{field.videoId && field.status !== 'failed' && (
  <iframe
    src={field.embedUrl}
    allowFullScreen
    allow="autoplay; encrypted-media; picture-in-picture; fullscreen"
    style={{ width: '100%', aspectRatio: '16/9', border: 0 }}
  />
)}

That is the whole integration. The player adapts quality to the viewer's connection on its own, so someone on a phone gets a smaller stream than someone on fibre without you doing anything.

While it is still encoding

Render the player anyway — that is the point. A freshly uploaded video plays from the original file while the qualities are being prepared, and the prepared versions take over on their own. During the brief window before the upload itself has landed, the player shows a neutral waiting state and starts by itself. There is nothing to poll and nothing to check except failed.

Thumbnails

GET/api/public/video/{videoId}/thumbnailPublic

The poster frame as an ordinary image.

It works in an img tag, from a server-side fetch, and through an image optimiser alike. Public and keyless, so it needs no proxy.

It is also the right poster for a lazily loaded player: render the thumbnail, swap in the iframe on click, and the page does not carry a video player it may never need.