Skip to main content

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.

The Convertly WordPress plugin optimizes media as it enters the WordPress Media Library. It is intended for WordPress site owners who want automatic image and media optimization without building against the API directly.

​
Install from WordPress

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 a Convertly API key.
  6. Choose your optimization rules.
New uploads are optimized automatically after setup.

​
Connect Convertly

Create an API key in the Convertly dashboard, then paste it into Settings > Convertly Media. The plugin uses API keys rather than OAuth account login. This keeps the WordPress setup simple and avoids storing Convertly account passwords in WordPress.

​
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.

​
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.
  1. Choose a tool card.
  2. Click Choose from Media Library.
  3. Pick an image from the WordPress media modal.
  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.

​
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 your Convertly API key, so every optimization request follows the API key owner’s plan limits.
  • 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.
  • Keep API keys 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 API keys are the expected setup for the first marketplace release.