Introduction
Â
APIs in Developer Preview are subject to change and are not intended for use in production.
Send us your suggestions for improving this API. Your feedback is valuable to us.
Â
The Files API allows you to manage files and generate file urls from your Media Manager.
With the Files API, you can:
Setup
To use the Files API, install the @wix/media
package using npm or Yarn:
1npm install @wix/media
or
1yarn add @wix/media
Then import { files }
from @wix/media
:
1import { files } from '@wix/media'
Resumable Upload API
This article demonstrates how to use the response object from the Generate File Resumable Upload Url endpoint to upload a file to a site's Media Manager.
Note: Due to limits on the size and duration of files that you can upload, we recommend using the importFile()
function. See Wix Media: Supported Media File Types and File Sizes for more details.
Authorization
This endpoint uses the uploadToken
from the response for authorization.
No additional authorization is needed.
Syntax
1PUT {{generateFileResumableUploadUrlResponse.uploadUrl}}/{{generateFileResumableUploadUrlResponse.uploadToken}}
Query Params
Name | Type | Optional | Description |
---|---|---|---|
filename | string | no | File name that appears in the Media Manager. Include the file's extension in the name to prevent potential errors. |
Example
Implement a Resumable Upload Client using TUS Protocol
In this example we use tus-js-client to implement a resumable upload using the TUS protocol.
Request
1async function resumableFileUpload(resumableUploadUrlResponse: GenerateFileResumableUploadUrlResponse): Upload {2 // get the file content to upload3 const fileName = 'imageExample.jpg';4 const fileContent = await fs.createReadStream(path.join(__dirname, '..', 'files', fileName));5
6 const mimeType = 'image/jpeg';7
8 const params = {9 filename: fileName,10 contentType: mimeType,11 token: resumableUploadUrlResponse.uploadToken12 };13
14 // Wrap the resumable upload session in a promise to wait for the upload to finish.15 await new Promise(async (resolve, reject) => {16 // Create a new TUS upload.17 const upload = new tus.Upload(fileContent, {18 // Use the uploadUrl from the response of the generate URL endpoint.19 endpoint: resumableUploadUrlResponse.uploadUrl,20 // Enable tus-js-client to automatically retry on errors.21 retryDelays: [0, 3000, 5000, 10000, 20000],22 // TSend parameters to the upload server to indentify the file and authentication token.23 metadata: {24 filename: fileName,25 contentType: mimeType,26 token: resumableUploadUrlResponse.uploadToken27 },28 // Callback for errors that can't be fixed using retries.29 onError: function (error) {30 console.log('Failed because: ' + error);31 reject(error);32 },33 // Callback for reporting upload progress.34 onProgress: function (bytesUploaded, bytesTotal) {35 var percentage = (bytesUploaded / bytesTotal * 100).toFixed(2);36 console.log(bytesUploaded, bytesTotal, percentage + '%');37 },38 // Callback for once the upload is completed.39 onSuccess: function () {40 console.log('Download %s from %s', fileName, upload.url);41 resolve(true);42 }43 });44
45 upload.start();46 });47
48 // PUT request to finalize the upload.49 // Note that we concatenate the URL and token of the resumable upload response.50 const result = await httpClient.put(51 `${resumableUploadUrlResponse.uploadUrl}/${resumableUploadUrlResponse.uploadToken}`,52 {}, { params: { filename: fileName } }53 );54}
Response
1{2 "file": {3 "id": "2acbb8_86485e224dd84143ba2f228777217bb7~mv2.jpeg",4 "displayName": "file.jpg",5 "url": "https://static.wixstatic.com/media/2acbb8_86485e224dd84143ba2f228777217bb7~mv2.jpeg",6 "parentFolderId": "media-root",7 "hash": "cf96f0567ed967f02bc9580ab8db86be",8 "sizeInBytes": "15359",9 "private": false,10 "mediaType": "IMAGE",11 "media": {12 "image": {13 "image": {14 "id": "2acbb8_86485e224dd84143ba2f228777217bb7~mv2.jpeg",15 "url": "https://static.wixstatic.com/media/2acbb8_86485e224dd84143ba2f228777217bb7~mv2.jpeg",16 "height": 226,17 "width": 370,18 "filename": "file.jpg",19 "sizeInBytes": "15359"20 },21 "faces": []22 }23 },24 "operationStatus": "READY",25 "thumbnailUrl": "https://static.wixstatic.com/media/2acbb8_86485e224dd84143ba2f228777217bb7~mv2.jpeg",26 "labels": [],27 "createdDate": "2022-09-11T15:13:24.000Z",28 "updatedDate": "2022-09-11T15:13:24.000Z"29 }30}
Status/Error Codes
Errors from this endpoint will include an HTTP status code.
Upload API
This article demonstrates how to use the uploadUrl
response from the Generate File Upload Url endpoint to upload a file to a site's Media Manager.
Note: Due to limits on the size and duration of files that you can upload, we recommend using the importFile()
function. See Wix Media: Supported Media File Types and File Sizes for more details.
Authorization
This endpoint uses the upload token included in the url for authorization. No additional authorization is needed.
Syntax
1PUT {{generateFileUploadUrlResponse.uploadUrl}}
Headers Params
Name | Type | Optional | Description |
---|---|---|---|
Content-Type | string | no | File content type. For example, "image/jpeg" for a jpg file. |
Query Params
Name | Type | Optional | Description |
---|---|---|---|
filename | string | no | File name that appears in the media manager. Include the file's extension in the name to prevent potential errors. |
Note: In case of failure due to incorrect mimeType
, include the file's extension in the filename
parameter and set the Content-Type
to 'application/octet-stream'. Doing this allows Wix servers to detect the correct content type of the file.
Request
1async function uploadMyFile(uploadUrl, fileContent) {2 const params = {'filename':'my-audo-track.mp3'};3 const headers = {4 'Content-Type': 'application/octet-stream'5 } 6
7 const uploadResponse = await httpClient.put( uploadUrl, fileContent, { headers, params } );8 return uploadResponse;9}
Response
1{2 "file": {3 "id": "2acbb8_86485e224dd84143ba2f228777217bb7~mv2.jpeg",4 "displayName": "file.jpg",5 "url": "https://static.wixstatic.com/media/2acbb8_86485e224dd84143ba2f228777217bb7~mv2.jpeg",6 "parentFolderId": "media-root",7 "hash": "cf96f0567ed967f02bc9580ab8db86be",8 "sizeInBytes": "15359",9 "private": false,10 "mediaType": "IMAGE",11 "media": {12 "image": {13 "image": {14 "id": "2acbb8_86485e224dd84143ba2f228777217bb7~mv2.jpeg",15 "url": "https://static.wixstatic.com/media/2acbb8_86485e224dd84143ba2f228777217bb7~mv2.jpeg",16 "height": 226,17 "width": 370,18 "filename": "myfilename.jpg",19 "sizeInBytes": "15359"20 },21 "faces": []22 }23 },24 "operationStatus": "READY",25 "thumbnailUrl": "https://static.wixstatic.com/media/2acbb8_86485e224dd84143ba2f228777217bb7~mv2.jpeg",26 "labels": [],27 "createdDate": "2022-09-11T15:13:24.000Z",28 "updatedDate": "2022-09-11T15:13:24.000Z"29 }30}
Status/Error Codes
Errors from this endpoint will include an HTTP status code.
Deletes the specified files from the Media Manager.
The bulkDeleteFiles()
function returns a Promise that resolves when the files are deleted.
The deleted files are moved to the Media Manager's trash bin (TRASH_ROOT
folder) unless permanently deleted. To permanently delete files, pass the permanent
parameter with the value true
. Permanently deleting files isn't reversible, so make sure that these files aren't being used in a site or in any other way as the files will no longer be accessible.
Notes:
- The specified files can be from different folders.
- Moving multiple files at once is an asynchronous action, and may take time for the changes to appear in the Media Manager.
- Attempting to delete files that are already in the trash bin doesn't result in an error.
- If your site contains deleted media files, the deleted media files still appear on your site as the files are still in the Media Manager (in the trash bin).
- You can use
bulkRestoreFilesFromTrashBin()
to restore files from the Media Manager's trash bin.
Permission Scopes
For app development, you must have one of the following permission scopes:function bulkDeleteFiles(fileIds: Array<string>, options: BulkDeleteFilesOptions): Promise<void>
IDs of the files to move to the Media Manager's trash bin.
Options to use when deleting files.
Imports a bulk of files to the Media Manager using external urls.
The bulkImportFile()
function returns a Promise that resolves to an object containing bulk import metadata and an array of imported files' descriptors and metadata.
Returns information about the imported files. Use the parentFolderId
parameter to specify in which folder you want each file to be imported.
If no folder is specified, the file is imported to the media-root
folder.
To import files, you need to do one of the following for each file:
- Pass its MIME type in the
mimeType
field of the request. For example,mimeType: 'image/jpeg'
. - Include its extension in either the
displayName
orurl
field of the request. For example,displayName: 'Example Image.jpeg
orurl: https://www.example.com/image.jpeg
. - Ensure the server hosting the file supports HEAD requests. In these cases the Wix servers can retrieve the MIME type from the hosting server.
Note: If you want to validate the media type, pass the file's expected media type in the optional
mediaType
field of the request. For example,mediaType: 'IMAGE'
.
Permission Scopes
For app development, you must have one of the following permission scopes:function bulkImportFile(importFileRequests: Array<ImportFileRequest>, options: BulkImportFileOptions): Promise<BulkImportFileResponse>
Information about the files to import.
Options to include the file descriptor in the response.
Deprecated.
This function has been replaced with bulkImportFile()
, and will be removed on March 31, 2024.
The bulkImportFiles()
function returns a Promise that resolves to an array of the imported files' descriptors.
Imports a bulk of files to the Media Manager using external urls.
Returns information about the imported files. Use the parentFolderId
parameter to specify in which folder you want each file to be imported.
If no folder is specified, the file is imported to the media-root
folder.
Note: The media
property isn't returned in the files
response object.
To import files, you need to do one of the following for each file:
- Pass its MIME type in the
mimeType
field of the request. For example,mimeType: 'image/jpeg'
. - Include its extension in either the
displayName
orurl
field of the request. For example,displayName: 'Example Image.jpeg
orurl: https://www.example.com/image.jpeg
. - Ensure the server hosting the file supports HEAD requests. In these cases the Wix servers can retrieve the MIME type from the hosting server.
Note: If you want to validate the media type, pass the file's expected media type in the optional
mediaType
field of the request. For example,mediaType: 'IMAGE'
.
Permission Scopes
For app development, you must have one of the following permission scopes:function bulkImportFiles(importFileRequests: Array<ImportFileRequest>): Promise<BulkImportFilesResponse>
Information about the files to import.
Restores the specified files from the Media Manager's trash bin, and moves them to their original locations in the Media Manager.
The bulkRestoreFilesFromTrashBin()
function returns a Promise that resolves when the files have been restored.
Permission Scopes
For app development, you must have one of the following permission scopes:function bulkRestoreFilesFromTrashBin(fileIds: Array<string>): Promise<void>
IDs of the files to restore from the Media Manager's trash bin.
Generates one or more temporary URLs for downloading a specific file in the Media Manager.
The generateFileDownloadUrl()
function returns a Promise that resolves to an array containing download URLs for the assets specified in the options parameter.
To download different assets of the file, use the assetKeys
parameter which generates a download URL for each asset.
If no asset key is specified, it defaults to src
, which generates one download URL in the original file's format and quality.
Use this function to grant external clients access to a private media file. Use the expirationInMinutes
parameter to set the URL expiration time, and the expirationRedirectUrl
parameter to add a redirect URL when the URL expires.
To generate a permanent URL for downloading a compressed file that contains multiple files in the Media Manager, use the generateFilesDownloadUrl()
function.
Since this is a permanent URL, it is less secure. Therefore, to download private files, use the generateFileDownloadUrl()
function for each private file that you want to generate a download URL for.
Permission Scopes
For app development, you must have one of the following permission scopes:function generateFileDownloadUrl(fileId: string, options: GenerateFileDownloadUrlOptions): Promise<GenerateFileDownloadUrlResponse>
File ID.
Options to use when generating a file's download URL.
Generates a resumable upload URL to allow external clients to upload large files over 10MB to the Media Manager.
The generateFileResumableUploadUrl()
function returns a Promise that resolves to an upload URL, token, and protocol.
When using the resumable upload URL, any interruptions will pause the file upload process, which automatically resumes once the interruption is resolved. The resumable upload URL is also helpful when network connection is poor.
To learn how external clients can use the generated upload URL in the response to upload large files to the Media Manager, see the Resumable Upload API article.
Permission Scopes
For app development, you must have one of the following permission scopes:function generateFileResumableUploadUrl(mimeType: string, options: GenerateFileResumableUploadUrlOptions): Promise<GenerateFileResumableUploadUrlResponse>
File mime type.
Options to use when generating a resumable upload URL.
Generates an upload URL to allow external clients to upload a file to the Media Manager.
The generateFileUploadUrl()
function returns a Promise that resolves to an upload URL.
To learn how external clients can use the generated upload URL in the response to upload a file to the Media Manager, see the Upload API article.
Note: Any interruption in the upload process stops the file upload. For files larger than 10MB, or when network connection is poor, use generateFileResumableUploadUrl()
instead. With the resumable upload URL, any interruption in the upload process pauses the file upload, and resumes the file upload process after the interruption.
Permission Scopes
For app development, you must have one of the following permission scopes:function generateFileUploadUrl(mimeType: string, options: GenerateFileUploadUrlOptions): Promise<GenerateFileUploadUrlResponse>
File mime type.
Options to use when generating a file's upload URL.
Generates a URL for downloading a compressed file containing specific files in the Media Manager.
The generateFilesDownloadUrl()
function returns a Promise that resolves to a download URL.
The compressed file can contain up to 1000 files.
To generate one or more temporary URLs for downloading a specific file in the Media Manager, use the generateFileDownloadUrl()
function.
You can use the expirationInMinutes
parameter to set the URL expiration time, making it more secure than the generateFilesDownloadUrl()
function.
Therefore, to download private files, use the generateFileDownloadUrl
function for each private file that you want to generate a download URL for.
Permission Scopes
For app development, you must have one of the following permission scopes:function generateFilesDownloadUrl(fileIds: Array<string>): Promise<GenerateFilesDownloadUrlResponse>
IDs of the files to download.
Generates a URL for streaming a specific video file in the Media Manager.
The generateVideoStreamingUrl()
function returns a Promise that resolves to a download URL and its asset key.
To stream different assets of the file, use the assetKeys
parameter which generates a video streaming URL for each asset. If no asset key is specified, it defaults to src
, which generates one video streaming URL in the original file's format and quality.
Permission Scopes
For app development, you must have one of the following permission scopes:function generateVideoStreamingUrl(fileId: string, options: GenerateVideoStreamingUrlOptions): Promise<GenerateVideoStreamingUrlResponse>
File ID.
Options to use when generating a video file's streaming URL.
Gets information about the specified file in the Media Manager.
The getFileDescriptor()
function returns a Promise that resolves to the specified file's descriptor.
Use getFileDescriptors()
to get multiple file descriptors at once.
Permission Scopes
For app development, you must have one of the following permission scopes:function getFileDescriptor(fileId: string): Promise<FileDescriptor>
File ID.
Gets information about the specified files in the Media Manager.
The getFileDescriptors()
function returns a Promise that resolves to an array containing the specified files' descriptors.
Use getFileDescriptor()
to get a single file descriptor.
Permission Scopes
For app development, you must have one of the following permission scopes:function getFileDescriptors(fileIds: Array<string>): Promise<GetFileDescriptorsResponse>
File IDs.
Imports a file to the Media Manager using an external URL.
The importFile()
function returns a Promise that resolves to the imported file's descriptor.
This function returns information about the imported file. Importing a file is the method through which you can add files to the Media Manager.
Use the parentFolderId
parameter to specify which folder you want the file to be imported to.
If no folder is specified, the file is imported to the media-root
folder.
To import a file, you need to do one of the following:
- Pass its MIME type in the
mimeType
field of the request. For example,mimeType: 'image/jpeg'
. - Include its extension in either the
displayName
orurl
field of the request. For example,displayName: 'Example Image.jpeg
orurl: https://www.example.com/image.jpeg
. - Ensure the server hosting the file supports HEAD requests. In these cases the Wix servers can retrieve the MIME type from the hosting server.
Note: If you want to validate the media type, pass the file's expected media type in the optional
mediaType
field of the request. For example,mediaType: 'IMAGE'
.
Permission Scopes
For app development, you must have one of the following permission scopes:function importFile(url: string, options: ImportFileOptions): Promise<ImportFileResponse>
Publicly accessible external file URL.
Options to use when importing a single file.
Retrieves a list of files in the Media Manager's trash bin.
The listDeletedFiles()
function returns a Promise that resolves to an array of the specified deleted files' descriptors and cursor information.
Note: The Media Manager's trash bin (TRASH_ROOT
folder) only contains temporarily deleted files, not permanently deleted files.
To retrieve a list of non-deleted files, use the listFiles()
function.
Permission Scopes
For app development, you must have one of the following permission scopes:function listDeletedFiles(options: ListDeletedFilesOptions): Promise<ListDeletedFilesResponse>
Options to use when listing deleted files from the trash bin.
Retrieves a list of files in the Media Manager.
The listFiles()
function returns a Promise that resolves to an array of the specified files' descriptors and cursor information.
To retrieve a list of files within a specific folder in the Media Manager, pass the folder's ID in the parentFolderId
parameter. If no folder is specified, the function retrieves only the list of files in the root folder of the Media Manager.
To retrieve a list of (non-permanently) deleted files, use the listDeletedFiles()
function.
Permission Scopes
For app development, you must have one of the following permission scopes:function listFiles(options: ListFilesOptions): Promise<ListFilesResponse>
Options to use when listing media files.
Searches all folders in the Media Manager and returns a list of files that match the terms specified in the optional parameters.
The searchFiles()
function returns a Promise that resolves to an array of the specified files' descriptors and cursor information.
If no parameters are specified, the function returns all files in the MEDIA_ROOT
folder.
Permission Scopes
For app development, you must have one of the following permission scopes:function searchFiles(options: SearchFilesOptions): Promise<SearchFilesResponse>
Options to specify which folders to search.
Updates a file.
The updateFileDescriptor()
function returns a Promise that resolves to the updated file's descriptor.
You can use the parentFolderId
parameter to move a file from its current folder to a different folder.
Permission Scopes
For app development, you must have one of the following permission scopes:function updateFileDescriptor(_id: string, file: UpdateFileDescriptorFile): Promise<FileDescriptor>
File ID. Generated when a file is uploaded to the Media Manager.