RECIPE: Upload Media to Wix Media Manager

View the file in GitHub
Download skill
Copy

Learn how to upload images and files to a Wix site's Media Manager using the REST API.

Overview

The Wix Media Manager stores all media files for a site. When you need to use images or files in other Wix APIs, you should first upload them to the Media Manager to get a reliable wixstatic.com URL.

Key Points:

  • Uploaded files are permanently stored on Wix servers
  • You get back a url (wixstatic.com) that works reliably in other APIs
  • External URLs can fail if the source server blocks requests - Media Manager URLs never fail

Method: Import File from External URL

The simplest way to add media is to import it from an external URL. Wix will download and store the file.

API Endpoint

Copy

Request Example

Copy

Request Parameters

ParameterRequiredDescription
urlYesThe external URL of the file to import
mimeTypeRecommendedMIME type (e.g., image/jpeg, image/png). If omitted, Wix tries to detect it
displayNameNoDisplay name in Media Manager. Include extension (e.g., My Image.jpg)
parentFolderIdNoFolder ID to store the file. Defaults to media-root

Response Example

Copy

Key Response Fields

FieldDescription
idMedia ID
urlThe wixstatic.com URL - use this in other APIs
operationStatusPENDING → READY when processed, or FAILED if import failed

Can I Use the URL Immediately?

In most cases, yes. The returned wixstatic.com URL typically works immediately for basic use cases like adding to products or blog posts.

Wait for READY when:

  • You need image dimensions or metadata
  • You're using image transformations (resize, crop)
  • You want guaranteed consistency for critical operations

Practical approach: Try using the URL immediately. If it fails, poll until operationStatus: "READY".

Checking File Status

After importing, the file goes through async processing. For guaranteed consistency, verify operationStatus: "READY" before using the file.

Get File by ID (Recommended)

Use this endpoint to check the status of a specific file:

Copy

Example:

Copy

List Recent Files (Alternative)

If you need to find files without knowing the ID:

Copy

Status Values

StatusMeaning
PENDINGStill processing - wait before using
READYFile is ready to use
FAILEDImport failed

Response When Ready

Copy

Note: Wix automatically generates labels (tags) for images using AI.

Alternative: Upload from Local Device

If you need to upload files from a local device (not from a URL), use the two-step upload process:

Step 1: Generate Upload URL

Copy

Step 2: Upload to the Generated URL

Copy

Note: For files larger than 10MB, use the Resumable Upload URL API instead.

Common Issues

Issue 1: Import Fails (operationStatus: FAILED)

Problem: The file shows operationStatus: "FAILED" after import.

Causes:

  • Source server blocks external requests (e.g., Wikipedia, some CDNs)
  • Source server requires authentication
  • Invalid URL or file not found
  • File type not supported

Solution: Use image sources that allow hotlinking:

  • Unsplash (images.unsplash.com)
  • Pexels (images.pexels.com)
  • Your own hosted images
  • Public cloud storage (S3, GCS with public access)

Issue 2: File Stuck in PENDING

Problem: File stays in PENDING status for a long time.

Solution:

  • Large files take longer to process
  • Check back after a few seconds
  • If still pending after 30+ seconds, the import may have silently failed

Summary

StepActionResult
1Call Import File API with external URLGet file id and url with status PENDING
2Poll List Files APIWait for operationStatus: "READY"
3Use in other APIsUse the url field (wixstatic.com URL)
Did this help?