getUploadUrl( )

Gets an upload URL for uploading a file to the media manager.

Description

The getUploadUrl() function returns a Promise that resolves to an object containing an upload URL.

Use the getUploadUrl() function to allow an external client to upload a single file to your site's Media Manager.

Note: The upload URL is valid for a single file upload and expires after 1 day. The getUploadUrl() function must be called for each file that you want to upload.

The external client uploads a file by sending a POST or PUT request to the URL returned by getUploadUrl() using multipart/form-data encoding and sending the following data:

{
  "upload_url": <uploadUrl>,
  "file": {
    "value": <contentStream>,
    "options": {
      "filename": <fileName>,
      "contentType": <contentType>
    }
  }
};

javascript | Copy Code

upload_url: The returned upload URL.
file: An object containing:
- value: The file content as a multi-part value.
- options: An object containing:
  - filename: The name of the file as it will appear in the Media Manager.
  - contentType: The content type of the file.

The POST or PUT request returns the following:

[ 
  { 
    "parent_folder_id": <folder id>,
    "hash": <file hash>,
    "tags": [],
    "file_name": <internal file name>,
    "refs": [],
    "labels": [] <image recognition labels of the image content>,
    "site_id": <site id>,
    "height": <image height>,
    "original_file_name": <the original file name>,
    "file_size": <file size>,
    "width": <image width>,
    "media_type": "picture",
    "mime_type": "image/jpeg"
  } 
]

javascript | Copy Code

To get a Wix image URL that can be stored in a collection or displayed in an image element or gallery from the above object, use the following expression:

let wixImageUrl = `wix:image://v1/${response[0].file_name}/${response[0].original_file_name}#originWidth=${response[0].width}&originHeight=${response[0].height}`;

Copy Code

Syntax

function getUploadUrl(path: string, options: UploadOptions): UploadUrl

getUploadUrl Parameters

NAME

TYPE

DESCRIPTION

path

string

The path within the Media Manager where the file will be uploaded. If the path doesn't yet exist, the missing folders will be created.

options

UploadOptions

Options to use when uploading the file.

Returns

Fulfilled - The file's URL.

Return Type:

Promise<UploadUrl>

NAME

TYPE

DESCRIPTION

uploadUrl

string

The URL used for sending a POST or PUT request to upload a file to the Media Manager.

uploadToken

string

Deprecated. Use the uploadUrl property instead.

The token to use with the file POST.

Note: The uploadToken property returns empty, as the token is now included in the upload URL. The uploadToken property will continue to work, but we recommend that you use the updated uploadUrl parameter instead.

Was this helpful?

Generate a URL for uploading a file

This example demonstrates how to generate a URL that an external application can use to upload a file to your site's Media Manager.

Copy Code

1import { Permissions, webMethod } from 'wix-web-module';
2import { mediaManager } from 'wix-media-backend';
3
4export const getUploadUrl = webMethod(Permissions.Anyone, () => {
5  return mediaManager.getUploadUrl(
6    "/myUploadFolder/subfolder",
7    {
8      "mediaOptions": {
9        "mimeType": "image/jpeg",
10        "mediaType": "image"
11      },
12      "metadataOptions": {
13        "isPrivate": false,
14        "isVisitorUpload": false,
15        "context": {
16          "someKey1": "someValue1",
17          "someKey2": "someValue2"
18        }
19      }
20    }
21  );
22});

Use the generated uploadUrl to send a PUT request to upload an image

This example demonstrates how an upload URL generated in the first code example could be used by an external application to upload an image file to the Media Manager using a PUT request. It also creates a Wix image URL from the response.

Copy Code

1/********************************
2 * External Node.js application *
3********************************/
4
5import axios from 'axios';
6
7async function myUploadImageFunction(uploadUrl, contentStream, fileName, contentType) {
8  const response = await axios.put(uploadUrl, contentStream, {
9    headers: {
10      'Content-Type': contentType
11    },
12    params: {
13      filename: fileName
14    }
15  });
16   
17  return `wix:image://v1/${response[0].file_name}/${response[0].original_file_name}#originWidth=${response[0].width}&originHeight=${response[0].height}`;
18}

Use the generated upload URL to send a POST request to upload an image

This example demonstrates how an upload URL generated in the first code example could be used by an external application to upload an image file to the Media Manager using a POST request.

Copy Code

1/********************************
2 * External Node.js application *
3********************************/
4
5import axios from 'axios';
6import FormData from 'form-data';
7
8async function myUploadImageFunction(uploadUrl: string, fileName: string, content: Buffer | fs.ReadStream | string) {
9  const formData = new FormData({});
10  formData.append('file', content, {
11    filename: fileName,
12    contentType: 'image/jpeg',
13  });
14
15  const uploadResponse = await axios.post(
16    uploadUrl,
17    formData,
18    {
19      headers: formData.getHeaders()
20    });
21 
22  return uploadResponse;
23}