S3-compatible endpoint
Many storage services and self-hosted servers speak the same API as Amazon S3. Examples are OVHcloud, Akamai (Linode), Vultr, Scaleway, MinIO and Ceph. WP Media Cloud can upload your Media Library to a bucket on any of them. It then serves every file from a CDN in front of the bucket, or from the bucket’s own address.
In the setup wizard this option is called Custom S3.
If your provider has its own option in the wizard, use that instead. These are Amazon S3, Cloudflare R2, DigitalOcean Spaces, Wasabi, Hetzner, Backblaze B2, Google Cloud and Bunny.net. Those options know their own endpoints and regions.
What you need from your provider#
WP Media Cloud only uses basic S3 requests: upload an object, upload a large object in parts, download, check and delete. Your provider must support these with AWS Signature Version 4.
| What | Where to find it | Example |
|---|---|---|
| Endpoint URL | Your provider’s S3 or API settings | https://s3.gra.io.cloud.ovh.net |
| Region | Same place. Some providers have none. | gra, or us-east-1 if none is given |
| Access key and secret key | API keys, credentials or access keys page | |
| Bucket name | The bucket you create in Step 1 | example-media |
| URL style | Your provider’s docs | Path style or virtual-hosted style |
Endpoint examples#
These formats come from each provider’s documentation. Check your own account for the exact value.
| Provider | Endpoint URL | Notes |
|---|---|---|
| OVHcloud | https://s3.<region>.io.cloud.ovh.net | Region codes are lowercase, such as gra, rbx or de. Supports virtual-hosted style. |
| Akamai (Linode) | https://<endpoint>.linodeobjects.com | For example https://us-lax-4.linodeobjects.com. Supports virtual-hosted style. |
| Vultr | https://<location>.vultrobjects.com | For example https://ewr1.vultrobjects.com for New Jersey. Supports virtual-hosted style. |
| Scaleway | https://s3.<region>.scw.cloud | Regions such as fr-par or nl-ams. |
| MinIO, Ceph or another self-hosted server | Your server’s S3 address | Often needs path style, unless the server is set up for bucket subdomains. |
Path style or virtual-hosted style#
- Path style puts the bucket in the path:
https://s3.example.com/example-media/photo.jpg. MinIO and many self-hosted servers use this. - Virtual-hosted style puts the bucket in the host name:
https://example-media.s3.example.com/photo.jpg. Most managed providers use this.
If you are not sure, check your provider’s docs. If uploads fail with a host name or certificate error, try the other style.
Before you start#
- An account with your provider, or a running self-hosted server.
- An HTTPS endpoint with a valid certificate. WP Media Cloud checks certificates on every upload.
- A bucket name without dots. With virtual-hosted style, dots in the name often break HTTPS certificates.
Step 1: Create a bucket#
- In your provider’s dashboard, create a new bucket.
- Give it a name such as
example-media. Most providers allow lowercase letters, numbers and hyphens. - Choose the region or location closest to most of your visitors.
- Write down the bucket name and region. You need both in Step 4.
Step 2: Make files publicly readable#
Visitors load your images straight from the bucket or from a CDN that reads the bucket. Most buckets start private, so choose one of these options.
Option A: Bucket policy (recommended where supported)#
Many providers accept an AWS-style bucket policy. This one lets anyone read files in one bucket, but not list or change them. Replace example-media with your bucket name.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "PublicReadGetObject",
"Effect": "Allow",
"Principal": "*",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::example-media/*"
}
]
} Where you add it depends on the provider. Look for Bucket policy, Access policy or Public access in the bucket’s settings. Some providers have a simple Public switch that does the same thing.
Option B: Public object ACL#
If your provider has no bucket policy but supports object ACLs, WP Media Cloud can mark each file as public when it uploads it. You set this after Step 4, in Settings, Object Permissions, by setting Object ACL to public-read. See “After setup” below.
Only files uploaded after the change get the ACL. Set it before you start a bulk offload.
Adding a CDN#
Most S3-compatible services do not include a CDN. You can put one in front of the bucket, such as Bunny.net, KeyCDN or CDN77. Point the CDN’s origin at the bucket’s public address and keep the CDN address for Step 4. The bucket must still be public for the CDN to read it.
WP Media Cloud stores every file with a one-year Cache-Control header, so CDNs and browsers can keep files for a long time.
Step 3: Create access keys limited to your bucket#
Create a key just for this site. Many providers let you limit a key to one bucket. Use that option if it exists, and give it read and write access.
If your provider or server supports AWS-style user policies, this policy is all WP Media Cloud needs:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "MediaFilesInOneBucket",
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:DeleteObject",
"s3:AbortMultipartUpload"
],
"Resource": "arn:aws:s3:::example-media/*"
}
]
} WP Media Cloud does not list buckets or bucket contents for this provider, so no list permission is needed.
Copy the access key and secret key into a password manager. Many providers show the secret only once.
Step 4: Connect WP Media Cloud#

In WordPress, open Media Cloud. The setup wizard opens on first use. Choose Custom S3 and select Continue.
| Field | What to enter |
|---|---|
| Endpoint URL | The full S3 address with https://, for example https://s3.gra.io.cloud.ovh.net. Do not include the bucket name. Include a port if your server uses one, for example https://minio.example.com:9000. |
| Region | Your provider’s region code, for example gra. If your provider has no region, enter us-east-1. If you leave it empty, us-east-1 is used. |
| Access Key | From Step 3 |
| Secret Key | From Step 3 |
| Bucket | Exactly as shown by your provider, for example example-media |
| URL Style | Path style (recommended for MinIO) or Virtual-hosted style. Path style is selected by default. The choice shown is the one that is saved. |
| CDN Configuration | Choose Direct bucket URL to serve files from the bucket’s own address. Choose Custom CDN for your own CDN address. |
| CDN URL | Shown for Custom CDN. Your CDN address with https://, for example https://media.example.com. |
You can also pick Bunny.net CDN, KeyCDN, EWWW Easy IO or CDN77. These let the Dashboard show CDN bandwidth.
Select Continue, then Save & Go to Dashboard.
With Direct bucket URL, files are served from:
- Path style: your endpoint followed by the bucket, such as
https://s3.example.com/example-media. - Virtual-hosted style: the bucket in front of the endpoint host, such as
https://example-media.s3.example.com.
Check that it works#
The Custom S3 wizard has no Test connection button. Upload a test instead:
- Upload an image in Media.
- In Media, then Library, switch to list view. The image row should show In cloud.
- Open the image. Its address should start with your CDN URL or bucket address, and it should load.
If the row shows Offload failed, hover over it to read the error, then see Troubleshooting. Failed items are also listed in the Bulk Offload card on the Dashboard.
The Health page checks that your keys and bucket are saved and that the CDN URL responds. For this provider it does not upload a test file.
Changing your endpoint, bucket or keys later#

Go to Settings and select run the setup wizard. Your offloaded files, records and other settings are kept.
In WP Media Cloud 1.1.8 or newer, the wizard opens with your saved settings filled in. This includes the endpoint, region, bucket, URL style, CDN choice and CDN URL. Saved keys show as Saved. Paste only the keys you are changing.
Alternative: Connect with wp-config.php#

Instead of the wizard, you can define your settings in wp-config.php, above the line /* That's all, stop editing! */. Values set here override anything saved in the admin, which suits sites managed in version control.
Multisite: constants in wp-config.php apply to every subsite, so they point every subsite at the same bucket. That works when each subsite keeps its files in its own folder: also add define( 'WPMC_PATH_PREFIX', 'sites/%site_id%' );. Or set up each subsite in its own dashboard. See Custom path prefix.
// Required
define( 'WPMC_PROVIDER', 's3' );
define( 'WPMC_S3_ENDPOINT', 'https://s3.gra.io.cloud.ovh.net' );
define( 'WPMC_S3_ACCESS_KEY', 'your-access-key' );
define( 'WPMC_S3_SECRET_KEY', 'your-secret-key' );
define( 'WPMC_S3_BUCKET', 'example-media' );
// Recommended: set these to match your provider.
define( 'WPMC_S3_REGION', 'gra' ); // us-east-1 if your provider has no region
define( 'WPMC_S3_PATH_STYLE', false ); // true for path style, false for virtual-hosted
// Optional: serve files through a CDN.
// Leave both out to serve files from the bucket's own address.
define( 'WPMC_S3_CDN_TYPE', 'custom' );
define( 'WPMC_S3_CDN_URL', 'https://media.example.com' );
// Optional: send a public-read ACL with every upload (Step 2, option B).
define( 'WPMC_S3_ACL', 'private' ); // private | public-read The first five lines are required. If you leave out WPMC_S3_REGION, us-east-1 is used. If you leave out WPMC_S3_PATH_STYLE, path style is used, so set it to false for virtual-hosted providers.
Then open Media Cloud. On the first wizard screen, select Configure via wp-config.php, then Done, constants added.
The Health page and the Dashboard read these constants too.
For other CDNs, the generator also prints optional constants such as WPMC_S3_BUNNY_API_KEY, WPMC_S3_PULL_ZONE_HOSTNAME, WPMC_S3_KEYCDN_ZONE_URL, WPMC_S3_EWWW_API_KEY and WPMC_S3_CDN77_URL. WP Media Cloud reads every one of them.
Older setups using s3compat#
Earlier versions of this guide used WPMC_PROVIDER set to s3compat, with WPMC_S3COMPAT_* constants. Those sites keep working, and Settings shows an S3-Compatible CDN card for them. The setup wizard has no fields for s3compat, so keep managing its endpoint and keys in wp-config.php. For new sites, use s3 as shown above.
After setup#
- New uploads are offloaded automatically and served from your CDN URL or bucket address.
- Existing media is not moved until you start a bulk offload from the Dashboard with Offload All Media. On large libraries or multisite,
wp wpmc offload(orwp wpmc offload --network) is faster. - Changing your CDN URL later: in Settings, open the Custom S3 CDN card, choose your CDN and enter the new URL. Select Save Settings. Then select Update all media URLs under Apply to Existing Media, so existing offloaded items record the new address.
- Object ACL: Settings, Object Permissions, Object ACL sends
x-amz-acl: public-readwith every upload when set topublic-read. Leave it onprivateif your bucket is public through a policy. - Dashboard stats: storage size is not available for custom S3 endpoints. The Dashboard shows the number of offloaded files. CDN bandwidth is shown only for Bunny.net CDN, KeyCDN, EWWW Easy IO and CDN77.
- WooCommerce secure downloads are available with Bunny.net and Cloudflare R2 only. With a custom S3 endpoint, the WooCommerce card says so, and downloadable product files use their normal CDN URL.
Troubleshooting#
| What you see | What it means | How to fix it |
|---|---|---|
Offload failed: cURL error 6: Could not resolve host | The endpoint host is wrong, or the provider does not support bucket subdomains. | Check the Endpoint URL. If it is correct, switch URL Style to Path style. |
Offload failed: cURL error 60 or another SSL certificate error | The endpoint’s certificate is not valid for the host name. With virtual-hosted style, the certificate may not cover bucket subdomains. | Install a valid certificate on your server. Try Path style, or a bucket name without dots. |
Offload failed: cURL error 7, cURL error 28 or No response from storage provider | WP Media Cloud could not reach the endpoint, or it timed out. | Check the address and port, and that your host allows outgoing connections to it. |
Offload failed: HTTP 403 SignatureDoesNotMatch | The secret key is wrong, or the provider expects a different region. | Paste the secret again with no spaces. Check the region code in your provider’s docs. |
Offload failed: HTTP 403 InvalidAccessKeyId | The access key does not exist on this endpoint. | Copy the key again. Check that the key and bucket belong to the same provider account and region. |
Offload failed: HTTP 403 AccessDenied | The key is not allowed to write to this bucket. | Give the key read and write access to the bucket. |
Offload failed: HTTP 400 AuthorizationHeaderMalformed | The region does not match what the provider expects. | Enter the exact region code from your provider, or us-east-1 if it has none. |
Offload failed: HTTP 404 NoSuchBucket | The bucket name is wrong, or it is in another region or endpoint. | Copy the bucket name exactly. Use the endpoint for the bucket’s region. |
Offload failed: HTTP 400 AccessControlListNotSupported, or another ACL error | Object ACL is public-read, but the bucket does not accept ACLs. | Set Object ACL to private and make the bucket public with a policy instead. |
Images are broken, or the file URL shows 403 AccessDenied | Visitors are not allowed to read files in the bucket. | Complete Step 2. Then open a file’s URL in a private browser window to check. |
| Images are blocked as mixed content | The endpoint uses http://, so files are served over HTTP on an HTTPS site. | Use an https:// endpoint, or put an HTTPS CDN in front and choose Custom CDN. |
| Images load from the bucket address instead of your CDN | The CDN choice is Direct Bucket, or the CDN URL is empty. | In the Custom S3 CDN card, choose your CDN, enter the URL and save. Or set WPMC_S3_CDN_URL in wp-config.php. |
| New uploads stay on your server | Offload on upload is switched off. Before 1.1.7.1, finishing the setup wizard could switch it off. | In Settings, turn on Offload on upload and Rewrite URLs. |
| Browser console shows CORS errors | A script is fetched from the bucket’s domain, or a font while Serve fonts from your site is off. Fonts load from your site by default and need no CORS. Ordinary images and video do not need CORS. | On the Health tab, run the Web Fonts (CORS) check and click Allow this site to add the rule to the bucket. If the button is not shown, your access key cannot change the bucket’s CORS rules: add a CORS rule on the bucket that allows GET from your site’s address, if your provider supports it. |
Frequently asked questions#
Which providers work? Any provider that supports the S3 API with AWS Signature Version 4 for uploads, multipart uploads, downloads and deletes. If a provider has its own option in the wizard, use that instead.
Do I have to use a CDN? No. Direct bucket URL serves files from the bucket’s own address. A CDN is faster for visitors far from the bucket and can lower your provider’s traffic bill.
What region should I enter if my provider has none? Enter us-east-1. This is the default when the field is empty. Self-hosted servers sometimes use their own region name, so check your server’s settings.
Can WP Media Cloud list my buckets? Not for Custom S3. Type the bucket name in the wizard. This also means the key needs no list permission.
Can I use one bucket for several sites? Yes, when each site has its own path prefix. WP Media Cloud stores files by upload date and file name, such as 2026/10/photo.jpg, so two sites without a prefix can overwrite each other’s files. On a multisite network, set Path prefix to sites/%site_id%. For separate sites, give each one a prefix of its own, such as shop and blog. A staging site should still use its own bucket. See Custom path prefix.