Skip to main content
WordPress plugin
The Convertly WordPress plugin connects WordPress to the Convertly media API. It can optimize uploads, process existing Media Library files, import assets from Convertly Storage, and create new media assets with on-demand tools such as background removal, format conversion, raster-to-SVG, thumbnails, watermarks, and metadata cleanup.

Optimize WordPress media

Queue new uploads and existing attachments for compression, resizing, WebP, AVIF, and background processing.

Use Convertly Storage

Browse Convertly Storage folders from WordPress and import selected files into the Media Library.

Run media tools

Create new WordPress attachments from Convertly tools without changing the source file.

Keep WordPress responsive

WordPress coordinates jobs while Convertly workers handle heavier media processing.

​
Download and install

Download the latest plugin ZIP from Convertly:
  1. Open convertly.sh/wordpress-plugin/download.
  2. Save the ZIP when your browser starts the download.
  3. In WordPress, open Plugins > Add New > Upload Plugin.
  4. Choose the versioned ZIP (for example convertly-media-optimizer-0.7.6.zip), click Install Now, then Activate.
  5. Open Settings > Convertly Media and paste the site’s Convertly WordPress token.
The plugin is licensed under GPL-2.0-or-later and includes its source code in the package. Convertly serves a versioned ZIP on each release; the download page always points at the latest build.

​
Install from WordPress.org

When the plugin is listed in the WordPress Plugin Directory:
  1. Open Plugins > Add New in WordPress.
  2. Search for Convertly Media Optimizer.
  3. Click Install Now, then Activate.
  4. Open Settings > Convertly Media or click Settings next to Convertly in the plugin list.
  5. Paste the site’s Convertly WordPress token.
  6. Choose your optimization rules.
New uploads are optimized automatically after setup.

​
Connect Convertly

The plugin accepts any Convertly API key. Which key you paste decides what the site sees inside Convertly Storage. Create a WordPress site token in the Convertly dashboard at Integrations → WordPress → Create site token, then paste it into Settings > Convertly Media on the WordPress site. Site tokens start with cvly_wp_ and are scoped to one WordPress install. This is the safe default and the right choice for agencies, client sites, and any deployment where the WordPress admin is not the same person as the Convertly account owner.
  • No storage lets the site optimize uploads and run every media tool, but it cannot browse or save into Convertly Storage.
  • Isolated storage gives the site its own Convertly Storage scope, so files saved by the plugin are invisible to other sites and to your main library.
When isolated storage is on, you can additionally share specific folders from your main Convertly library with the site. Shared folders show up alongside the site’s isolated workspace in the Convertly Storage browser and can be marked read-write (plugin can browse, import, and save into them) or read-only (browse and import only). Manage shares from Integrations → WordPress → site → Shared folders in the Convertly dashboard.

​
Alternative for solo developers: standard account API keys

You can also paste a standard account API key (the cvly_… key from Settings → API) into the plugin. This works the same way and unlocks every optimization, media tool, and storage feature — but the WordPress site can browse and import your entire Convertly library, including files unrelated to this site. Use this only when:
  • You are the only person who manages both the WordPress site and the Convertly account.
  • You explicitly want the plugin to access every folder you have in Convertly Storage.
If anyone else has access to the WordPress admin (a client, a junior team member, a contractor), use a WordPress site token instead. The site token scope is a one-way boundary: the site only sees what you have given it.

​
Media tools work the same either way

The Media tools tab in the plugin works with both token types. Tools that do not save to Convertly Storage — background removal, format conversion, watermarking, raster-to-SVG, thumbnails, metadata cleanup — all run identically. The only difference is the optional “Save result to Convertly Storage” checkbox: with a WordPress site token, the output lands in the site’s isolated bucket; with a standard key, it lands in your main library.

​
Optimization controls

  • Optimize new uploads automatically
  • Optimize original images
  • Choose generated WordPress image sizes
  • Set image quality from 1 to 100
  • Strip metadata
  • Generate WebP copies
  • Generate AVIF copies
  • Resize oversized originals
  • Enable video and audio compression
