Convert files

The core of the api2convert API is format conversion: you send a job describing one or more source files and the target you want them converted to. This guide explains how a conversion entry is built, how to discover the targets and options available for any format, and walks through a complete remote JPG to PNG example.

The conversion entry

Every job contains a conversion array. Each entry has three parts: a category (the kind of target — document, image, audio, video, archive, ebook, or operation), a target (the concrete format or operation, e.g. png), and an optional options object that tunes the result.

{
  "conversion": [
    {
      "category": "image",
      "target": "png",
      "options": {}
    }
  ]
}

For an actual format conversion, the category names the media type and the target is the file extension (lowercase). When you instead want a transformation that is not a format change — such as rotating or merging — use "category": "operation" with the operation name as the target. Browse every operation in the Formats Explorer.

Discovering targets and options

Every format declares which targets it can convert to and which options each target accepts. Rather than guessing, query them at runtime with GET /v2/conversions, which lists all source/target combinations and their option schemas.

curl https://api.api2convert.com/v2/conversions \
  -H "x-oc-api-key: <your-api-key>"

You can filter by source and target to narrow the response:

curl "https://api.api2convert.com/v2/conversions?source=jpg&target=png" \
  -H "x-oc-api-key: <your-api-key>"

The same data is browsable visually in the Formats Explorer, where you can pick a source and target and see every supported option with its allowed values.

Example: convert a remote JPG to PNG

This job downloads a JPG from a public URL and converts it to PNG. The input entry points at the remote file; the single conversion entry sets the target.

{
  "input": [
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
    }
  ],
  "conversion": [
    {
      "category": "image",
      "target": "png"
    }
  ]
}

Send it to the jobs endpoint:

curl -X POST https://api.api2convert.com/v2/jobs \
  -H "x-oc-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d @job.json

The response returns a job id you can poll until the converted PNG is ready for download. To attach options — for example a fixed output width — add them under options:

{
  "conversion": [
    {
      "category": "image",
      "target": "png",
      "options": {
        "width": 1920
      }
    }
  ]
}

Pick a format

Use the picker below to choose a target format and see the conversion entry to drop into your job. The available options for each pairing mirror what GET /v2/conversions returns.

Common option types

Options vary per target, but several recur across formats:

Always confirm the exact option names and accepted values for your specific source/target pair via GET /v2/conversions or the Formats Explorer — passing an unsupported option will be rejected.