Amazon S3 Storage

Offload your Image Studio and Video Studio results from the local server disk to your own Amazon S3 (or S3-compatible) bucket.

This is a Paid plugin that you can purchase and install via the in-app Plugins marketplace.

Introduction

Amazon S3 Storage lets you, the platform owner, offload generated studio results (Image Studio and Video Studio images and videos) from the local server disk to your own Amazon S3 bucket — or any S3-compatible provider such as DigitalOcean Spaces, MinIO or Cloudflare R2.

Unlike the studios, Amazon S3 Storage is an infrastructure plugin: it doesn’t add any user-facing tool. It registers a new storage backend that the platform writes new results to, and serves those results back to users. It plugs into the same shared storage layer as the Wasabi, Cloudflare R2 and Google Cloud Storage plugins — so exactly one backend is active at a time, chosen by you.

This guide covers the full lifecycle — where to buy it, how to install it, how to create a bucket and IAM credentials, how to configure and test the connection, how to make S3 the active storage, and how offloading behaves.

What it adds

• Config screen — an admin page under General Settings → Plugins to enter credentials, tune options and test the connection.
• Storage provider — registers Amazon S3 as an option in the platform’s Default Storage selector.
• Automatic offload — when S3 is the active storage, every newly finalized studio result is uploaded to your bucket, and the platform records that the file now lives in S3.
• Transparent serving — reads, downloads and deletes for offloaded results resolve through S3 (or your CDN) automatically.

The plugin only affects where generated results are stored. It doesn’t change how anything is generated, priced or gated — it’s purely a storage backend.

Purchase & Installation

Amazon S3 Storage is distributed through the in-app plugin marketplace — purchasing and installation both happen inside your MagicAds admin. There’s no third-party download.

1. Open the Plugins marketplace

   Sign in as an admin and go to Admin → General Settings → Plugins. Find the Amazon S3 Storage card in the marketplace catalog.

2. Purchase (if required)

   The card CTA depends on your license and purchase state:

   • Free / already owned → installs directly.
   • Paid → routes you to the plugin checkout to complete the purchase.
   • Extended License holders → plugins flagged “free for Extended License” install without an extra purchase.

   If the page shows “This plugin is free only for Extended License holders”, you’re on a Regular License and must purchase Amazon S3 Storage (or upgrade your license) to install it.

3. Install / activate

   Click Install on the Amazon S3 Storage card. The platform downloads the archive, unpacks it, runs its migration and activates the plugin. Its provider details (key, secret, region, bucket, endpoint, URL, path-style, prefix, delete-local) are stored as an encrypted settings entry, so adding storage providers never changes the schema.

   On a fresh install everything stays on the local disk. Installation only makes the config screen and the storage provider exist. Nothing is offloaded until you enter valid credentials, enable the provider, and select S3 as the Default Storage (next sections).

To remove the plugin later, click Uninstall on the same card.

Create a bucket and IAM credentials

Before configuring the plugin, set up the bucket and credentials in the AWS Console.

1. Create an S3 bucket

   In the AWS S3 Console, create a bucket (e.g. my-magicads-media). Note the bucket name and its Region (e.g. us-east-1).

2. Create an IAM user with programmatic access

   In IAM → Users → Create user, add a user with programmatic (access key) access, and attach an S3 policy scoped to your bucket — it needs to read, write and delete objects (e.g. s3:GetObject, s3:PutObject, s3:DeleteObject, s3:ListBucket).

3. Generate an access key

   Create an Access key ID and Secret access key for that user. Copy both now — AWS shows the secret only once.

4. Decide how files are served

   Generated results are served from the bucket’s public URL (or a CDN in front of it). Make the bucket (or its objects) publicly readable, or put a CloudFront/CDN distribution in front and set its URL in the plugin’s Public / CDN URL field.

For strict least-privilege, scope the IAM policy to the exact bucket (and key prefix) you’ll use. The access key and secret are stored encrypted by the plugin once saved.

Configure Amazon S3

Go to Admin → General Settings → Plugins → Amazon S3 Storage (/app/admin/general/plugins/amazon-s3). The screen has these sections.

General

Setting	Purpose
Enable Amazon S3	Makes S3 a selectable option in the Default Storage list once credentials are valid. It does not by itself route uploads here — you still pick the active backend.
Delete local copy after upload	When on, the local file is removed once it’s safely stored in S3, reclaiming server disk space. Leave off to keep a local backup of every result.

Bucket Credentials

Field	Notes
Access Key ID	From your IAM user (e.g. AKIA…).
Secret Access Key	From your IAM user. Stored encrypted; leave blank on later edits to keep the existing one.
Region	The bucket’s AWS region (e.g. us-east-1).
Bucket	The S3 bucket name.

Advanced

Only needed for S3-compatible providers (DigitalOcean Spaces, Cloudflare R2, MinIO) or a CDN in front of your bucket.

