PHP SDK

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 CDN endpoint 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

Option	Type	Description
`compression`	`string`	Image compression preset: `high`, `balanced`, `ultra`.
`resize`	`string`	Resize strategy: `fit`, `fill`, `cover`, `contain`.
`resizeWidth`	`int`	Target width in pixels.
`resizeHeight`	`int`	Target height in pixels.
`autoOrient`	`bool`	Auto-rotate based on EXIF. Default `true`.
`mono`	`bool`	For SVG tracing: `true` for monochrome, `false` for color.
`saveToStorage`	`bool`	Save 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

Option	Type	Description
`mode`	`string`	`quality` (1-100) or `target-size` (bytes).
`quality`	`int`	1-100 quality level when mode is `quality`.
`stripMetadata`	`bool`	Remove EXIF and metadata.
`saveToStorage`	`bool`	Save 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, video-frames, 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

Method	Description
`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.

Getting Started

Image CDN

Media Platform

SDKs & Integrations

Resources

Create a client

Convert a file

Conversion options

Compress a file

Compression options

Media tools

Convertly Storage

Batch jobs

Job management

Error handling

WordPress integration

Method reference

​Create a client

​Convert a file

​Conversion options

​Compress a file

​Compression options

​Media tools

​Convertly Storage

​Batch jobs

​Job management

​Error handling

​WordPress integration

​Method reference

Create a client

Convert a file

Conversion options

Compress a file

Compression options

Media tools

Convertly Storage

Batch jobs

Job management

Error handling

WordPress integration

Method reference