--- updatedAt: 2026-04-20T20:26:21.000Z agentTools: projectIndex: https://docs.wistia.com/llms.txt --- # Create Customizations 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. # OpenAPI definition ````json { "openapi": "3.1.1", "info": { "title": "Data API", "description": "Wistia Data API", "version": "2026.09.0" }, "servers": [ { "url": "https://api.wistia.com/modern" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Customizations" } ], "paths": { "/medias/{mediaId}/customizations": { "post": { "summary": "Create Customizations", "x-speakeasy-group": "customizations", "x-speakeasy-name-override": "create", "description": "Set customizations for a video. Replaces the customizations explicitly set for this video.\n\n## Requires api token with one of the following permissions\n```\nRead, update & delete anything\n```\n\nTokens with the \"Act with a team member's permissions\" permission\n(`all:delegate_to_contact_permissions` scope) can also be used. Requests\nmade with such a token are authorized using the permissions of the\ncontact assigned to the token.\n\nAn [expiring access token](https://docs.wistia.com/reference/post_expiring-token)\ncreated with the `all:delegate_to_contact_permissions` scope and an\nauthorization granting the `edit` permission on this media can also be used.\n", "parameters": [ { "name": "mediaId", "in": "path", "description": "The hashed ID of the video.", "required": true, "schema": { "type": "string" } }, { "name": "X-Wistia-API-Version", "in": "header", "required": true, "schema": { "type": "string", "default": "2026-09" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "unevaluatedProperties": false, "type": "object", "description": "A collection of settings you can apply to a video to change its appearance and\nbehavior.\n", "properties": { "autoPlay": { "description": "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.", "type": "boolean" }, "controlsVisibleOnLoad": { "description": "If set to true, controls like the big play button, playbar, volume, etc. will be visible as soon as the video is embedded.", "type": "boolean" }, "copyLinkAndThumbnailEnabled": { "description": "If set to false, the option to “Copy Link and Thumbnail” will be removed when right-clicking on the video.", "type": "boolean" }, "doNotTrack": { "description": "If set to true, data for each viewing session will not be tracked.", "type": "boolean" }, "email": { "description": "Associate a specific email address with this video’s viewing sessions.", "type": "string" }, "endVideoBehavior": { "description": "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).", "type": "string" }, "fakeFullscreen": { "description": "If set to true, the video will try to play in a pseudo-fullscreen mode on certain mobile devices.", "type": "boolean" }, "fitStrategy": { "description": "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.", "type": "string" }, "fullscreenButton": { "description": "If set to true, the fullscreen button will be available as a video control.", "type": "boolean" }, "fullscreenOnRotateToLandscape": { "description": "If set to false, the video will not automatically go to fullscreen mode on mobile when rotated to landscape.", "type": "boolean" }, "keyMoments": { "description": "If set to false, the key moments feature will be disabled.", "type": "boolean" }, "muted": { "description": "If set to true, the video will start in a muted state.", "type": "boolean" }, "playbackRateControl": { "description": "If set to false, the playback speed controls in the settings menu will be hidden.", "type": "boolean" }, "playbar": { "description": "If set to true, the playbar will be available. If set to false, it will be hidden.", "type": "boolean" }, "playButton": { "description": "Indicates if the play button is visible.", "type": "boolean" }, "playerColor": { "description": "Changes the base color of the player. Expects a hexadecimal rgb string.", "type": "string" }, "playlistLinks": { "description": "Enables the use of specially crafted links on the page to associate with a video, turning them into a playlist.", "type": "boolean" }, "playlistLoop": { "description": "If set to true and this video has a playlist, it will loop back to the first video after the last one has finished.", "type": "boolean" }, "playsinline": { "description": "If set to false, videos will play within the native mobile player.", "type": "boolean" }, "playPauseNotifier": { "description": "If set to false, animations for the Pause and Play symbols will be removed.", "type": "boolean" }, "playSuspendedOffScreen": { "description": "If set to false for a muted autoplay video, the video won't pause when out of view.", "type": "boolean" }, "plugin": { "unevaluatedProperties": false, "type": "object", "properties": { "videoThumbnail": { "unevaluatedProperties": false, "type": "object", "properties": { "clickToPlayButton": { "description": "If set to false, removes the “Click to Play” button on video thumbnails.", "type": "boolean" } } }, "socialbar-v1": { "unevaluatedProperties": false, "type": "object", "properties": { "buttons": { "type": "string" }, "showTweetCount": { "type": "boolean" }, "tweetText": { "type": "string" }, "height": { "type": "integer" } } }, "chapters": { "unevaluatedProperties": false, "type": "object", "properties": { "visibleOnLoad": { "type": "boolean" }, "chapterList": { "type": "array", "items": { "unevaluatedProperties": false, "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "time": { "type": "string" }, "deleted": { "type": "string" } } } }, "on": { "type": "boolean" } } }, "postRoll-v1": { "unevaluatedProperties": false, "description": "Adds a Call To Action to your Video", "type": "object", "properties": { "rewatch": { "description": "If set to true, allows the video to be rewatched.", "type": "boolean" }, "text": { "description": "The URL of the text to be displayed.", "type": "string" }, "link": { "description": "The URL of the link to be displayed.", "type": "string" }, "time": { "unevaluatedProperties": false, "description": "The time when the post-roll should be displayed. Can be a string like \"end\" or a number representing seconds.", "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "autoSize": { "description": "If set to true, the post-roll will automatically adjust its size.", "type": "boolean" }, "style": { "unevaluatedProperties": false, "type": "object", "properties": { "backgroundColor": { "description": "The background color of the post-roll.", "type": "string", "examples": [ "#303030" ] } } }, "ctaType": { "description": "The type of call-to-action to be displayed. Typically set to \"text\". Other options are \"image\" which allows for \"altText\", and \"html\".", "type": "string", "examples": [ "text" ] }, "on": { "description": "If set to true, the post-roll is enabled.", "type": "boolean" }, "conversionOpportunityKey": { "description": "The key used for tracking conversion opportunities.", "type": "string" } } }, "captions-v1": { "unevaluatedProperties": false, "description": "Enables closed captions for the video", "type": "object", "properties": { "on": { "description": "If set to true, the captions plugin is enabled and captions controls will be available to viewers.", "type": "boolean" }, "onByDefault": { "description": "If set to true, captions will be turned on automatically when the video loads. Only takes effect when the captions plugin is enabled.", "type": "boolean" } } } } }, "preload": { "description": "Sets the video’s preload property. Possible values are metadata, auto, none, true, and false.", "type": "string" }, "qualityControl": { "description": "If set to false, the video quality selector in the settings menu will be hidden.", "type": "boolean" }, "qualityMax": { "description": "Specifies the maximum quality the video will play at.", "type": "integer" }, "qualityMin": { "description": "Specifies the minimum quality the video will play at.", "type": "integer" }, "resumable": { "description": "Determines if the video should resume from where the viewer left off. Options are true, false, and auto.", "type": "string" }, "seo": { "description": "If set to true, the video’s metadata will be injected into the page’s markup for SEO.", "type": "boolean" }, "settingsControl": { "description": "If set to true, the settings control will be available.", "type": "boolean" }, "silentAutoPlay": { "description": "Determines how videos handle autoplay in contexts where normal autoplay might be blocked. Options are true, allow, and false.", "type": "string" }, "smallPlayButton": { "type": "boolean" }, "stillUrl": { "description": "Overrides the thumbnail image that appears before the video plays.", "type": "string" }, "time": { "description": "Sets the starting time of the video.", "type": "string" }, "thumbnailAltText": { "description": "Sets the Thumbnail Alt Text for the media.", "type": "string" }, "videoFoam": { "unevaluatedProperties": false, "description": "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.", "anyOf": [ { "type": "boolean", "examples": [ true ] }, { "type": "object", "unevaluatedProperties": false, "properties": { "minWidth": { "description": "Minimum width the video can be resized to.", "type": "integer" }, "maxWidth": { "description": "Maximum width the video can be resized to.", "type": "integer" }, "minHeight": { "description": "Minimum height the video can be resized to.", "type": "integer" }, "maxHeight": { "description": "Maximum height the video can be resized to.", "type": "integer" } }, "description": "Examples:\n```json\n{\n \"minWidth\": 400,\n \"maxWidth\": 960\n}\n```\n```json\n{\n \"minHeight\": 300,\n \"maxHeight\": 450\n}\n```\n" } ] }, "volume": { "description": "Sets the volume of the video.", "type": "number" }, "volumeControl": { "description": "When set to true, a volume control is available over the video.", "type": "boolean" }, "wmode": { "description": "If set to transparent, the background behind the player will be transparent instead of black.", "type": "string" } } } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "unevaluatedProperties": false, "type": "object", "properties": { "playerColor": { "description": "The color of the video player.", "type": "string" }, "stillUrl": { "type": "string" }, "autoPlay": { "description": "Whether the video should auto play or not.", "type": "string" }, "bpbTime": { "type": "string" }, "controlsVisibleOnLoad": { "type": "string" }, "endVideoBehavior": { "description": "Behavior of the video at the end.", "type": "string" }, "fullscreenButton": { "type": "string" }, "branding": { "type": "string" }, "playbar": { "type": "string" }, "playButton": { "description": "Indicates if the play button is visible.", "type": "string" }, "settingsControl": { "type": "string" }, "showCustomerLogo": { "type": "string" }, "qualityControl": { "type": "string" }, "playbackRateControl": { "type": "string" }, "smallPlayButton": { "type": "string" }, "spherical": { "type": "string" }, "volumeControl": { "type": "string" }, "copyLinkAndThumbnailEnabled": { "type": "string" }, "doNotTrack": { "type": "string" }, "email": { "type": "string" }, "fitStrategy": { "type": "string" }, "fullscreenOnRotateToLandscape": { "type": "string" }, "muted": { "type": "string" }, "playlistLinks": { "type": "string" }, "playlistLoop": { "type": "string" }, "playsinline": { "type": "string" }, "playPauseNotifier": { "type": "string" }, "playSuspendedOffScreen": { "type": "string" }, "preload": { "type": "string" }, "qualityMax": { "type": "string" }, "qualityMin": { "type": "string" }, "resumable": { "type": "string" }, "seo": { "type": "string" }, "silentAutoPlay": { "type": "string" }, "time": { "type": "string" }, "thumbnailAltText": { "type": "string" }, "videoFoam": { "type": "string" }, "volume": { "type": "string" }, "wmode": { "type": "string" }, "keyMoments": { "description": "String representation of whether the key moments feature is enabled.", "type": "string" }, "plugin": { "unevaluatedProperties": true, "description": "Container for player plugin configurations. Plugin keys are extensible and\nnot strictly validated; the documented sub-objects represent the most\ncommon plugins.\n", "type": "object", "properties": { "passwordProtectedVideo": { "unevaluatedProperties": false, "type": "object", "properties": { "on": { "type": "string" }, "src": { "type": "string" }, "challenge": { "type": "string" }, "async": { "type": "string" } } }, "videoThumbnail": { "unevaluatedProperties": false, "type": "object", "properties": { "clickToPlayButton": { "type": "string" } } }, "socialbar-v1": { "unevaluatedProperties": false, "type": "object", "properties": { "buttons": { "type": "string" }, "showTweetCount": { "type": "string" }, "tweetText": { "type": "string" }, "height": { "type": "string" } } }, "chapters": { "unevaluatedProperties": false, "type": "object", "properties": { "visibleOnLoad": { "type": "string" }, "chapterList": { "type": "array", "items": { "unevaluatedProperties": false, "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "time": { "type": "string" }, "deleted": { "type": "string" } } } }, "on": { "type": "string" } } }, "postRoll-v1": { "unevaluatedProperties": false, "description": "Adds a Call To Action to your Video (response format)", "type": "object", "properties": { "rewatch": { "description": "String representation of whether the video can be rewatched.", "type": "string" }, "text": { "description": "The URL of the text to be displayed.", "type": "string" }, "link": { "description": "The URL of the link to be displayed.", "type": "string" }, "time": { "description": "The time when the post-roll should be displayed as a string.", "type": "string" }, "autoSize": { "description": "String representation of whether the post-roll will automatically adjust its size.", "type": "string" }, "style": { "unevaluatedProperties": false, "type": "object", "properties": { "backgroundColor": { "description": "The background color of the post-roll.", "type": "string" } } }, "ctaType": { "description": "The type of call-to-action to be displayed.", "type": "string" }, "on": { "description": "String representation of whether the post-roll is enabled.", "type": "string" }, "conversionOpportunityKey": { "description": "The key used for tracking conversion opportunities.", "type": "string" } } }, "captions-v1": { "unevaluatedProperties": false, "description": "Captions plugin configuration (response format)", "type": "object", "properties": { "on": { "description": "String representation of whether the captions plugin is enabled (\"true\" or \"false\").", "type": "string" }, "onByDefault": { "description": "String representation of whether captions are turned on by default (\"true\" or \"false\").", "type": "string" } } } } }, "private": { "unevaluatedProperties": false, "type": "object", "properties": { "password_protect_on": { "type": "string" }, "show_comments": { "type": "string" } } }, "encrypted": { "unevaluatedProperties": false, "type": "object", "properties": { "password_protect_password": { "type": "string" } } } } } } } }, "401": { "description": "Unauthorized, invalid or missing token", "content": { "application/json": { "schema": { "unevaluatedProperties": false, "type": "object", "properties": { "code": { "description": "A machine-readable identifier for the specific authorization failure.", "type": "string", "enum": [ "unauthorized_credentials", "account_inactive", "unauthorized_scope", "unauthorized_params" ] }, "error": { "type": "string", "examples": [ "Invalid credentials." ] } } } } } }, "403": { "description": "Forbidden, token is valid but account does not have access to feature", "content": { "application/json": { "schema": { "unevaluatedProperties": false, "type": "object", "properties": { "error": { "type": "string", "examples": [ "Webinars are not available on your current plan" ] } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "unevaluatedProperties": false, "type": "object", "properties": { "error": { "type": "string", "examples": [ "Internal server error" ] } } } } } } }, "tags": [ "Customizations" ], "x-readme": { "code-samples": [ { "name": "Typescript (SDK)", "language": "javascript", "code": "import { Wistia } from \"@wistia/wistia-api-client\";\n\nconst wistia = new Wistia({\n bearerAuth: process.env[\"WISTIA_BEARER_AUTH\"] ?? \"\",\n});\n\nasync function run() {\n const result = await wistia.customizations.create({\n mediaId: \"\",\n requestBody: {\n plugin: {\n postRollV1: {\n style: {\n backgroundColor: \"#303030\",\n },\n ctaType: \"text\",\n },\n },\n videoFoam: true,\n },\n });\n\n console.log(result);\n}\n\nrun();" } ] } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } } }, "x-readme": { "samples-languages": [ "javascript", "shell", "node", "python", "ruby" ] } } ````