> ## Documentation Index > Fetch the complete documentation index at: https://docs.convertly.sh/llms.txt > Use this file to discover all available pages before exploring further. # WordPress plugin > Optimize WordPress uploads, import Convertly Storage files, and run Convertly media tools from the WordPress admin.
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. Queue new uploads and existing attachments for compression, resizing, WebP, AVIF, and background processing. Browse Convertly Storage folders from WordPress and import selected files into the Media Library. Create new WordPress attachments from Convertly tools without changing the source file. 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](https://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. ### Recommended for production sites: WordPress site tokens 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](/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. ## Recommended production setup * 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.