--- title: "Create Customizations" method: POST path: "/medias/{mediaId}/customizations" tags: ["Customizations"] --- # Create Customizations `POST /medias/{mediaId}/customizations` ## Request - Base URL: `https://api.wistia.com/modern` - URL: `https://api.wistia.com/modern/medias/{mediaId}/customizations` - Auth: HTTP bearer Set customizations for a video. Replaces the customizations explicitly set for this video. ## Requires api token with one of the following permissions ``` Read, update & delete anything ``` Tokens with the "Act with a team member's permissions" permission (`all:delegate_to_contact_permissions` scope) can also be used. Requests made with such a token are authorized using the permissions of the contact assigned to the token. An [expiring access token](https://docs.wistia.com/reference/post_expiring-token) created with the `all:delegate_to_contact_permissions` scope and an authorization granting the `edit` permission on this media can also be used. ## Path parameters - `mediaId` string, required ## Headers - `X-Wistia-API-Version` string, required ## Request body - object: A collection of settings you can apply to a video to change its appearance and behavior. - `autoPlay` boolean: If set to true, the video will play as soon as it’s ready. Note that autoplay might not work on some devices and browsers. - `controlsVisibleOnLoad` boolean: If set to true, controls like the big play button, playbar, volume, etc. will be visible as soon as the video is embedded. - `copyLinkAndThumbnailEnabled` boolean: If set to false, the option to “Copy Link and Thumbnail” will be removed when right-clicking on the video. - `doNotTrack` boolean: If set to true, data for each viewing session will not be tracked. - `email` string: Associate a specific email address with this video’s viewing sessions. - `endVideoBehavior` string: Determines what happens when the video ends. Options are default (stays on the last frame), reset (shows thumbnail and controls), and loop (plays again from the start). - `fakeFullscreen` boolean: If set to true, the video will try to play in a pseudo-fullscreen mode on certain mobile devices. - `fitStrategy` string: Resizes the video when there's a discrepancy between its aspect ratio and that of its parent container. Options are contain, cover, fill, and none. - `fullscreenButton` boolean: If set to true, the fullscreen button will be available as a video control. - `fullscreenOnRotateToLandscape` boolean: If set to false, the video will not automatically go to fullscreen mode on mobile when rotated to landscape. - `keyMoments` boolean: If set to false, the key moments feature will be disabled. - `muted` boolean: If set to true, the video will start in a muted state. - `playbackRateControl` boolean: If set to false, the playback speed controls in the settings menu will be hidden. - `playbar` boolean: If set to true, the playbar will be available. If set to false, it will be hidden. - `playButton` boolean: Indicates if the play button is visible. - `playerColor` string: Changes the base color of the player. Expects a hexadecimal rgb string. - `playlistLinks` boolean: Enables the use of specially crafted links on the page to associate with a video, turning them into a playlist. - `playlistLoop` boolean: If set to true and this video has a playlist, it will loop back to the first video after the last one has finished. - `playsinline` boolean: If set to false, videos will play within the native mobile player. - `playPauseNotifier` boolean: If set to false, animations for the Pause and Play symbols will be removed. - `playSuspendedOffScreen` boolean: If set to false for a muted autoplay video, the video won't pause when out of view. - `plugin` object - `videoThumbnail` object - `clickToPlayButton` boolean: If set to false, removes the “Click to Play” button on video thumbnails. - `socialbar-v1` object - `buttons` string - `showTweetCount` boolean - `tweetText` string - `height` integer - `chapters` object - `visibleOnLoad` boolean - `chapterList` object[] - `id` string - `title` string - `time` string - `deleted` string - `on` boolean - `postRoll-v1` object: Adds a Call To Action to your Video - `rewatch` boolean: If set to true, allows the video to be rewatched. - `text` string: The URL of the text to be displayed. - `link` string: The URL of the link to be displayed. - `time` union: The time when the post-roll should be displayed. Can be a string like "end" or a number representing seconds. - string - number - `autoSize` boolean: If set to true, the post-roll will automatically adjust its size. - `style` object - `backgroundColor` string: The background color of the post-roll. - `ctaType` string: The type of call-to-action to be displayed. Typically set to "text". Other options are "image" which allows for "altText", and "html". - `on` boolean: If set to true, the post-roll is enabled. - `conversionOpportunityKey` string: The key used for tracking conversion opportunities. - `captions-v1` object: Enables closed captions for the video - `on` boolean: If set to true, the captions plugin is enabled and captions controls will be available to viewers. - `onByDefault` boolean: If set to true, captions will be turned on automatically when the video loads. Only takes effect when the captions plugin is enabled. - `preload` string: Sets the video’s preload property. Possible values are metadata, auto, none, true, and false. - `qualityControl` boolean: If set to false, the video quality selector in the settings menu will be hidden. - `qualityMax` integer: Specifies the maximum quality the video will play at. - `qualityMin` integer: Specifies the minimum quality the video will play at. - `resumable` string: Determines if the video should resume from where the viewer left off. Options are true, false, and auto. - `seo` boolean: If set to true, the video’s metadata will be injected into the page’s markup for SEO. - `settingsControl` boolean: If set to true, the settings control will be available. - `silentAutoPlay` string: Determines how videos handle autoplay in contexts where normal autoplay might be blocked. Options are true, allow, and false. - `smallPlayButton` boolean - `stillUrl` string: Overrides the thumbnail image that appears before the video plays. - `time` string: Sets the starting time of the video. - `thumbnailAltText` string: Sets the Thumbnail Alt Text for the media. - `videoFoam` union: When set to true, the video will adjust its size according to its parent element. It can also be an object specifying min/max width or height. - boolean - object: Examples: ```json { "minWidth": 400, "maxWidth": 960 } ``` ```json { "minHeight": 300, "maxHeight": 450 } ``` - `minWidth` integer: Minimum width the video can be resized to. - `maxWidth` integer: Maximum width the video can be resized to. - `minHeight` integer: Minimum height the video can be resized to. - `maxHeight` integer: Maximum height the video can be resized to. - `volume` number: Sets the volume of the video. - `volumeControl` boolean: When set to true, a volume control is available over the video. - `wmode` string: If set to transparent, the background behind the player will be transparent instead of black. ## Response `201` Successful response - object - `playerColor` string: The color of the video player. - `stillUrl` string - `autoPlay` string: Whether the video should auto play or not. - `bpbTime` string - `controlsVisibleOnLoad` string - `endVideoBehavior` string: Behavior of the video at the end. - `fullscreenButton` string - `branding` string - `playbar` string - `playButton` string: Indicates if the play button is visible. - `settingsControl` string - `showCustomerLogo` string - `qualityControl` string - `playbackRateControl` string - `smallPlayButton` string - `spherical` string - `volumeControl` string - `copyLinkAndThumbnailEnabled` string - `doNotTrack` string - `email` string - `fitStrategy` string - `fullscreenOnRotateToLandscape` string - `muted` string - `playlistLinks` string - `playlistLoop` string - `playsinline` string - `playPauseNotifier` string - `playSuspendedOffScreen` string - `preload` string - `qualityMax` string - `qualityMin` string - `resumable` string - `seo` string - `silentAutoPlay` string - `time` string - `thumbnailAltText` string - `videoFoam` string - `volume` string - `wmode` string - `keyMoments` string: String representation of whether the key moments feature is enabled. - `plugin` object: Container for player plugin configurations. Plugin keys are extensible and not strictly validated; the documented sub-objects represent the most common plugins. - `passwordProtectedVideo` object - `on` string - `src` string - `challenge` string - `async` string - `videoThumbnail` object - `clickToPlayButton` string - `socialbar-v1` object - `buttons` string - `showTweetCount` string - `tweetText` string - `height` string - `chapters` object - `visibleOnLoad` string - `chapterList` object[] - `id` string - `title` string - `time` string - `deleted` string - `on` string - `postRoll-v1` object: Adds a Call To Action to your Video (response format) - `rewatch` string: String representation of whether the video can be rewatched. - `text` string: The URL of the text to be displayed. - `link` string: The URL of the link to be displayed. - `time` string: The time when the post-roll should be displayed as a string. - `autoSize` string: String representation of whether the post-roll will automatically adjust its size. - `style` object - `backgroundColor` string: The background color of the post-roll. - `ctaType` string: The type of call-to-action to be displayed. - `on` string: String representation of whether the post-roll is enabled. - `conversionOpportunityKey` string: The key used for tracking conversion opportunities. - `captions-v1` object: Captions plugin configuration (response format) - `on` string: String representation of whether the captions plugin is enabled ("true" or "false"). - `onByDefault` string: String representation of whether captions are turned on by default ("true" or "false"). - `private` object - `password_protect_on` string - `show_comments` string - `encrypted` object - `password_protect_password` string ## Other responses - `401`: Unauthorized, invalid or missing token - `403`: Forbidden, token is valid but account does not have access to feature - `500`: Internal server error ## Changes - **2026-11-03** `b86cb2a7b420`: 1 info - endpoint added [Operation history](https://skmtc.dev/wistia/apis/data-api/changes/medias/:mediaId/customizations/post.md) --- [API](https://skmtc.dev/wistia/apis/data-api.md) - [All operations](https://skmtc.dev/wistia/apis/data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/wistia/apis/data-api/revisions/b86cb2a7b420?raw)