Skip to main content
The Convertly PHP SDK is a small cURL-based client for server-side apps and WordPress plugins. It has zero dependencies beyond the PHP cURL extension.
CDN delivery is separate from this API client. To serve optimized images from the CDN, use a delivery namespace and either Convertly Storage file ids/slugs or an origin source for your deployed asset URLs. See Image CDN setup.
composer require convertly/convertly-php

​
Create a client

<?php

require __DIR__ . '/vendor/autoload.php';

use Convertly\ConvertlyClient;

$convertly = new ConvertlyClient(getenv('CONVERTLY_API_KEY'));
For a custom API origin (for example staging): 
$convertly = new ConvertlyClient(
    getenv('CONVERTLY_API_KEY'),
    'https://staging.convertly.sh'
);

​
Convert a file

$result = $convertly->convertFile(__DIR__ . '/photo.png', 'webp', [
    'compression' => 'balanced',
    'resizeWidth' => 1600,
    'saveToStorage' => false,
]);

if (!$result['ok']) {
    throw new RuntimeException($result['error']);
}

$outputUrl = $result['body']['url'];

​
Conversion options

OptionTypeDescription
compressionstringImage compression preset: high, balanced, ultra.
resizestringResize strategy: fit, fill, cover, contain.
resizeWidthintTarget width in pixels.
resizeHeightintTarget height in pixels.
autoOrientboolAuto-rotate based on EXIF. Default true.
monoboolFor SVG tracing: true for monochrome, false for color.
saveToStorageboolSave the output to Convertly Storage.
For raster-to-SVG conversion, color is preserved by default. Pass 'mono' => true only when you want monochrome tracing.

​
Compress a file

$result = $convertly->compressFile(__DIR__ . '/hero.jpg', [
    'quality' => 82,
    'stripMetadata' => true,
    'mode' => 'quality',
]);

​
Compression options

OptionTypeDescription
modestringquality (1-100) or target-size (bytes).
qualityint1-100 quality level when mode is quality.
stripMetadataboolRemove EXIF and metadata.
saveToStorageboolSave the output to Convertly Storage.

​
Media tools

Use the generic mediaTool() method for any Convertly media tool endpoint: 
// Background removal
$result = $convertly->mediaTool('remove-background', __DIR__ . '/product.jpg', [
    'format' => 'png',
    'model' => 'medium',
]);

// Thumbnail from video
$result = $convertly->mediaTool('thumbnail', __DIR__ . '/video.mp4', [
    'time' => 5.0,
    'width' => 320,
    'height' => 180,
]);

// Watermark
$result = $convertly->mediaTool('watermark', __DIR__ . '/photo.jpg', [
    'text' => 'Convertly',
    'position' => 'bottom-right',
    'opacity' => 0.5,
]);

// PDF preview
$result = $convertly->mediaTool('pdf-preview', __DIR__ . '/document.pdf', [
    'page' => 1,
    'width' => 800,
]);

// Image to PDF
$result = $convertly->mediaTool('image-to-pdf', __DIR__ . '/scan.png');

// Strip metadata
$result = $convertly->mediaTool('strip-metadata', __DIR__ . '/photo.jpg');

// Inspect file
$result = $convertly->mediaTool('inspect', __DIR__ . '/video.mp4');
Available tool slugs: thumbnail, pdf-preview, image-to-pdf, strip-metadata, poster-frame, extract-audio, watermark, inspect, trim, gif, storyboard, transform, remove-background. Pass 'async' => 'true' in $fields for longer media-tool work. Async tool responses include a jobId; use getJob($jobId) to poll completion.

​
Convertly Storage

The WordPress-bundled SDK also exposes storage helpers used by the plugin: 
// List root folders and root files
$folders = $convertly->getFolders('');
$files = $convertly->getFiles('', 100, 0);

// List a nested folder
$folders = $convertly->getFolders($parentFolderId);
$files = $convertly->getFiles($parentFolderId, 100, 0);

// Upload a local file into a Convertly folder
$uploaded = $convertly->uploadFile(__DIR__ . '/hero.jpg', $parentFolderId);
Use an empty string ('') for root-level storage listings. Use null only when you intentionally want the API default behavior.

​
Batch jobs

Upload multiple files in a single batch job: 
$result = $convertly->createJob(
    [
        __DIR__ . '/photo1.png',
        __DIR__ . '/photo2.png',
        __DIR__ . '/photo3.png',
    ],
    [
        'format' => 'webp',
        'compression' => 'balanced',
        'resizeWidth' => 1600,
    ]
);

$jobId = $result['body']['jobId'];

​
Job management

// Get a job by ID
$job = $convertly->getJob($jobId);

// List recent jobs
$jobs = $convertly->getJobs(20);

// Check status
if ($job['body']['status'] === 'completed') {
    $outputUrl = $job['body']['result']['url'];
}

​
Error handling

Every method returns a consistent response array: 
$result = $convertly->convertFile(__DIR__ . '/photo.png', 'webp');

if (!$result['ok']) {
    $status = $result['status'] ?? 0;
    $error = $result['error'] ?? 'Unknown error';
    // Handle error
}
Common error cases:
  • Missing API key: ['ok' => false, 'error' => 'Missing Convertly API key.']
  • Missing cURL extension: ['ok' => false, 'error' => 'Convertly uploads require the PHP cURL extension.']
  • Unreadable file: ['ok' => false, 'error' => 'File is not readable.']
  • HTTP errors: ['ok' => false, 'status' => 429, 'error' => 'Rate limit exceeded.']

​
WordPress integration

The WordPress plugin is built on this SDK, so plugin behavior and standalone PHP behavior stay aligned. You can use the same ConvertlyClient class in custom WordPress themes or plugins: 
$convertly = new ConvertlyClient(get_option('convertly_api_key'));
$result = $convertly->convertFile($upload_path, 'webp', [
    'compression' => get_option('convertly_compression', 'balanced'),
    'saveToStorage' => true,
]);

​
Method reference

MethodDescription
new ConvertlyClient($apiKey, $baseUrl?)Create a client. Default base URL is https://convertly.sh.
hasApiKey()Check if an API key was provided.
convertFile($path, $format, $options?)Convert a file to another format.
compressFile($path, $options?)Compress an image or document.
mediaTool($tool, $path, $fields?)Call any media tool endpoint.
createJob($paths, $fields)Create a batch job with multiple files.
getJob($jobId)Get a job by ID.
getJobs($limit?)List recent jobs. Default limit is 20.
getFiles($folderId?, $limit?, $offset?, $search?)List Convertly Storage files. Empty string lists root files.
getFolders($parentId?, $search?)List Convertly Storage folders. Empty string lists root folders.
uploadFile($path, $folderId?)Upload a local file into Convertly Storage.