Download the PHP package api2convert/sdk without Composer

API2Convert PHP SDK

The official PHP client for the API2Convert file-conversion API. Convert, compress and transform images, documents, audio, video, ebooks, archives and CAD — and run operations like OCR, merge, thumbnail and website capture — in one line of code.

That single call creates a job, uploads your file, starts it, waits for it to finish and gives you back a result you can save. No polling loops, no manual upload handling.

Requirements

• PHP 8.2+
• A Guzzle HTTP client (or any other PSR-18 client)

Install

Get an API key from the API2Convert dashboard / documentation.

Quick start

convert($input, $to, $options = []) — $input is a local path, a public URL, or an open stream/resource; $to is the target format; $options are the conversion options for that target. Less-common controls are named arguments: category, timeout, outputIndex, filename, downloadPassword. The returned ConversionResult lets you:

Password-protect the result

Pass downloadPassword and the output is locked behind it. The SDK remembers the password and sends it automatically when you download — you don't pass it again:

The download URL still needs the password from anywhere else (a browser, cURL, another process), via the X-Api2convert-Download-Password header. When you already hold an OutputFile — e.g. from the Jobs API — hand the password to download():

Asynchronous conversions & webhooks

For long-running jobs, start the conversion and get notified via a webhook instead of waiting:

In your webhook handler, verify and parse the callback:

Signed webhooks are being rolled out. Until they are enabled for your account no signature is sent — call Api2Convert::webhooks()->parse($payload) (or pass an empty secret) to deserialize the callback without verifying.

Cloud storage

Read an input straight from your own S3, Azure, FTP or Google Cloud storage, and/or deliver the converted output into a bucket — no re-uploading, no re-downloading.

Read the input from S3. A CloudInput is a started job, just like a remote URL — build it with the per-provider factory (flat, lowercase keys, exactly as the API expects) and save the result locally:

azure(container, file, accountname, accountkey), ftp(host, file, username, password) and googleCloud(projectid, bucket, file, keyfile) work the same way.

Deliver the output to S3. Attach one or more OutputTargets via outputTargets. When a target is set the conversion delivers straight to your storage and there's no local download:

Credentials ride in the request body but are redacted in exception messages and when a CloudInput/OutputTarget is printed or logged (credentials renders as [REDACTED]) — they are never surfaced on read.

Error handling

Every failure is a typed exception extending Api2Convert\Exception\Api2ConvertException:

Transient failures (429, 5xx, network errors) are retried automatically with exponential backoff.

Power user: the full job API

convert() is sugar over the Jobs API. Drop down to it for compound jobs, merges, presets, custom polling or job chaining:

Available resources: jobs(), conversions() (the catalog + option discovery), presets(), stats(), contracts().

Discover the valid options for any target:

Configuration

Bring your own PSR-18 client (e.g. Symfony HttpClient) by passing it as the third argument.

Security — never publish your API key

• Never hard-code or commit your API key. Load it from the environment (API2CONVERT_API_KEY) or a secrets manager.
• In CI, store it as a masked & protected variable (this repo's pipeline reads $API2CONVERT_API_KEY) and never print it to logs.
• Treat the per-job upload token and your webhook signing secret with the same care.
• The SDK never logs your key/token and never puts them in exception messages.
• If a key is ever exposed, revoke and rotate it in the API2Convert dashboard immediately.

Development

The live conformance suite runs against the real API when API2CONVERT_API_KEY is set (it auto-skips otherwise):

It runs automatically against the real API on every release tag (see .github/workflows/live-conformance.yml), so a published version is always verified end to end. Each test mirrors one of the runnable examples below, plus two negative tests (an unknown target is a typed validation error; a bad key is a typed auth error that never leaks the key).

Examples

Every example in examples/ is a complete, self-contained program that reads your key from API2CONVERT_API_KEY. Run any of them with, e.g.:

This SDK is hand-written and kept in sync with the API by an AI agent — see AGENTS.md and docs/SDK_CONTRACT.md. Notable changes are recorded in docs/CHANGELOG.md.

License

MIT — see LICENSE.