In This Article

Media

The Media API enables you to get absolute URLs for Wix Media resources, including scaled and cropped images.

With the SDK Media API, you can:

Get an absolute URL for a Wix Media resource
Scale a Wix Media image to fit specified dimensions
Scale a Wix Media image to fill specified dimensions
Crop a Wix Media image

Wix APIs identify Wix Media resources using internal identifiers with the following structure:

Copy

1wix:image://v1/<uri>/<filename>#originWidth=<width>&originHeight=<height>[&watermark=<watermark_manifest_string>]

For example, a product or cart item object may refer to its associated image with an identifier such as "wix:image://v1/3c76e2_c5331f937348492a97df87b...".

You can use the SDK Media API to obtain an absolute URL for such an image, so you can access and manipulate it in your own code. You can obtain a URL for the original image, or for a scaled or cropped version of the image.

Functions

getImageUrl()

Gets an absolute URL for the specified Wix Media image.

Syntax

Copy

1getImageUrl(wixMediaIdentifier: string) : {
2    id: string,
3    url: string,
4    height: number,
5    width: number,
6    altText?: string,
7    filename?: string,
8}

Parameters

Name	Type	Description
`wixMediaIdentifier`	string	Wix Media resource identifier starting with `wix:image//`.

Returns

Name	Type	Description
`id`	string	Wix Media ID.
`url`	string	Absolute URL for the image.
`height`	number	Image height.
`width`	number	Image width.
`altText`	string	Optional. Image alt text.
`filename`	string	Optional. Image file name.

getScaledToFillImageUrl()

Gets an absolute URL for a scaled-to-fill version of a Wix Media image.

The getScaledToFillImageUrl() function scales the specified Wix Media image to fill the specified targetWidth and targetHeight while retaining the image's original proportions. If the desired proportions are different from those of the original image, the image is cropped so it fills the entire area specified. This means only part of the original image may be visible. The image can be further transformed by passing an options object.

When cropping is necessary, the position from which to crop is set by default to the center of the image, or to the x and y values of the image's focal point, if present.

Syntax

Copy

1getScaledToFitImageUrl(
2  wixMediaIdentifier: string,
3  targetWidth: number,
4  targetHeight: number,
5  options?: ImageTransformOptions,
6) : string

Parameters

Name	Type	Description
`wixMediaIdentifier`	string	Wix Media resource identifier starting with `wix:image//`.
`targetWidth`	string	Target width of the scaled image.
`targetHeight`	string	Target height of the scaled image.
`options`	ImageTransformOptions	Options to be used to further transform the image.

Returns

URL of scaled image

getScaledToFitImageUrl()

Gets an absolute URL for a scaled-to-fit version of a Wix Media image.

The getScaledToFitImageUrl() function scales a specified Wix Media image to fit within the specified targetWidth and targetHeight while retaining the image's original proportions. The image can be further transformed by passing an options object.

Syntax

Copy

1getScaledToFitImageUrl(
2  wixMediaIdentifier: string,
3  targetWidth: number,
4  targetHeight: number,
5  options?: ImageTransformOptions,
6) : string

Parameters

Name	Type	Description
`wixMediaIdentifier`	string	Wix Media resource identifier starting with `wix:image//`.
`targetWidth`	string	Target width of the scaled image.
`targetHeight`	string	Target height of the scaled image.
`options`	ImageTransformOptions	Options to be used to further transform the image.

Returns

URL of scaled image

getCroppedImageUrl()

Gets an absolute URL for a cropped version of a Wix Media image.

The getCroppedImageUrl() function crops the specified Wix Media image based on the specified coordinates. The part of the image to be retained starts at the specified cropX and cropY coordinates and includes the specified cropWidth and cropHeight. If targetWidth and targetHeight are provided, the image is scaled accordingly. The image can be further transformed by passing an options object.

Syntax

Copy

1getCroppedImageUrl(
2  wixMediaIdentifier: string,
3  cropX: number,
4  cropY: number,
5  cropWidth: number,
6  cropHeight: number,
7  targetWidth: number,
8  targetHeight: number,
9  options?: ImageTransformOptions,
10) : string

Parameters

