Guide

Quickstart

Convert your first file in five minutes.

This guide takes you from zero to a converted file in about five minutes. You'll create a job that converts a remote image to PNG, wait for it to finish, and download the result. The examples use curl, but any HTTP client (or our PHP SDK) works the same way.

You'll need: an api2convert account with an API key (step 1) and curl installed.

1. Get an API key

Create a free account — every registered user gets 30 free credits every 24 hours, enough to start converting right away — then generate an API key from your dashboard. Every request is authenticated by sending that key in the x-oc-api-key header. In the examples below, replace <your-api-key> with your real key. More detail in Authentication.

2. Create and start a job

A job holds your inputs (the files to convert) and conversions (what to produce). With process: true it starts converting right away. This request body converts a remote image to PNG:

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

Save it as job.json and send it to POST /v2/jobs:

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 is your new job. Note the id — you'll use it in the next step:

{
  "id": "8daae6d1-26e0-11e5-b2a1-0800273b325b",
  "token": "12srxin63mgp23f8mtny2rgtgl1nl39i",
  "status": "incomplete",
  "output": []
}

3. Wait for it to finish

Conversions run in the background, so check the job until its status is completed (or failed). Request the same job by its id every few seconds:

curl https://api.api2convert.com/v2/jobs/8daae6d1-26e0-11e5-b2a1-0800273b325b \
  -H "x-oc-api-key: <your-api-key>"

When status becomes completed, the finished files appear under output, each with a download uri:

{
  "id": "8daae6d1-26e0-11e5-b2a1-0800273b325b",
  "status": "completed",
  "output": [{
    "uri": "https://www2.api2convert.com/v2/dl/web7/example.png",
    "name": "example.png",
    "content_type": "image/png"
  }]
}
In production, prefer webhooks over polling — set a callback URL on the job and get notified the moment it finishes.

4. Download the result

Take the uri from the output above and fetch it to save the converted file:

# replace the URL with the uri from your own job's output (step 3) — it is unique per job
curl -o example.png "https://www2.api2convert.com/v2/dl/web7/example.png"
Download URLs are valid for 24 hours. If the job was created with download_password, send it in the x-oc-download-password header.

That's the whole flow: create & start → poll → download. 🎉

Next steps