The queue section shows how many local WordPress jobs are queued, dispatched to Convertly, running, completed, skipped, or failed. It stays in an empty state until media is actually queued, then shows progress once there is work to track.

​
Existing media

Use Media > Bulk optimize to optimize files that were uploaded before Convertly was installed. The bulk page shows available media, queue progress, total savings, and recent job status in one place. You can also queue existing media from Settings > Convertly Media when you are already editing optimization rules.

​
Convertly Storage imports

Use Media > Convertly Storage to pull files from your Convertly account into WordPress.
  1. Open Media > Convertly Storage.
  2. Browse a Convertly Storage folder.
  3. Select the assets you want in WordPress.
  4. Import them into the Media Library.
Imported attachments are tagged with their Convertly Storage file ID so repeated imports can skip duplicates. This is useful when your team, app, or AI workflow already created assets in Convertly and WordPress needs to publish them. The browser mirrors Convertly’s folder hierarchy. Root browsing requests only show root-level folders and files; when you open a folder, WordPress sends that folder ID so nested folders stay grouped under their parent. When you use Media > Convertly tools, the native WordPress media modal also includes a Convertly Storage tab. Browse or search the site-scoped folders, choose an image, and click Import and use this image. WordPress imports the remote image as a normal Media Library attachment before the tool runs. If that Convertly Storage image was imported previously, the plugin reuses the existing attachment instead of creating a duplicate. If the site’s token has storage disabled, this page shows a storage access message and optimization still works. Use isolated storage when a client site should import from its own Convertly asset area without seeing agency files, and add shared folders when the site should also pull from a brand or stock library you maintain in your main account.

​
Optional auto-import

When the plugin is connected with a WordPress site token that has isolated storage, administrators can enable Convertly Storage auto-import under Settings > Convertly Media. The plugin checks every five minutes for new files in the site’s workspace folders and imports them into the Media Library, skipping duplicates. The setting is off by default and stays disabled for account API keys or site tokens without isolated storage.

​
On-demand media tools

Use Media > Convertly tools when you want to create a new asset from an existing Media Library item without changing the original. These tools use the Convertly media API from inside WordPress.
  1. Choose a tool card.
  2. Click Choose from Media Library.
  3. Pick a local image, or open the Convertly Storage tab and import a site-scoped image.
  4. Adjust the settings for that tool.
  5. Click Create new media file.
The plugin saves the Convertly output back into the WordPress Media Library as a new attachment and stores source metadata on the generated file. Available tools:
  • Remove background creates a transparent PNG copy.
  • Convert format creates WebP, AVIF, JPG, or PNG copies with optional resizing.
  • Raster to SVG creates an editable SVG copy for simple logos and flat artwork.
  • Create thumbnail generates square or fitted preview assets.
  • Watermark creates a branded image copy.
  • Strip metadata creates a cleaned copy where the source format supports metadata removal.

​
Image CDN

The plugin can serve your Media Library images through Convertly’s image CDN in origin-fetch mode: the CDN pulls each original from your WordPress site the first time it is requested, transforms and compresses it, then serves it from the edge on every subsequent request. Nothing is re-uploaded and your originals stay in WordPress. This is an opt-in module, separate from upload optimization. You can run either, both, or neither.

​
One-time setup in Convertly

The quickest path is Settings > Convertly Media > Image CDN > Create setup automatically in WordPress. The plugin uses the site’s Convertly token to create or reuse an origin source for the WordPress uploads URL and a public delivery namespace. Click Test Image CDN setup afterward to fetch and display a real transformed Media Library image. You can also configure the same values manually:
  1. Create a CDN origin source pointing at your uploads URL. In Convertly, open Image CDN → Origin sources and add an origin whose base URL is your WordPress uploads root, for example https://example.com/wp-content/uploads. Give it a slug like my-site.
  2. Choose a delivery namespace. Under Image CDN → Delivery, use the default namespace or create a site-specific one. It is safe to embed in page markup and does not rotate when signing keys change.