Name	Type	Description
`wixMediaIdentifier`	string	Wix Media resource identifier starting with `wix:image//`.
`cropX`	number	Top-left X coordinate of the retained part of the image.
`cropY`	number	Top-left Y coordinate of the retained part of the image.
`cropWidth`	number	Width of the retained section of the image.
`cropHeight`	number	Height of the retained section of the image.
`targetWidth`	string	Optional. Target width of the cropped image. Use this to scale the image.
`targetHeight`	string	Optional. Target height of the cropped image. Use this to scale the image.
`options`	ImageTransformOptions	Optional. Options to be used to further transform the image.

1getVideoUrl(wixMediaIdentifier: string, videoResolution?: VideoResolution) : {
2    id: string,
3    url: string,
4    thumbnail: string,
5    filename?: string,
6}

Parameters

Name	Type	Description
`wixMediaIdentifier`	string	Wix Media resource identifier starting with `wix:video//`.
`videoResolution`	VideoResolution	Optional. Video resolution. Supported values: `360p`, `480p`, `720p`, `1080p`. Defaults to the resolution of the video uploaded.

Returns

Name	Type	Description
`id`	string	Wix Media ID.
`url`	string	Absolute URL for the video.
`thumbnail`	string	Wix Media resource identifier for the video's thumbnail image.
`filename`	string	Optional. Video filename.

getAudioUrl()

Gets an absolute URL for the specified Wix Media audio.

Syntax

Copy

1getAudioUrl(wixMediaIdentifier: string) : {
2    id: string,
3    url: string,
4    duration: number,
5    filename?: string,
6}

Parameters

Name	Type	Description
`wixMediaIdentifier`	string	Wix Media resource identifier starting with `wix:audio//`.

Returns

Name	Type	Description
`id`	string	Wix Media ID.
`url`	string	Absolute URL for the audio.
`duration`	number	Duration of the audio in seconds.
`filename`	string	Optional. Audio filename.

getDocumentUrl()

Gets an absolute URL for the specified Wix Media document.

Syntax

Copy

1getDocumentUrl(wixMediaIdentifier: string) : {
2    id: string,
3    url: string,
4    filename?: string,
5}

Parameters

Name	Type	Description
`wixMediaIdentifier`	string	Wix Media resource identifier starting with `wix:document//`.

Returns

Name	Type	Description
`id`	string	Wix Media ID.
`url`	string	Absolute URL for the document.
`filename`	string	Optional. Document file name.

Objects

ImageTransformOptions

Name	Type	Description
`filters`	ImageTransformFiltersOption	Optional. Image filters.
`unsharpMask`	OptionUnsharpMask	Optional. Image unsharp masking options.
`focalPoint`	`{x: number, y: number}`	Optional. Image focal point.
`name`	string	Optional. Image name.
`quality`	number	Optional. Quality of the image.
`upscaleMethod`	string	Optional. Method used when upscaling an image. One of `'auto'`, `'classic'`, or `'super'`.
`watermark`	string	Optional. Image watermark.
`isSEOBot`	boolean	Optional. Whether to enforce rendering the full image for robots. Defaults to `false`.
`autoEncode`	boolean	Optional. Whether to disable the server's auto detection of the best file format to use based on the request. Defaults to `true`.
`shouldLoadHQImage`	boolean	Optional. Whether to enforce the library to attempt loading the image, not a low quality placeholder. If `true` a `targetWidth` and `targetHeight` must be provided. Defaults to `false`.
`useSrcset`	boolean	Optional. Whether to return a map for use in image's `srcset` attribute instead of a single URL for use in responsive images. Supports the "Resolution Switching: same size, different resolution" use-case. Result will be returned in the following format: `{ dpr: ['url/for/1x.png 1x', 'url/for/2x.png 2x'] }`. Defaults to `false`.

ImageTransformFiltersOption

Name	Type	Description
`contrast`	number	Optional. Contrast value.
`brightness`	number	Optional. Brightness value.
`saturation`	number	Optional. Saturation value.
`hue`	number	Optional. Hue value.
`blur`	number	Optional. Blur value.

OptionUnsharpMask

Name	Type	Description
`amount`	number	Optional. Amount of contrast to add to make the image appear sharper. From `0`-`10`. Defaults to `0.66`.
`radius`	number	Optional. Number of pixels next to the detected edge pixels that are affected. From `0.1`-`500`. Defaults to `1.0`.
`threshold`	number	Optional. How different a pixel is from surrounding pixels to be considered an edge. From `0`-`255`. Defaults to `0.01`.

Was this helpful?

Yes