VideoResponse Object

VideoResponse objects represent video assets in the FacePop platform. These objects contain essential information about video content, including identifiers, streaming URLs, and thumbnail images that are used in FacePop widgets.

VideoResponse objects are typically returned by video-related API endpoints and are referenced by FacePop objects to display video content in interactive video elements.

VideoResponse Type Definition

Below is the TypeScript type definition for the VideoResponse object. This defines the structure and properties that make up a video resource in the FacePop API.

/**
 * Represents a video asset in the FacePop platform.
 * This object contains all the necessary information to display and stream a video.
 */
export type VideoResponse = {
    /**
     * A unique identifier for this specific video.
     * e.g., 'vid-xyz789abc'
     */
    id: string;

    /**
     * The identifier of the company account this video belongs to.
     */
    companyId: string;

    /**
     * The identifier of the FacePop widget this video is associated with.
     * This links the video to a specific FacePop configuration.
     */
    facepopId: string;

    /**
     * The identifier of the content library this video belongs to.
     * Videos can be organized in libraries for better management.
     */
    libraryId: string;

    /**
     * The URL to the HLS (HTTP Live Streaming) manifest file.
     * This m3u8 file contains information about available video quality variants
     * and is used by video players to stream adaptive content.
     */
    m3u8: string;

    /**
     * Collection of thumbnail images for the video.
     * These are displayed before the video plays or in preview contexts.
     */
    thumbnail: {
        /**
         * URL to a static image thumbnail (usually JPG or PNG).
         * Used as the default preview image for the video.
         */
        static: string;
        
        /**
         * URL to an animated thumbnail (usually GIF).
         * Provides a brief preview of the video content with motion.
         */
        animated: string;
    }

    /**
     * Timestamp when this video was created or last updated.
     * Format is standard unix time.
     */
    ts: string;
}

VideoResponse Object Example

Here's an example of a complete VideoResponse object in JSON format, illustrating how the properties are structured in an actual API response.

{
  "id": "vid-7890def123",
  "companyId": "comp-abcd1234",
  "facepopId": "fp-xyz5678",
  "libraryId": "lib-uvw9012",
  "m3u8": "https://stream.facepop.io/videos/abcd1234/welcome_video/master.m3u8",
  "thumbnail": {
    "static": "https://cdn.facepop.io/thumbnails/welcome_video_poster.jpg",
    "animated": "https://cdn.facepop.io/thumbnails/welcome_video_preview.gif"
  },
  "ts": "2025-01-15T14:32:00Z"
}

Using VideoResponse Objects

VideoResponse objects are primarily used in the following contexts:

• • When retrieving video assets through the FacePop API.
• • In conjunction with FacePop objects where the VideoResponse provides the actual video content source.
• • For displaying video thumbnails in content management interfaces.
• • When integrating FacePop widgets with custom video players that consume HLS streams.

The m3u8 property is particularly important as it points to the HLS manifest that enables adaptive streaming, allowing videos to play at the optimal quality based on the viewer's network conditions.