Upload Multiple Media by API

Upload multiple images and media files to your WordPress Media Library through a dedicated REST API endpoint.

Upload Multiple Media by API is designed for headless WordPress, mobile apps, external applications, frontend frameworks, and custom integrations that need reliable programmatic media uploads.

Each uploaded file is validated, optionally optimized, checked for duplicates, added to the WordPress Media Library, and returned with detailed information in the API response.

Video Tutorial

Learn how to upload multiple media files through the WordPress REST API:

Features

• Upload multiple media files in a single REST API request.
• REST API endpoint for programmatic media uploads.
• Authentication support using WordPress Application Passwords.
• Optional ALT text for each uploaded image.
• Image optimization with configurable quality.
• Maximum image width and height controls.
• Duplicate detection using SHA-256 file hashes.
• Configure maximum files per request.
• Configure maximum file size.
• Configure allowed file types.
• Attach uploaded media to an existing post.
• Detailed per-file JSON responses.
• Works with headless WordPress and custom frontend applications.
• WordPress Media Library integration.

REST API

Endpoint:

/wp-json/mmbyapi/v1/upload-multiple-images

Method:

POST

File field:

mmbyapi_file_upload[]

Send multiple files using the same field name.

ALT text field:

mmbyapi_alt_texts[]

ALT text is optional and is matched to uploaded files by array index.

Optional post field:

post_id

Use post_id to attach uploaded media to an existing WordPress post.

Image Optimization

Image optimization can be enabled or disabled from the plugin settings.

When enabled, supported images can be optimized according to the configured quality and maximum dimensions.

Supported optimization formats:

• JPEG/JPG
• PNG
• WebP

Available settings include:

• Enable or disable image optimization.
• Image quality from 10 to 100.
• Maximum image width.
• Maximum image height.

Images smaller than the configured maximum dimensions are not enlarged.

The API response includes optimization information for each file, including:

• Original file size.
• Optimized file size.
• Saved bytes.
• Saved percentage.
• Final image width.
• Final image height.

When optimization is disabled, uploaded images are not modified by the optimization process and the response reports optimized: false.

Authentication

Authentication is optional and is disabled by default for backward compatibility.

When authentication is enabled, API requests must be authenticated and the user must have the WordPress upload_files capability.

WordPress Application Passwords can be used with the REST API.

For production environments, use HTTPS and authenticated requests rather than exposing an unrestricted upload endpoint.

Example using cURL:

curl -X POST "https://example.com/wp-json/mmbyapi/v1/upload-multiple-images" -u "USERNAME:APPLICATION_PASSWORD" -F "mmbyapi_file_upload[]=@image1.jpg" -F "mmbyapi_file_upload[]=@image2.jpg" -F "mmbyapi_alt_texts[]=Front view of the property" -F "mmbyapi_alt_texts[]=Interior of the property"<h3>JavaScript Example</h3>
const formData = new FormData();

formData.append('mmbyapi_file_upload[]', file1);
formData.append('mmbyapi_file_upload[]', file2);

formData.append(
    'mmbyapi_alt_texts[]',
    'Front view of the property'
);

formData.append(
    'mmbyapi_alt_texts[]',
    'Interior of the property'
);

const response = await fetch(
    'https://example.com/wp-json/mmbyapi/v1/upload-multiple-images',
    {
        method: 'POST',
        headers: {
            Authorization: 'Basic ' + btoa(
                'USERNAME:APPLICATION_PASSWORD'
            ),
        },
        body: formData,
    }
);

const result = await response.json();
console.log(result);<h3>Response</h3>

Successful requests return per-file information including:

• Attachment ID.
• Media URL.
• MIME type.
• File size.
• Image dimensions when available.
• Content hash.
• Duplicate status.
• ALT text when provided.
• Image optimization information when applicable.

Example:

{
    "success": true,
    "total": 2,
    "uploaded": 2,
    "failed": 0,
    "duplicates": 0,
    "post_id": null,
    "files": [
        {
            "file": "image1.jpg",
            "success": true,
            "duplicate": false,
            "attachment_id": 123,
            "url": "https://example.com/wp-content/uploads/2026/09/image1.jpg",
            "mime_type": "image/jpeg",
            "title": "image1",
            "filesize": 100785,
            "width": 2560,
            "height": 1920,
            "hash": "sha256-file-hash",
            "optimization": {
                "optimized": true,
                "original_size": 233292,
                "optimized_size": 100785,
                "saved_bytes": 132507,
                "saved_percent": 56.8,
                "width": 2560,
                "height": 1920
            },
            "alt_text": "Front view of the property"
        }
    ]
}

If some files succeed while others fail, the endpoint returns HTTP 207 and provides a result for each file.

Duplicate Detection

Duplicate detection is enabled by default and uses a SHA-256 content hash.

The plugin calculates a SHA-256 hash of each uploaded file and stores the hash as attachment metadata. If identical file content is uploaded again, the existing Media Library attachment is returned instead of creating another attachment.

Renaming a file does not bypass duplicate detection because the check is based on file content.

Admin Settings

The plugin provides settings for:

• Authentication requirements.
• Maximum files per request.
• Maximum file size.
• Allowed file types.
• Duplicate detection.
• Image optimization.
• Image quality.
• Maximum image width.
• Maximum image height.

These settings help administrators control external media uploads and image processing.

Use Cases

• Headless WordPress media uploads.
• Next.js and React applications.
• Mobile applications.
• Custom frontend applications.
• External systems integrating with WordPress.
• Bulk image uploads.
• Property and real estate websites.
• Product and catalog management systems.
• Automated media ingestion workflows.

Compatibility

• WordPress 5.0 or higher.
• PHP 5.6 or higher.
• WordPress REST API.
• WordPress Media Library.
• JPEG/JPG, PNG, GIF, and WebP according to the configured MIME allow-list.