Field	Notes
Custom Endpoint	Leave blank for AWS. Set it to point at an S3-compatible provider (e.g. https://nyc3.digitaloceanspaces.com).
Public / CDN URL	The base URL files are served from — a CloudFront/CDN domain, for example.
Key Prefix	Optional folder inside the bucket (e.g. magicads), transparently prepended to every object key.
Use path-style endpoint	Off for AWS. Enable it for providers that require path-style addressing (e.g. MinIO).

To enable the provider you need at minimum the access key, secret, region and bucket.

Connection

Click Test connection. The plugin saves your settings, then uploads, reads back and deletes a tiny probe object to confirm the bucket is reachable and writable. A green toast means S3 is ready; a red toast surfaces the exact error (bad credentials, wrong region/bucket, permissions).

Click Save to persist everything.

Make S3 the active storage

Enabling the provider only adds it to the selector. To actually store new results in S3, set it as the platform’s Default Storage:

1. Open General Settings

   Go to Admin → General Settings → General.

2. Select Amazon S3

   Set Default Storage to Amazon S3.

3. Save

   Save the change. From that point, every newly finalized studio result is offloaded to S3. Only enabled, fully-configured providers appear in this list, and “Local server (this machine)” is always the fallback.

Only one storage backend is active at a time. Selecting Amazon S3 here makes it authoritative for new results; it does not retroactively move files that were already stored locally or on another provider — those keep serving from wherever they already live.

How offloading works

The platform uses a single shared storage layer, so S3 behaves like the other storage plugins:

1. A studio finishes generating an image or video and stores it on the local results disk.
2. The platform checks which provider is active. If it’s S3, the file is streamed up to your bucket under the same relative path it has locally (e.g. images/gemini/uuid.png), with your key prefix prepended if set.
3. The creative is marked as living in S3, so future reads, downloads and deletes resolve through S3.
4. If Delete local copy after upload is on, the local file is removed to reclaim space.

Two important safety properties:

• Generation never breaks on storage errors. If an upload fails, the result simply stays on the local disk and serves from there — the failure is logged, not surfaced to the user.
• Local is the safe default. If S3 is later disabled, uninstalled, or misconfigured, the platform falls back to local storage for new results, and already-offloaded files keep serving from S3.

Because offloaded objects are served from your bucket’s public URL (or the Public / CDN URL when set), features that hand a media URL to a third party (for example, publishing a creative through Social Media Studio) automatically use the S3 URL. If the bucket isn’t publicly readable and no CDN URL is set, those files won’t be reachable.

Go-live checklist

1. Install the plugin

   Admin → General Settings → Plugins → Amazon S3 Storage → Install.

2. Create the bucket and IAM credentials

   In AWS: create the S3 bucket and an IAM user with an S3 policy scoped to it, then generate an access key.

3. Enter the credentials

   Amazon S3 config → fill in Access Key ID, Secret, Region and Bucket (plus Endpoint / path-style for S3-compatible providers).

4. Enable the provider

   Turn on Enable Amazon S3 and Save.

5. Test the connection

   Click Test connection and confirm the green success toast.

6. Set as Default Storage

   General Settings → General → set Default Storage to Amazon S3 → Save.

7. Verify end-to-end

   Generate a new result in Image or Video Studio, then confirm the file appears in your bucket and still displays correctly in the app.

8. Decide on local cleanup

   Once you trust the setup, optionally turn on Delete local copy after upload to reclaim server disk.

Once every step above is green, new studio results are stored in your S3 bucket.

Troubleshooting

Symptom	Likely cause	Fix
S3 doesn’t appear in the Default Storage list	Provider not enabled, or credentials incomplete	Enable it and fill in access key, secret, region and bucket.
”Connection failed” on test	Wrong keys, region or bucket name	Re-check the IAM key, the exact region, and the bucket name.
”Upload succeeded but the object could not be read back”	IAM policy too narrow	Grant the user read access (e.g. s3:GetObject, s3:ListBucket) and retry.
New results still stored locally	S3 enabled but not selected as Default Storage	Set Default Storage to Amazon S3 in General Settings → General.
Offloaded images show broken in the app	Bucket not public and no CDN URL	Make the bucket/objects publicly readable, or set a Public / CDN URL.
S3-compatible provider fails to connect	Missing endpoint or path-style setting	Set the Custom Endpoint and enable Use path-style endpoint if the provider needs it.
Files served from the wrong path	Key prefix mismatch	Ensure the Key Prefix matches how objects are organized in the bucket.
Secret field looks empty when editing	Secrets are never echoed back	Leave it blank to keep the stored secret; type a new value only to replace it.
Old files didn’t move to S3	Offload only applies to new results	Selecting S3 doesn’t migrate existing files; they keep serving from their current location.

The secret access key is stored encrypted using your app APP_KEY. Switching Default Storage back to local (or disabling the plugin) never deletes what’s already in your bucket — those files keep serving from S3.