API › Catalogs

Backdrops

The hand-picked loops behind a take: the public set, its wire shape, and how a doc keys one.

A backdrop is the loop that plays behind a take's card: a vos animation the platform has baked once, hand-picked into a small set. The set is public, so a studio session reads it signed out and an agent writes a backdrop into a doc with one call and no credential.

The set

GET vos.so/api/backdrops returns the ready rows in the platform's order:

JSON
{
  "backdrops": [
    {
      "id": "…",
      "slug": "soft-beams",
      "title": "Soft Beams",
      "duration": 10,
      "width": 1920,
      "height": 1080,
      "ground": "#a7b2d1",
      "vosId": "…",
      "urls": {
        "1080p": "https://assets.vos.so/backdrops/soft-beams/1080p.webm",
        "2k": "https://assets.vos.so/backdrops/soft-beams/2k.webm",
        "poster": "https://assets.vos.so/backdrops/soft-beams/poster.webp"
      }
    }
  ]
}
  • duration is the loop's length, the period the vos authored as its own config.duration. It is a fact of the asset, never a number you choose.
  • ground is the loop's average colour. Write it into frame.background so the frame before the first decoded frame, the reduced-motion still and the offline fallback all land on the loop's own colour.
  • 2k is present when that bake landed; exports at 2k and 4K pick it.
  • URLs are absolute and immutable. A doc that keys one keeps playing it after the row leaves the set.

In a doc

JSON
"frame": { "background": "#a7b2d1",
           "backgroundMedia": { "kind": "video",
             "key": "https://assets.vos.so/backdrops/soft-beams/1080p.webm",
             "duration": 10, "dim": 0 } }

On the CLI, --background <slug> on render and frames resolves the slug through this endpoint and writes exactly that. A URL still works, for a loop of your own.

Your own vos as a backdrop

In the studio, the Backdrop panel's From your projects picker, under the Animated tab, takes any vos you own, a take included. The platform bakes it into a loop at the vos's own period (a take's first 30 seconds) on the fleet, rated per day; the preview plays while the loop lands. Keys never ask for that render: an agent writes a URL from this set instead.