Importing videos

The import API pulls a video from a URL you control — an S3 object, a signed link, any direct HTTPS file — into your Livepush video library. It runs on its own host: https://vod-web-import-api.livepush.io.

Imports are a two-step flow. You cannot skip the first step.

1. Inspect the source #

Inspection reads the remote file's headers and container metadata and returns an id that represents the inspected source.

curl -X POST 'https://vod-web-import-api.livepush.io/inspector/get_metadata' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example-bucket.s3.amazonaws.com/keynote.mp4"}'

The response reports duration, size, container, and the video and audio codecs. Check these before transferring — a file the inspector cannot read is a file the import will fail on, and you find out in milliseconds instead of after a multi-gigabyte transfer.

2. Start the transfer #

Pass the id from step 1 along with the zone the video should land in and the name it should carry in the library.

curl -X POST 'https://vod-web-import-api.livepush.io/transfers/new' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "meta_xxxxxxxxxxxx",
    "zone": "eu-central",
    "videoName": "Keynote 2026"
  }'

The call returns immediately. The transfer itself is asynchronous.

3. Poll until it disappears #

curl -X GET 'https://vod-web-import-api.livepush.io/transfers/queued' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

This returns imports that are queued or processing, each with a progress value and a status. Completion is signalled by absence: when your video ID is no longer in the list, the import has finished and the asset is in the VOD library, where Get user videos will return it.

Poll on a sensible interval — every 5 to 10 seconds is plenty for a transfer measured in minutes.

async function waitForImport(videoId, { intervalMs = 8000, timeoutMs = 3_600_000 } = {}) {
  const deadline = Date.now() + timeoutMs;

  while (Date.now() < deadline) {
    const queued = await getQueuedTransfers();
    const entry = queued.find((item) => item.id === videoId);

    if (!entry) return 'complete';
    if (entry.status === 'error') throw new Error(`Import failed for ${videoId}`);

    await new Promise((resolve) => setTimeout(resolve, intervalMs));
  }

  throw new Error(`Import timed out for ${videoId}`);
}

Guard the loop with a deadline. Absence means success, so a bug that drops the entry for any other reason would otherwise leave you polling forever.

Using the imported video #

Once the video is in the library it behaves like any other asset — attach it to a pre-recorded stream playlist and schedule it.