FileConvert support
50 answers written against what this service actually does — converting files, the formats and options that exist, the API, how long anything is kept, and what to do when a conversion will not run.
Filters every answer below as you type. Press Escape to clear it.
Browse by topic 50 answers
Your first conversion, what an account is for, and where the limits are.
No. The converter on the home page and every /x-to-y tool page is open — there is no sign-in wall and no CSRF token, because the form takes a file and hands one back without touching any account state.
An account exists only so you can mint and revoke API keys from the account page. If you are never going to call the API, you never need one.
Drop one or more files onto the converter, choose the target format, and press Convert. On a tool page such as /png-to-jpg the target is already set, so there is nothing to choose.
A single input comes back as a single file. Several inputs come back as one ZIP.
Two hundred per batch by default, controlled by FC_MAX_BATCH_SIZE. PHP has its own ceiling as well — max_file_uploads — and whichever is lower wins.
Per-file size is capped at 256 MiB by default (FC_MAX_UPLOAD_BYTES), again bounded by PHP upload_max_filesize.
There is a full CLI. It runs the same converters as the web form and the API, with no upload ceiling and no execution timeout, which makes it the right tool for anything large or scripted. Exit codes are stable: 0 success, 1 the work failed, 2 the command line was wrong, 3 a required tool is missing, 4 interrupted.
php cli.php convert photo.heic photo.jpg --quality=88
php cli.php batch 'shoot/*.CR2' --to=jpg --out=web --quality=85See the pricing page for the current plans.
Underneath, every job record carries a credits figure: billable processing seconds rounded up to the minute. Import and export steps are not counted — only the work itself, such as converting, optimising, thumbnailing, watermarking, merging, archiving and metadata.
Batches, URLs, multi-page output and chaining several steps into one job.
It is staged in a temporary directory unique to that one request, converted in place, and the directory is removed by a shutdown handler when the response finishes. Nothing from the web form is written into the service storage area.
Files submitted through the API are different — those belong to a job and live until the job expires. See Privacy and security below.
Because more than one file came out. A batch, or a single conversion that produces several outputs, is packed into one archive so the browser only has to handle one download.
Yes, through the API import/url operation. Give it a URL and it fetches the file server-side.
The URL goes through an SSRF guard first: http and https only, the hostname is resolved and every address it returns is checked, and private, loopback and link-local ranges are refused. Redirects are re-checked at every hop.
curl -sS -X POST "$FC_API/jobs" \
-H "Authorization: Bearer $FC_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"tasks":{
"in": {"operation":"import/url","url":"https://example.com/in.docx"},
"pdf": {"operation":"convert","input":"in","output_format":"pdf"},
"out": {"operation":"export/url","input":"pdf"}}}'One file per page. A PDF converted to PNG produces page-1.png, page-2.png and so on, and the command or job record lists every file it wrote. Narrow it with the range option, for example 1-5,8.
php cli.php convert report.pdf page.png --density=200 --range=1-5Yes. That is what a job is: a set of named tasks forming a directed acyclic graph, each consuming the output of the tasks it names as input. The whole graph is validated before anything runs, so a typo in a task name is a 422 rather than a half-finished job.
A job may hold up to 50 tasks by default and must end in at least one export task — without one, the work would run and the results would be unreachable.
A couple of seconds, not instantly. Workers poll the queue and sleep between empty polls — two seconds by default. If the wait grows, the queue is outrunning the workers; the fix is more worker processes, not a shorter sleep.
php cli.php queue --jsonWhat converts to what, which options exist, and where fidelity is lost.
Formats are grouped into categories — raster, vector, video, audio, text, office, pdf, ebook, tabular, geo, 3D, archive and font. Anything in a category converts to anything else in the same category, plus a short list of cross-category routes such as PDF to image, video to GIF, video to audio and raster to PDF.
The authoritative answer is the running host, because a format only works if its tool is installed. Ask the server directly.
curl -sS "$FC_API/formats"
curl -sS "$FC_API/tools"
php cli.php doctorBecause the pair is neither inside one category nor on the cross-category list, so it is rejected up front rather than attempted. CSV to JPG and MP3 to DOCX are the classic examples: there is no sensible thing for them to mean, so nothing is guessed.
Images take quality, resize, width, height, strip, background, flatten, colorspace and density. Video takes crf, preset, video_codec, audio_codec, bitrate, audio_bitrate, fps, scale, start, duration and time. Audio takes bitrate, sample_rate, channels, start and duration. PDF takes preset (screen, ebook, printer, prepress), range, density, gray and version.
On the CLI they are --key=value; over the API they are fields on the task.
php cli.php convert clip.mov clip.webm --crf=32 --preset=slowNo. PDF to text extracts text that is already in the file. A scanned PDF is a picture of words and yields nothing at all — run it through the OCR path first, which needs ocrmypdf installed and costs seconds per page.
Office formats are rendered by LibreOffice running headless, so the fidelity is LibreOffice fidelity, not Word fidelity. Complex layouts, unusual fonts and heavily tracked documents drift.
The first office conversion on a fresh host is also noticeably slow, because LibreOffice is building its user profile.
Mesh geometry converts reliably; materials and textures survive unevenly, because assimp does the work and assimp's own format support is the ceiling. glTF and GLB round-trips are better with gltf-pipeline, which preserves Draco compression and PBR extensions that assimp drops — but that is an npm tool and is not in the Docker image.
No — only read one. RAR extraction works, RAR creation is not possible, because unrar is extract-only by licence. Convert to ZIP or 7z instead. Note also that archive conversion extracts and repacks, so it needs disk equal to the uncompressed contents.
Keys, scopes, one-shot calls, rate limits, webhooks and download links.
A bearer token on every route that touches data. The public routes — the index, /health, /formats, /tools and /openapi.json — need no token at all.
Downloads are the exception: /files/{token} authenticates on the token in the URL, not a bearer key, so a link can be handed straight to a browser.
curl -sS "$FC_API/jobs" -H "Authorization: Bearer $FC_TOKEN"From the API keys panel on your account page, or from the CLI. Three scopes exist: task.read for listing and reading jobs, task.write for creating and deleting them, uploading and minting signed URLs, and user.read for key metadata.
Give a key the narrowest scope that works — task.write alone is enough for a pipeline that only submits work.
php cli.php keys:create --scopes=task.read,task.write --label='ci pipeline'A one-shot task. It wraps a single operation in a job with an import and an export, so simple work needs no graph. The response is a job record whose file entries are ready to download.
curl -sS -X POST "$FC_API/tasks/convert" \
-H "Authorization: Bearer $FC_TOKEN" \
-F 'file=@photo.heic' \
-F 'output_format=jpg' \
-F 'quality=88'Six hundred requests a minute per API key and three hundred a minute per client IP by default. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; a 429 also carries Retry-After, which your client should honour rather than retrying faster.
The counters live in the filesystem, so they are per host. Several web containers multiply the effective limit unless they share the storage volume.
Use a webhook for anything slow. The blocking wait endpoint holds a PHP-FPM worker for the whole duration, and a polling loop spends resources you would rather spend on conversions.
Three events fire: job.created, job.finished and job.failed. Registration is deliberately server-side only — there is no HTTP route for it — so a leaked API key cannot redirect your results to somebody else's endpoint. Deliveries are HMAC-signed with the timestamp inside the signed material, so an old body cannot be replayed.
Either pass the download URL as it is — the token in it is the capability, and it expires with the job — or mint a signed URL with its own lifetime. Signed links are HMAC-SHA256 over the payload and compared with a constant-time check, so an expired or edited link is a 403.
curl -sS -X POST "$FC_API/signed" \
-H "Authorization: Bearer $FC_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"job":"'"$JOB_ID"'","ttl":900}'Because a failed job is a perfectly successful HTTP response. Check the job status field, not just the status code: a status of error means a task failed, and the error carries the underlying tool's own message.
Signing in, lockouts, lost keys, credits and deleting what you have made.
Your profile, your password and your API keys. Converting files never requires one — the account page exists so that keys have somewhere to live and something to be revoked from.
That is deliberate. A failed sign-in never says which half was wrong, because saying so would turn the form into a way of testing whether an address has an account.
Failures are counted per email address and per client IP, and enough of them lock further attempts for a few minutes. The message tells you how long. Wait it out rather than retrying, which extends it.
No. Only a SHA-256 hash of the key is stored; the raw token is displayed once, at creation, and cannot be recovered from the server. Revoke the old key and mint a new one.
Each job records credits: billable processing seconds, rounded up to the minute. Import and export steps do not count toward it — only the actual work. A job record also carries created_at, started_at, ended_at, duration and expires_at.
Delete the job, which removes its record and every file it produced immediately. Otherwise everything goes on its own: jobs and their files expire after their TTL, and a scheduled purge removes them.
curl -sS -X DELETE "$FC_API/jobs/$JOB_ID" -H "Authorization: Bearer $FC_TOKEN"Retention, who can reach a download link, and what is deliberately not protected.
Files converted through the web form are not kept at all — they live in a per-request temporary directory that is deleted when the response finishes.
Files belonging to an API job live until the job expires, 24 hours by default (FC_FILE_TTL). Download tokens have their own lifetime, also 24 hours by default. Deletion is done by a scheduled purge command, which the operator of the deployment has to run — nothing else on the system deletes anything.
Anyone holding the link, for as long as it is valid. The download token is the capability: it comes from the cryptographic random source, carries at least 128 bits, and expires with the job. Treat a download URL as you would treat the file itself.
No, and it is better that you read that here than discover it later. Files in the storage area are plaintext on disk. If that matters for your data, run the service on an encrypted volume — the application does not encrypt anything itself.
No. Uploads are validated for size, for a known target format, and for a safe filename — traversal, null bytes and leading dots do not survive — but content is not scanned, and it is not sniffed to prove it matches its extension. The conversion tools are the format validators. A deployment that accepts files from the public internet should put a scanner in front.
It is guarded against exactly that. Only http and https schemes are accepted; the hostname is resolved and every address it returns is checked; loopback, private, link-local, multicast and reserved ranges are refused, which covers the cloud metadata endpoint. Redirects are re-checked at every hop, up to five, which is the check most SSRF filters omit.
A residual DNS-rebinding window remains, because the guard resolves and then the fetcher resolves again. A deployment fetching from genuinely hostile sources should also run an egress proxy.
Not a per-request one. API key use is timestamped, and every request carries a request_id that appears both in the error envelope and in the server log line, which is what to quote when reporting a problem. Individual requests are not attributed to a user anywhere durable.
Running your own copy: Docker, native installs, scheduling and PHP settings.
Docker is the shortest path, because the image carries the whole toolchain and the web tier and the workers are guaranteed to agree about which formats exist. Expect the first build to take 10 to 20 minutes and produce a 3 to 4 GB image — LibreOffice and Calibre are most of that.
Compose starts three things: a web service, one or more workers running queued jobs, and a cron service running the purge loop.
docker compose up --build
docker compose run --rm cli doctorYes, on macOS with Homebrew or Debian and Ubuntu with apt. Run the doctor command before anything else: it reports every binary as installed, missing or installed-but-broken, prints the exact install command for each missing one, and flags PHP settings that will silently truncate uploads.
./install.sh
php cli.php doctor
php -S 127.0.0.1:8807 router.php
php cli.php workerThe purge command, every five to fifteen minutes. It is the only thing that deletes anything: expired job directories, expired export tokens, old queue entries and rate-limiter buckets. Forgetting it is the single most common way to break a deployment, because storage then grows without bound.
*/10 * * * * php /srv/file-convert/cli.php purge --quietFive, and the stock defaults make the web form useless. Want at least: upload_max_filesize 64M, post_max_size 256M, max_file_uploads 50, max_execution_time 300 and memory_limit 512M. Raise the front-end body limit too, or the web server rejects the body before PHP ever sees it.
post_max_size must be larger than upload_max_filesize. If it is not, an upload at the per-file limit fails with an empty file array and no explanation at all. The doctor command reports that specific misconfiguration as an error.
Not safely, and this is stated plainly rather than hedged. Storage is a POSIX directory and the queue claims work with an atomic rename between subdirectories, so all of it must sit on one filesystem where rename is genuinely atomic — NFS is not a safe assumption. Scale by adding worker processes on one host. Workers scale with cores, not memory.
Highest wins: an FC_ environment variable, then config.local.php at the project root, then the built-in default. Environment values are coerced to the type of their default, so a typo in a numeric variable falls back rather than silently becoming zero. A config.local.php that does not return an array is a hard failure at startup, by design.
php cli.php doctor | sed -n '/configuration/,/summary/p'No. The code assumes POSIX paths, POSIX rename semantics and /dev/null. Use WSL, a container or a Unix host.
The failures that actually happen, and the command that identifies each one.
Every one of these is diagnosed by php cli.php doctor or
php cli.php queue. The full runbook — scaling, retention, monitoring,
stuck and failed jobs — is docs/operations.md.
The two formats are not in the same category and the pair is not one of the cross-category routes, so it was refused before any tool ran. This is a rejection, not a crash.
Check what the running host will accept, then pick a route that exists — often via an intermediate format, such as document to PDF to image.
curl -sS "$FC_API/formats"Two different failures with two different fixes. A clean rejection means the file passed the configured maximum — 256 MiB per file by default. A submission that appears to do nothing at all, with no error, usually means the whole POST exceeded post_max_size, in which case PHP discards the body and the uploaded-files array arrives empty.
The CLI has no upload limit and no execution timeout, so if the command line handles a file that the web form will not, the limits above are the first thing to check.
php cli.php doctorLook at queue depth first. If oldest_ready keeps climbing past about a minute, submissions are simply outrunning the workers and the answer is more worker processes.
If a job sits in running with no worker attached, a worker died holding it. It is reclaimed automatically once it is older than the worker timeout — 900 seconds by default — and re-queued. To force that immediately, reap the queue.
php cli.php queue --json
php cli.php queue --list=running
php cli.php queue --reap
php cli.php job:show <id>A format only works when its tool is installed, and a missing tool produces an error naming the binary rather than a silent empty file. Over the API that is a 503: retrying will not help, because the message is telling you something is absent from the server.
Worse than missing is broken: a binary on the PATH that exits non-zero, which surfaces mid-conversion. The most common instance is a LibreOffice shim left behind after the application itself was deleted. The doctor command distinguishes the two and prints the exact install command for each.
php cli.php doctor
curl -sS "$FC_API/tools" | jq '.tools | with_entries(select(.value == false))'The error message carries the underlying tool's own stderr, which is nearly always the actual explanation. "no decode delegate for this image format" means the tool is installed but built without support for that format — a different problem from the tool being absent, and the doctor command tells them apart.
Work through it in order: is the tool installed and working; is the delegate present; does the tool handle this file directly outside the service; and is the file really what its extension claims?
php cli.php doctor
magick -list format | grep -iE 'heic|avif|jp2|dng'
file input.heic401 means the bearer token is missing or invalid — remember that a key is shown only once and cannot be recovered, so a lost key must be replaced rather than looked up. 403 means the token is valid but lacks the scope the route needs; task.write covers creating jobs, uploading and signing, task.read covers reading them.
429 means a rate limit. Honour the Retry-After header rather than retrying faster. Because the counters are per host, an unexpected limit is often several containers not sharing one storage volume.
Three causes, in order of likelihood: a missing or broken tool, which the doctor command names; a full disk, usually because the purge command is not scheduled; and a storage directory that became unwritable after a permissions change that missed the worker's user.
php cli.php doctor
du -sh storage/jobs storage/exports storage/queueNothing here matches that.
Try a shorter word, or clear the box and browse by topic. If the answer genuinely is not here, tell us what you were looking for.
The reference material the answers above are drawn from.
A report carrying the five things below is usually answered in one round trip instead of four.
request_id or the job id. Either one finds
the matching server log line.
php cli.php doctor.
Where to send it
support@fileconvert-prod-hhw93b.westus2.cloudapp.azure.com Usually answered within one working day. Operations runbook Reproducible bugs belong in the project issue tracker, with the details listed alongside. Health endpoint A liveness check you can call yourself. Self-hosted instances should also watch queue depth.