PHP SDK
Convert files between 240+ formats from PHP. One call uploads your file, converts it, waits and downloads the result; jobs, webhooks and the format list are there when you need more. PHP 8.1+ with the curl extension, no other dependencies.
Installing
Install it with your package manager. PHP 8.1+.
$ composer require runconvert/runconvert-phpInitializing
new RunConvert(?string $apiKey = null, string $baseUrl = …, int $timeout = 60, int $maxRetries = 2)Create one client and reuse it. Without an API key it reads the RUNCONVERT_API_KEY environment variable. Get a key in Dashboard → API Keys, and keep it on your server: never put it in browser or mobile app code.
Example
use RunConvert\RunConvert;
$rc = new RunConvert(); // reads RUNCONVERT_API_KEYuse RunConvert\RunConvert;
$rc = new RunConvert(
apiKey: getenv('RUNCONVERT_API_KEY'),
timeout: 60,
maxRetries: 2,
);Parameters
$apiKey?stringYour API key. Defaults to the RUNCONVERT_API_KEY environment variable.$baseUrlstringDefaults to https://api.runconvert.com/v3.$timeoutintSeconds per API request. Default 60. Uploads and downloads have no limit.$maxRetriesintRetries for network errors, 429 and 5xx. Default 2.
Quick start
Convert a file in one call: the SDK uploads it, converts it, waits for the job and saves the result.
Example
use RunConvert\RunConvert;
$rc = new RunConvert();
$result = $rc->convert('report.docx', 'pdf', ['out_dir' => 'out']);
print_r($result->saved); // ['out/report.pdf']Array ( [0] => out/report.pdf )Convert
Convert a file
$rc->convert($file, string $to, array $opts = []): ConvertResultConverts one file in one call: uploads a local file (or imports a URL), converts it, waits for the job and, when an output folder is given, downloads the result. Uses credits.
Example
$result = $rc->convert('report.docx', 'pdf', ['out_dir' => 'out']);
print_r($result->saved);// Imported by RunConvert: nothing to upload
$result = $rc->convert('https://example.com/talk.mp4', 'mp3', ['out_dir' => 'out']);$rc->convert('talk.mp4', 'mp3', [
'options' => ['audioBitrate' => '192k'],
'out_dir' => 'out',
]);$rc->convert('movie.mov', 'mp4', [
'out_dir' => 'out',
'timeout' => 600,
'on_update' => fn (array $job) => print($job['status'] . PHP_EOL),
]);Array ( [0] => out/report.pdf )Array ( [0] => out/talk.mp3 )waiting
processing
finishedParameters
$filestring|resourceA local path, an http(s) URL (imported by RunConvert), or a stream.Required$tostringThe target format, e.g. "pdf" or "mp3".Required'from'stringThe source format. Read from the file name or URL when left out; needed for bytes or streams without a filename.'options'arrayEngine options for the conversion, e.g. audioBitrate or image_quality. List them with Formats → engines for a pair.'out_dir'stringSave the results in this folder (created if needed). Without it nothing is downloaded; use the result's files.'filename'stringThe file's name when you pass bytes or a stream.'tag'stringA label to find the job later, e.g. "invoices".'timeout'floatSeconds to wait for the job before giving up.'on_update'callableCalled with the job after every check, e.g. to show progress.
Returns
ConvertResult with ->job (the finished job), ->files (each with filename, url and size) and ->saved (local paths, when out_dir is set).
Jobs
Create a job
$rc->jobs->create(array $tasks, ?string $tag = null, ?array $metadata = null): arrayCreates a job from named tasks that run in order: import → convert → export. Tasks refer to each other by name in input. The job comes back with its tasks; an upload task carries the upload_url to send your file to.
Example
$job = $rc->jobs->create([
'a' => ['operation' => 'import/url', 'source_url' => 'https://example.com/cover.pdf'],
'b' => ['operation' => 'import/url', 'source_url' => 'https://example.com/body.pdf'],
'merge' => ['operation' => 'convert', 'input' => ['a', 'b'], 'input_format' => 'pdf', 'output_format' => 'pdf'],
'export' => ['operation' => 'export/url', 'input' => 'merge'],
], tag: 'merge');use RunConvert\Jobs;
$job = $rc->jobs->create([
'upload' => ['operation' => 'import/direct/upload'],
'convert' => ['operation' => 'convert', 'input' => 'upload', 'input_format' => 'png', 'output_format' => 'webp', 'image_quality' => 80],
'export' => ['operation' => 'export/url', 'input' => 'convert'],
]);
$rc->files->upload(Jobs::task($job, 'upload'), 'image.png');Parameters
$tasksarrayNamed task definitions. Names use letters, digits, - or _ (up to 64 characters).Required$tag?stringA label to find the job later, e.g. "invoices".$metadata?arrayYour own key-value data, returned with the job and in webhooks.
Returns
The job, with its tasks.
Get a job
$rc->jobs->get(string $id): arrayGets one job with its tasks: status, credits used, and the result files of its export tasks.
Example
$job = $rc->jobs->get('job_01hx4k9m2p7w');
echo $job['status'];{
"id": "job_01hx4k9m2p7w",
"status": "finished",
"tag": "invoices",
"credits_used": 2,
"created_at": "2026-11-16T09:12:04Z",
"ended_at": "2026-11-16T09:12:09Z",
"tasks": [
{ "name": "import-1", "operation": "import/direct/upload", "status": "finished" },
{ "name": "convert-1", "operation": "convert", "status": "finished" },
{ "name": "export-1", "operation": "export/url", "status": "finished",
"result": { "files": [
{ "filename": "report.pdf", "size": 72841, "url": "https://storage.runconvert.com/…/report.pdf" }
] } }
]
}Parameters
$idstringThe job's ID.Required
Returns
The job, with its tasks.
List jobs
$rc->jobs->list(?string $status = null, ?string $tag = null, ?int $page = null, ?int $perPage = null, bool $includeTasks = false): arrayOne page of jobs, newest first, with paging details. Filter by status or tag.
Example
$page = $rc->jobs->list(status: 'finished', perPage: 20);
foreach ($page['data'] as $job) {
echo $job['id'], PHP_EOL;
}{
"data": [ { "id": "job_01hx4k9m2p7w", "status": "finished", … } ],
"meta": { "page": 1, "per_page": 20, "total": 42, "total_pages": 3 }
}Parameters
$status?stringOnly jobs with this status: waiting, processing, finished, error or canceled.$tag?stringA label to find the job later, e.g. "invoices".$page?intPage number, from 1.$perPage?intJobs per page (max 100).$includeTasksboolInclude each job's tasks.
Returns
One page: ['data' => [jobs], 'meta' => [page, per_page, total, total_pages]].
Every job
$rc->jobs->all(?string $status = null, ?string $tag = null, ?int $perPage = null): GeneratorEvery job, page by page, so you can loop over all of them without handling pages yourself.
Example
foreach ($rc->jobs->all(tag: 'invoices') as $job) {
echo $job['id'], ' ', $job['status'], PHP_EOL;
}Parameters
$status?stringOnly jobs with this status: waiting, processing, finished, error or canceled.$tag?stringA label to find the job later, e.g. "invoices".$perPage?intJobs per page (max 100).
Wait for a job
$rc->jobs->wait(string $id, ?float $timeout = null, ?callable $onUpdate = null, bool $throwOnError = true): arrayPolls a job until it finishes (every 0.7 s, slowing to 3 s). Fails with the task's code and reason if the job fails, and stops after the timeout if you give one.
Example
$done = $rc->jobs->wait($job['id'], timeout: 300);
foreach (Jobs::exportedFiles($done) as $file) {
$rc->files->download($file, 'out');
}use RunConvert\JobFailedException;
try {
$rc->jobs->wait($job['id']);
} catch (JobFailedException $e) {
$task = $e->getTask();
echo $task['code'], ' ', $task['reason'], ' ', $task['message'];
}Parameters
$idstringThe job's ID.Required$timeout?floatSeconds to wait. Throws WaitTimeoutException after it.$onUpdate?callableCalled with the job after every check, e.g. to show progress.$throwOnErrorboolFail when the job ends in error (default). Turn off to get the failed job back instead.
Returns
The finished job.
Cancel a job
$rc->jobs->cancel(string $id): arrayCancels a job's pending tasks. Credits for tasks that didn't finish are refunded.
Example
$rc->jobs->cancel('job_01hx4k9m2p7w');Parameters
$idstringThe job's ID.Required
Returns
The canceled job.
Delete a job
$rc->jobs->delete(string $id): voidDeletes a job and its files.
Example
$rc->jobs->delete('job_01hx4k9m2p7w');Parameters
$idstringThe job's ID.Required
Result files
Jobs::exportedFiles(array $job): arrayThe files produced by a finished job's export tasks: file name, a temporary download URL and size.
Example
use RunConvert\Jobs;
foreach (Jobs::exportedFiles($job) as $file) {
echo $file['filename'], ' ', $file['url'], PHP_EOL;
}[
{ "filename": "report.pdf", "size": 72841, "url": "https://storage.runconvert.com/…/report.pdf" }
]Parameters
$jobarrayA finished job, with its tasks.Required
Files
Upload a file
$rc->files->upload(array|string $task, $file, ?string $filename = null): voidSends a file to an import/direct/upload task before its deadline. Use it with a job you created yourself.
Example
$rc->files->upload(Jobs::task($job, 'upload'), 'image.png');Parameters
$taskarray|stringThe upload task from the created job, or its upload URL.Required$filestring|resourceA local path or a stream.Required$filename?stringThe file's name when you pass bytes or a stream.
Download a result
$rc->files->download(array|string $file, string $dir, ?string $filename = null): stringSaves a result file into a folder, keeping its name, and returns the path. Streams, so big files use little memory.
Example
foreach (Jobs::exportedFiles($job) as $file) {
echo $rc->files->download($file, 'out'), PHP_EOL;
}out/report.pdfParameters
$filearray|stringA result file from a job's export task, or its URL.Required$dirstringThe folder to save into.Required$filename?stringSave under this name instead.
Returns
The saved file's path.
Formats
List formats
$rc->operations->list(?string $category = null): arrayEvery input format and what it converts to. Public: no API key needed.
Example
$catalog = $rc->operations->list('audio');
echo count($catalog['formats']);Parameters
$category?stringOnly one category: document, image, video, audio, ebook, archive, font, cad, …
Targets for a format
$rc->operations->forInput(string $input): arrayWhat one format converts to, with the credit cost of each conversion. Public.
Example
$mp4 = $rc->operations->forInput('mp4');
foreach ($mp4['outputs'] as $o) {
echo $o['format'], ' ', $o['credits'], PHP_EOL;
}{
"format": "mp4",
"category": "video",
"outputs": [
{ "format": "mp3", "category": "audio", "engine": "ffmpeg", "credits": 1 },
{ "format": "gif", "category": "image", "engine": "ffmpeg", "credits": 4 },
…
]
}Parameters
$inputstringThe input format, e.g. "mp4".Required
Engines for a pair
$rc->operations->forPair(string $input, string $output): arrayThe engines for one conversion and the options its convert task accepts, e.g. bitrate or quality. Public.
Example
$pair = $rc->operations->forPair('mp4', 'mp3');
foreach ($pair['engines'][0]['options'] as $opt) {
echo $opt['name'], PHP_EOL;
}{
"input": "mp4",
"output": "mp3",
"engines": [
{ "name": "ffmpeg", "credits": 1,
"options": [
{ "name": "audioBitrate", "type": "string",
"description": "Target audio bitrate in kbps.",
"supported_values": ["32k", "48k", "64k", "80k", …] },
…
] }
]
}Parameters
$inputstringThe input format, e.g. "mp4".Required$outputstringThe output format, e.g. "mp3".Required
Account
Credits and team
$rc->me(): arrayThe account, team and credit balance behind the API key.
Example
echo $rc->me()['credits']['total_remaining'];{
"user": { "email": "[email protected]", "full_name": "Ada Lovelace" },
"team": { "name": "Acme" },
"credits": { "mode": "wallet", "total_remaining": 4820 }
}Webhooks
Verify a signature
Webhooks::verify(string $rawBody, ?string $signature, string $secret): boolChecks that a webhook delivery really came from RunConvert: an HMAC-SHA256 of the raw request body with your webhook secret, compared with the X-RunConvert-Signature header in constant time.
Example
use RunConvert\Webhooks;
$ok = Webhooks::verify(
file_get_contents('php://input'),
$_SERVER['HTTP_X_RUNCONVERT_SIGNATURE'] ?? null,
getenv('RUNCONVERT_WEBHOOK_SECRET'),
);Parameters
$rawBodystringThe raw request body, exactly as received (not parsed JSON).Required$signature?stringThe X-RunConvert-Signature header.Required$secretstringYour webhook's signing secret.Required
Parse an event
Webhooks::constructEvent(string $rawBody, ?string $signature, string $secret): arrayVerifies the signature and parses the event in one step. Fails if the signature is wrong.
Throws UnexpectedValueException when the signature doesn't match: answer 400 and ignore the request. On Laravel, the runconvert-laravel package does this for you.
Example
use RunConvert\Webhooks;
try {
$event = Webhooks::constructEvent(
file_get_contents('php://input'),
$_SERVER['HTTP_X_RUNCONVERT_SIGNATURE'] ?? null,
getenv('RUNCONVERT_WEBHOOK_SECRET'),
);
} catch (UnexpectedValueException $e) {
http_response_code(400);
exit;
}
if ($event['event'] === 'job.finished') {
error_log('done ' . $event['job']['id']);
}{
"event": "job.finished",
"job": { "id": "job_01hx4k9m2p7w", "status": "finished", … }
}Parameters
$rawBodystringThe raw request body, exactly as received (not parsed JSON).Required$signature?stringThe X-RunConvert-Signature header.Required$secretstringYour webhook's signing secret.Required
More
Errors
Every failure is a typed error. The API's code tells you what happened, for example BILLING_INSUFFICIENT_CREDITS, UNAUTHORIZED or INVALID_DATA.
Example
use RunConvert\JobFailedException;
use RunConvert\RunConvertException;
try {
$rc->convert('report.docx', 'pdf', ['out_dir' => 'out']);
} catch (JobFailedException $e) {
echo 'conversion failed: ', $e->getTask()['reason'];
} catch (RunConvertException $e) {
echo $e->getStatus(), ' ', $e->getErrorCode(), ' ', $e->getMessage();
}422 BILLING_INSUFFICIENT_CREDITS Insufficient credits.Error types
RunConvertExceptionclassThe API said no: getStatus() (HTTP status), getErrorCode() (e.g. BILLING_INSUFFICIENT_CREDITS), getMessage().JobFailedExceptionclassThe job ended in error: getJob(), and getTask() with code, reason and message.WaitTimeoutExceptionclasswait() ran past its timeout: getJob() is the job as last seen.
Retries and timeouts
Network errors, rate limits (429) and server errors (5xx) are retried twice with backoff, honouring Retry-After. Creating a job is only retried when the request never reached the API, so a job is never created twice.
Example
$rc = new RunConvert(maxRetries: 4, timeout: 30);