File conversion
POST /convert to submit a file conversion. GET /convert/{id} to fetch the result. Async, queued, with webhooks or polling for completion.
The file-conversion API is a single async endpoint pair: submit a file with a target format, get back an ID, fetch the result when ready.
POST /convert, submit a conversion task
Uploads a file (or references one already in your destination) and queues it for conversion.
Request body (multipart/form-data)
| Field | Required | Description |
|---|---|---|
input | yes | The file to convert. Either a multipart file upload, or a string path to an existing file in your destination’s storage. The extension must be one of the supported source formats. |
output_format | yes | Target format extension (e.g. jpg, mp4, pdf). Must be a valid output for the given input. See the format matrix. |
file_name | no | Custom name for the output file in storage. Defaults to {task_id}.{output_format}. |
options[…] | no | Conversion options. See the options reference. Use bracket syntax for nested keys (e.g. options[resize][width]=800). |
Response: 201 Created
{
"id": "9f1a8e7c-1b9b-4f0a-9d2c-1a2b3c4d5e6f",
"status": "queued",
"done": false,
"object": "conversion-task"
}Errors
401 Unauthorized, missing or invalid API key.403 Forbidden, API key cannot create tasks (e.g. account suspended, over plan limits).422 Unprocessable Entity, validation failure (unsupported format, bad option value, missing input).
GET /convert/{id}, fetch a conversion task
Returns the current status of a conversion task.
Response: 200 OK
{
"id": "9f1a8e7c-1b9b-4f0a-9d2c-1a2b3c4d5e6f",
"status": "delivered",
"done": true,
"object": "conversion-task"
}Errors
401,403,404, standard.
Polling responses
The public API returns a single shape: id, status, done, object. There’s no expanded vs. compact distinction. Poll the done boolean (status === "delivered") until the job finishes, or skip polling entirely and use webhooks for completion notifications.
Retrieving the converted file
When the task reaches delivered, the converted file is in your destination’s storage at the path you set with file_name, or {id}.{output_format} by default. You construct the URL or fetch the file directly from your bucket. See Storage destinations for the public-vs.-private bucket details.