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. Pick your language with the tabs on each example: the cURL tab shows the raw REST calls, while the SDK tabs — Node.js, Python, PHP, Go, .NET, Java, Ruby and Rust — use the matching official SDK, which wraps this whole create → wait → download flow into a single convert() call.

You'll need: an api2convert account with an API key (step 1), and either curl or one of the official SDKs installed — each SDK tab starts with its one-line install command.

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
}

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 '{
    "input": [
        {
            "type": "remote",
            "source": "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
        }
    ],
    "conversion": [
        {
            "category": "image",
            "target": "png"
        }
    ],
    "process": true
}'
On an SDK tab? That single convert() call is the whole quickstart — it creates the job, uploads or links the input, starts it, waits for completion and saves the result, so steps 3 and 4 below are already handled for you. The rest of this page walks the same flow as raw REST calls (the cURL tab).

The raw API responds with your new job. Note the id — the cURL flow uses 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. With raw HTTP you poll — request the same job by its id every few seconds until its status is completed (or failed). The SDK's convert() already waited for you; the SDK tab here shows jobs.get(), which you'd use when you started a job asynchronously:

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. With an SDK, convert() already saved it — the SDK tab shows download(), for when you hold an output file from the Jobs API:

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 — or a single convert() call with an SDK. 🎉

Next steps