​
Enable it in WordPress

  1. Open Settings → Convertly Media → Image CDN.
  2. Tick Enable Image CDN.
  3. Paste the delivery namespace and the origin source slug.
  4. Choose a delivery format (Auto negotiates WebP/AVIF per browser) and a quality.
  5. Save.
The plugin rewrites front-end image URLs from your uploads directory into CDN URLs of the form: 
https://cdn.convertly.sh/{namespace}/o/{originSlug}/2026/05/photo.jpg?w=1024&format=auto&q=82
It hooks wp_get_attachment_image_src, wp_calculate_image_srcset, and post content, so themes that render images through standard WordPress functions get CDN URLs automatically — including responsive srcset widths. Admin screens, feeds, and the REST API keep using local URLs so the Media Library and block editor behave normally. SVGs and non-image files are never rewritten. External image URLs (not from your uploads directory) pass through untouched.

​
Roles and uninstall behavior

Administrators can enable Allow users who can upload files to use Convertly tools and the site-scoped storage picker under Settings > Convertly Media > Access and uninstall. This exposes the on-demand tools page and native picker tab to editors without granting access to plugin settings, bulk optimization, full storage imports, CDN provisioning, or CDN testing. SVG generation remains administrator-only. Deleting the plugin preserves its settings, queue rows, and attachment metadata by default. Enable Remove Convertly settings, queue rows, and attachment metadata when the plugin is deleted when you want a clean uninstall. Optimized media files and local backup files remain in WordPress either way.

​
Background processing

Upload requests do not wait for optimization to finish. The plugin stores local work items in WordPress, sends each media operation to Convertly’s /api/jobs endpoint, and writes completed results back into the Media Library after Convertly workers finish. When callbacks are enabled, Convertly notifies the plugin as soon as a remote job completes. WP-Cron remains as a fallback for dispatching local work and recovering missed callbacks, but the plugin does not need minute-by-minute polling for normal completion. WordPress still uses WP-Cron, or a real server cron calling wp-cron.php, as the lightweight dispatcher and poller. Convertly’s server-side queue performs the heavy media processing. Failed local queue items retry up to three times with backoff. Site admins can retry failed items and process a small queue batch from Media > Bulk optimize or Settings > Convertly Media.

​
Quota behavior

The plugin uses the site’s Convertly WordPress token, so every optimization request follows the owning Convertly account’s plan limits while storage access stays scoped to that site token.
  • Per-minute limits return 429; the background queue backs off and retries.
  • Monthly quota limits return 402; the job fails immediately with a quota message instead of wasting retries.
  • After upgrading or enabling overage billing in Convertly, retry failed jobs from Settings > Convertly Media.
  • The plugin sends idempotency keys for remote jobs so retries do not create duplicate Convertly work.
  • Enable original backups if you want a restore path before optimized files replace local uploads.
  • Enable modern-format serving to let WordPress return generated AVIF/WebP files for browsers that advertise support.
  • Use a paid Convertly plan sized for your upload volume.
  • Create one WordPress site token per production site from Integrations → WordPress, especially for agency and client work.
  • Disable storage on client tokens that only need optimization, or use isolated storage when client assets should remain separate.
  • Disabling storage blocks the site token from browsing, importing, uploading, or saving Convertly Storage files without deleting previously isolated files. Revoke the site token when the connection and its isolated storage data should be removed.
  • Keep site tokens private and rotate them if a site administrator leaves.
  • Use a real server cron for busy sites instead of relying only on visitor-triggered WP-Cron.
  • Keep enough WordPress disk space for originals, generated sizes, and optimized outputs.
  • Test WebP and AVIF delivery with your theme, cache plugin, and CDN.
OAuth-style Convertly Connect can be added later, but WordPress site tokens are the expected setup for the first marketplace release.