Skip to content

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
$ composer require runconvert/runconvert-php

Initializing

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_KEY

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

Convert a file
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 = []): ConvertResult

Converts 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);
Array ( [0] => out/report.pdf )

Parameters

  • $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): array

Creates 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');

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): array

Gets one job with its tasks: status, credits used, and the result files of its export tasks.

Example

Get a job
$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): array

One page of jobs, newest first, with paging details. Filter by status or tag.

Example

Finished jobs
$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): Generator

Every job, page by page, so you can loop over all of them without handling pages yourself.

Example

Loop over all jobs
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): array

Polls 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');
}

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): array

Cancels a job's pending tasks. Credits for tasks that didn't finish are refunded.

Example

Cancel
$rc->jobs->cancel('job_01hx4k9m2p7w');

Parameters

  • $idstringThe job's ID.Required

Returns

The canceled job.

Delete a job

$rc->jobs->delete(string $id): void

Deletes a job and its files.

Example

Delete
$rc->jobs->delete('job_01hx4k9m2p7w');

Parameters

  • $idstringThe job's ID.Required

Result files

Jobs::exportedFiles(array $job): array

The files produced by a finished job's export tasks: file name, a temporary download URL and size.

Example

List results
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): void

Sends a file to an import/direct/upload task before its deadline. Use it with a job you created yourself.

Example

Upload
$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): string

Saves a result file into a folder, keeping its name, and returns the path. Streams, so big files use little memory.

Example

Download
foreach (Jobs::exportedFiles($job) as $file) {
    echo $rc->files->download($file, 'out'), PHP_EOL;
}
out/report.pdf

Parameters

  • $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): array

Every input format and what it converts to. Public: no API key needed.

Example

Audio formats
$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): array

What one format converts to, with the credit cost of each conversion. Public.

Example

What MP4 converts to
$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): array

The engines for one conversion and the options its convert task accepts, e.g. bitrate or quality. Public.

Example

MP4 → MP3 options
$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(): array

The account, team and credit balance behind the API key.

Example

Credits left
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): bool

Checks 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

Verify
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): array

Verifies 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

Plain PHP
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

Handle errors
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

Tune retries
$rc = new RunConvert(maxRetries: 4, timeout: 30);

Like RunConvert? Set us as a preferred source on Google.

Add to Preferred Sources