# api2convert — full documentation

> Every api2convert developer guide concatenated into a single file for LLM ingestion (the
> llms-full.txt convention). For the concise link index see https://www.api2convert.com/llms.txt.

api2convert is a hosted REST API that converts, compresses, and transforms files — images,
video, audio, documents, ebooks, archives and CAD. Base URL: `https://api.api2convert.com/v2/`
(HTTPS, JSON in and out). Authenticate with the `x-oc-api-key` request header.

Authoritative, always-current references (fetch these for exact fields, targets and options):

- OpenAPI schema: https://api.api2convert.com/v2/schema
- Supported conversions & options: https://api.api2convert.com/v2/conversions
- Job status codes: https://api.api2convert.com/v2/statuses
- Agent skill (SKILL.md): https://www.api2convert.com/skills/api2convert-api/SKILL.md

The guides below are rendered from the live documentation. Interactive option builders are
omitted here — query /v2/conversions for the current per-target option schemas.

---

# Quickstart

> Convert your first file in five minutes.
> Source: https://www.api2convert.com/documentation/guides/quickstart

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](https://www.api2convert.com/documentation/guides/sdks), 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](https://www.api2convert.com/documentation/guides/sdks) installed — each SDK tab starts with its one-line install command.

## 1. Get an API key

[Create a free account](https://www.api2convert.com/register) — 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](https://www.api2convert.com/documentation/guides/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:

```json
{
  "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`:

```bash
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:

```json
{
  "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:

```bash
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`:

```json
{
  "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](https://www.api2convert.com/documentation/guides/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:

```bash
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](https://www.api2convert.com/documentation/guides/sdks). 🎉

## Next steps

- [Add conversion options](https://www.api2convert.com/documentation/guides/convert-files) (quality, size, pages…)
- [Upload your own files](https://www.api2convert.com/documentation/guides/uploading-files) instead of using a remote URL
- [Send results to cloud storage](https://www.api2convert.com/documentation/guides/output-storage) (S3, Google Drive…)
- Try every endpoint live in the [API Reference](https://www.api2convert.com/documentation/reference)

---

# Authentication & API keys

> Authenticate requests with your API key or a job token.
> Source: https://www.api2convert.com/documentation/guides/authentication

The API uses key-based authentication sent in HTTP headers. There is no OAuth flow — you pass your key (or a job token) directly on each request.

## Getting an API key

Generate an API key from your api2convert account. Keep it secret: anyone with the key can create jobs and consume your credits.

## API key header

Authenticate user-level requests with the `x-oc-api-key` header:

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

## Job tokens

Each job also has a `token`. A token grants access to that single job only and can be used in place of the API key via the `x-oc-token` header — useful for handing a client temporary, scoped access to one job.

```bash
curl https://api.api2convert.com/v2/jobs/<job-id> \
  -H "x-oc-token: <job-token>"
```

## Public endpoints

A few read-only endpoints need no authentication, including `GET /v2/conversions`, `GET /v2/presets` and `GET /v2/statuses`.

## Free vs. paid

Every registered user gets **30 free credits every 24 hours**; paid plans add higher quotas for professional use. Your plan determines quotas and concurrency — see [Rate limits & contracts](https://www.api2convert.com/documentation/guides/rate-limits).

Never embed your API key in client-side code or public repositories. For browser/native clients, proxy requests through your backend and hand out per-job tokens.

---

# Security & data protection

> Keep your API key safe, secure your integration, and how api2convert protects your data.
> Source: https://www.api2convert.com/documentation/guides/security

This guide has two parts: how to secure **your** integration with the API, and how api2convert protects the data you send us. For the mechanics of authenticating a request, see [Authentication & API keys](https://www.api2convert.com/documentation/guides/authentication).

## Securing your integration

### Keep your API key secret

Your API key authenticates every request and spends your credits, so treat it like a password. Keep it on your **server** — never embed it in browser JavaScript, mobile apps, or public repositories. For client-side or native apps, proxy requests through your own backend and hand out per-job tokens instead of the key.

### Use scoped job tokens

Each job has its own `token`. A token grants access to that **single** job and can be sent in the `x-oc-token` header in place of your API key — ideal for giving a client temporary, least-privilege access to one job's status and outputs without exposing your key.

### Rotate a key if it leaks

Keys are self-service: you can hold more than one and add or remove them at any time from your account's [API keys page](https://account.api2convert.com/user/apikeys). There is no single "regenerate" button — to rotate a compromised key, create a new one, move your integration over to it, then delete the old key. Deleting a key takes effect immediately.

### Always use HTTPS

Call the API over HTTPS so your key and payloads are encrypted in transit. Plain-HTTP requests are rejected with `426 Upgrade Required` — switch the scheme to `https://` and retry.

### Verify webhook callbacks

Webhook payloads are **not** cryptographically signed, and the sender does not verify your endpoint's TLS certificate. Don't act on a callback body blindly: re-fetch the job with your own API key (`GET /v2/jobs/{id}`) to confirm it's really yours before doing anything with it. Make your handler idempotent — see [Webhooks & callbacks](https://www.api2convert.com/documentation/guides/webhooks).

### Protect sensitive files

You control how long your data lives and who can reach it:

- Password-protect a result with a `download_password`; downloading it then requires the `x-oc-download-password` header.
- Delete a result early — `DELETE /v2/jobs/{id}/output/{output-id}` disables a single processed file so its download link stops working immediately; `DELETE /v2/jobs/{id}` removes the whole job. (Files are purged automatically when the job expires, but this revokes access right away.)
- Set `"delete_after_use": true` on an input — at job creation, or later with `PATCH /v2/jobs/{id}/input/{input-id}` — to have the uploaded source file deleted from our servers when the job finishes (whether it completes or fails).
- Download URLs expire automatically after **24 hours** — see [Output & cloud storage](https://www.api2convert.com/documentation/guides/output-storage).

```
"input": [{
  "type": "remote",
  "source": "https://your-app.example.com/private/report.docx",
  "parameters": { "delete_after_use": true }
}]
```

When you export results to your own cloud storage, the provider

credentials

you send are secrets — scope them to a single bucket/folder and rotate them like any other credential.

### Handle limits gracefully

Hitting your contract's concurrency cap returns `429 Too Many Requests` (back off and retry with exponential backoff); exhausting your quota returns `402 Payment Required`. Prefer [webhooks](https://www.api2convert.com/documentation/guides/webhooks) over tight polling loops. See [Rate limits & contracts](https://www.api2convert.com/documentation/guides/rate-limits).

## How api2convert protects your data

On our side, your files and credentials are protected at several layers:

- **Encryption in transit** — all API traffic is served over TLS.
- **Encryption at rest** — our servers use full-disk encryption, backups are encrypted, and any cloud-storage credentials you provide are additionally encrypted at the application layer before they are stored.
- **Password protection** — download passwords are stored only as salted hashes and verified in constant time; we never keep the plaintext.
- **Data lifecycle** — download links expire after 24 hours, and `delete_after_use` lets you remove source files as soon as a job is done.
- **Abuse protection** — traffic passes through DDoS mitigation and rate limiting at the edge.
- **Isolated infrastructure** — processing systems and datastores run on a private network and are not reachable from the public internet.
- **Vulnerability management** — our dependencies are continuously screened against known security advisories.

> Encryption at rest protects stored data on our infrastructure (for example, against physical disk access). It is not a substitute for the safeguards above that are yours to apply — keeping your key secret, using HTTPS, and verifying callbacks.

## Reporting a security issue

Found a vulnerability? Please report it responsibly to [time2help@api2convert.com](mailto:time2help@api2convert.com) and give us a reasonable window to investigate and fix it before any public disclosure.

---

# Jobs & lifecycle

> How jobs, conversions, inputs and outputs fit together.
> Source: https://www.api2convert.com/documentation/guides/job-lifecycle

Everything in the API revolves around the **job**. A job groups the files you send in, the conversions to run, and the files produced.

## The data model

- **Job** — the unit of work. Has an `id`, a `token`, a `status`, and the flags below.
- **input[]** — the source files (remote URL, upload, base64, cloud…). See [Importing files](https://www.api2convert.com/documentation/guides/uploading-files).
- **conversion[]** — what to produce: a `category` + `target` + `options`.
- **output[]** — the resulting files, each with a download `uri`.

> Unlike a task-graph API, api2convert jobs are flat: a job has inputs, conversions and outputs as parallel lists rather than a dependency graph.

## Job flags

| Flag | Purpose |
| --- | --- |
| `process` | Start the job immediately after creation. If `false`, the job stays `incomplete` until you PATCH it with `process: true`. |
| `fail_on_input_error` | Fail the whole job if any input cannot be fetched. |
| `fail_on_conversion_error` | Fail the whole job if any conversion errors. |
| `callback` | URL notified when the job finishes — see [Webhooks](https://www.api2convert.com/documentation/guides/webhooks). |

## Statuses

Typical progression: `incomplete` → `ready` → `running` → `completed` (or `failed`). The authoritative list is available at `GET /v2/statuses`.

## Building a job incrementally

Instead of one big POST, you can build a job step by step and start it last:

```
POST   /v2/jobs                      → create (process: false)
POST   /v2/jobs/{id}/input           → add input file(s)
POST   /v2/jobs/{id}/conversions     → add a conversion
PATCH  /v2/jobs/{id}                  → { "process": true }  (start)
GET    /v2/jobs/{id}                  → poll status / read output
GET    /v2/jobs/{id}/history          → audit trail of the job
```

## Modifying a job after creation (PATCH)

While a job is still `incomplete` — created but not yet started — you can adjust its parts with `PATCH`. Authenticate with the `x-oc-api-key` header.

| Endpoint | What you can change |
| --- | --- |
| `PATCH /v2/jobs/{id}` | Start the job (`process: true`), or update job-level fields such as `callback`, `notify_status`, `fail_on_input_error` and `download_passwords`. |
| `PATCH /v2/jobs/{id}/input` | Reorder inputs (`position`), and set per-input `slide_duration` (slideshow timing) or `resize_handling`. |
| `PATCH /v2/jobs/{id}/input/{input-id}` | Set the `decrypt_password` for a single password-protected input. |
| `PATCH /v2/jobs/{id}/conversions/{conversion-id}` | Change a conversion's `options`, or insert/update/delete file `metadata`. |
| `PATCH /v2/jobs/{id}/output/{output-id}` | Rename the output (`filename`) or set a `download_password`. |

### Reorder inputs

When several inputs are combined into one file, the output order follows each input's `position` (1-based). After the inputs are added, send one `PATCH` with the new positions — an array of `{ id, options: { position } }`, where `id` is the input id returned when it was added:

```bash
curl -X PATCH "https://api.api2convert.com/v2/jobs/<job-id>/input" \
  -H "x-oc-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '[
    {
        "id": "<cover-input-id>",
        "options": {
            "position": 1
        }
    },
    {
        "id": "<report-input-id>",
        "options": {
            "position": 2
        }
    }
]'
```

> `position` is 1-based and must be between 1 and the number of inputs. The same endpoint also accepts `slide_duration` (0.1–120 seconds, for slideshows) and `resize_handling` (`keep_aspect_ratio` or `stretch`).

### Change a conversion's options

Adjust a conversion you already added — without recreating the job — by patching it with the conversion id returned when it was created:

```bash
curl -X PATCH "https://api.api2convert.com/v2/jobs/<job-id>/conversions/<conversion-id>" \
  -H "x-oc-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
        "quality": "ebook"
    }
}'
```

## Managing jobs

- `GET /v2/jobs` — list your jobs (paginated, 50 per page; filter with `?status=`).
- `DELETE /v2/jobs/{id}` — cancel/remove a job.

---

# Importing files

> Remote URLs, direct uploads, base64 and cloud inputs.
> Source: https://www.api2convert.com/documentation/guides/uploading-files

Inputs tell the API where to read your source files. Each entry in a job's `input[]` has a `type` and a `source`; some types add a few more fields. Below is a full example for every input type.

| type | Use when |
| --- | --- |
| `remote` | The file is reachable over HTTP(S). |
| `upload` | You hold the bytes and upload them directly. |
| `base64` | Small files inlined in the request. |
| `cloud` | Read from S3, Azure, Google Cloud or FTP. |
| `gdrive_picker` | A file chosen via the Google Drive picker. |
| `input_id` | Reuse an input from another job. |
| `output` | Chain a previous job's output as a new input. |

## Remote URL `remote`

Point the API at a publicly reachable URL:

```
"input": [{
  "type": "remote",
  "source": "https://example-files.online-convert.com/document/docx/example.docx"
}]
```

The optional `engine` field controls how the URL is fetched (e.g. capture a web page) — see [Download engines & website capture](https://www.api2convert.com/documentation/guides/input-engines). For password-protected sources, add `credentials`:

```
"input": [{
  "type": "remote",
  "source": "https://example-files.online-convert.com/archive/zip/example.zip",
  "credentials": { "decrypt_password": "hunter2" }
}]
```

## Direct upload `upload`

Uploading is three steps. First, create the job *without* starting it:

```bash
curl -X POST "https://api.api2convert.com/v2/jobs" \
  -H "x-oc-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "conversion": [
        {
            "category": "image",
            "target": "png"
        }
    ]
}'
```

The response includes a `server` assigned to the job. Upload your file there as multipart form-data (field name `file`), at the path `/upload-file/<job-id>`:

```bash
curl -F "file=@photo.jpg" \
  -H "x-oc-api-key: <your-api-key>" \
  -H "x-oc-upload-uuid: <a-unique-id>" \
  "<server>/upload-file/<job-id>"
```

Then start the job:

```bash
curl -X PATCH "https://api.api2convert.com/v2/jobs/<job-id>" \
  -H "x-oc-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "process": true
}'
```

> For large files, our [PHP SDK](https://www.api2convert.com/documentation/guides/sdks) handles chunked uploads for you.

## Base64 `base64`

Inline a small file directly in the request as a base64 string:

```
"input": [{
  "type": "base64",
  "source": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago...",
  "filename": "document.pdf"
}]
```

## Cloud storage `cloud`

Set `type: "cloud"` and put the provider name in `source`, then supply that provider's `parameters` and `credentials`.

### Amazon S3

```
"input": [{
  "type": "cloud",
  "source": "amazons3",
  "parameters": { "bucket": "my-bucket", "file": "in/photo.jpg" },
  "credentials": { "accesskeyid": "AKIA...", "secretaccesskey": "..." }
}]
```

### Azure Blob Storage

```
"input": [{
  "type": "cloud",
  "source": "azure",
  "parameters": { "container": "my-container", "file": "in/photo.jpg" },
  "credentials": { "accountname": "myaccount", "accountkey": "..." }
}]
```

### Google Cloud Storage

```
"input": [{
  "type": "cloud",
  "source": "googlecloud",
  "parameters": { "projectid": "my-project", "bucket": "my-bucket", "file": "in/photo.jpg" },
  "credentials": { "keyfile": "<service-account-JSON>" }
}]
```

### FTP

```
"input": [{
  "type": "cloud",
  "source": "ftp",
  "parameters": { "host": "ftp.example.com", "file": "/in/photo.jpg" },
  "credentials": { "username": "user", "password": "..." }
}]
```

## Google Drive `gdrive_picker`

For files chosen with the Google Drive picker, use the Drive file id as `source` and pass an OAuth access token in `credentials`:

```
"input": [{
  "type": "gdrive_picker",
  "source": "1AbCdEfGhIjKlMnOpQrStUvWxYz",
  "filename": "report.pdf",
  "credentials": { "token": "<google-oauth-access-token>" }
}]
```

## Reuse another job's input `input_id`

Reference an input you already created on another job by its id — no need to re-upload or re-download:

```
"input": [{
  "type": "input_id",
  "source": "<input-id-from-another-job>"
}]
```

## Chain a previous output `output`

Feed the output of a finished job straight into a new one — useful for multi-step pipelines (e.g. convert, then compress):

```
"input": [{
  "type": "output",
  "source": "<output-id-from-another-job>"
}]
```

---

# Download engines

> Control how a remote URL is fetched: file, video, website, screenshot, zip.
> Source: https://www.api2convert.com/documentation/guides/input-engines

When an input is fetched from a URL (`type: "remote"`), the `engine` field controls *how* it's retrieved. This is how you download a plain file, grab an embedded video, or capture a web page as an image, PDF or HTML. Below is a full example for every engine.

| engine | What it does |
| --- | --- |
| `auto` | Default. Picks the best way to fetch the resource. |
| `file` | Download the resource as a plain file. |
| `video` | Extract an embedded video from a web page. |
| `website` | Fetch the full HTML page with its embedded resources. |
| `screenshot` | Render the page and capture a screenshot (→ image). |
| `screenshot_pdf` | Render the page and capture it as a PDF. |
| `zip` | Treat the resource as an archive to download. |

## auto (default)

If you omit `engine` (or set it to `auto`), the API picks the best method for the URL — a plain file download for a direct file, page rendering for a web page, and so on:

```
"input": [{
  "type": "remote",
  "source": "https://example-files.online-convert.com/raster%20image/jpg/example.jpg",
  "engine": "auto"
}]
```

## file

Force the URL to be downloaded as a plain file, without any page rendering or media extraction:

```
"input": [{
  "type": "remote",
  "source": "https://example-files.online-convert.com/document/pdf/example.pdf",
  "engine": "file"
}]
```

## video

Download a video that is embedded in a web page, then convert it (e.g. to MP4):

```json
{
  "input": [{
    "type": "remote",
    "source": "https://www.online-convert.com/",
    "engine": "video"
  }],
  "conversion": [{ "category": "video", "target": "mp4" }],
  "process": true
}
```

## website

Fetch the full HTML page (with its embedded resources) — convert it to `html`, or onward to a document format:

```json
{
  "input": [{
    "type": "remote",
    "source": "https://www.online-convert.com/",
    "engine": "website"
  }],
  "conversion": [{ "category": "document", "target": "html" }],
  "process": true
}
```

## screenshot

Render the page in a browser and capture a screenshot, then convert it to an image format (png, jpg, …):

```json
{
  "input": [{
    "type": "remote",
    "source": "https://www.online-convert.com/",
    "engine": "screenshot",
    "options": { "screen_width": 1280, "screen_height": 1024, "device_scale_factor": 1 }
  }],
  "conversion": [{ "category": "image", "target": "png" }],
  "process": true
}
```

### Screenshot options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `screen_width` | integer | 1440 | Viewport width in pixels. |
| `screen_height` | integer | 3851 | Viewport height in pixels. |
| `device_scale_factor` | float | 1 | Pixel density — e.g. `2` doubles the captured resolution. |

## screenshot_pdf

Render the page and capture it as a PDF instead of an image:

```json
{
  "input": [{
    "type": "remote",
    "source": "https://www.online-convert.com/",
    "engine": "screenshot_pdf"
  }],
  "conversion": [{ "category": "document", "target": "pdf" }],
  "process": true
}
```

## zip

Treat the downloaded resource as a ZIP archive — useful when a URL serves an archive you want to unpack or convert its contents:

```
"input": [{
  "type": "remote",
  "source": "https://example-files.online-convert.com/archive/zip/example.zip",
  "engine": "zip"
}]
```

---

# Convert files

> Convert between 500+ formats; discover per-format options.
> Source: https://www.api2convert.com/documentation/guides/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.

```json
{
  "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](https://www.api2convert.com/documentation/formats).

## 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.

```bash
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:

```bash
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](https://www.api2convert.com/documentation/formats), where you can pick a source and target and see every supported option with its allowed values.

> Once you have a set of options you reuse often, save them as a **Preset** and reference it by id instead of repeating the full options block on every job. See [Presets](https://www.api2convert.com/documentation/guides/presets).

## 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.

```json
{
  "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:

```bash
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"
        }
    ]
}'
```

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`:

```json
{
  "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:

| Option | Applies to | Purpose |
| --- | --- | --- |
| width / height | image, video | Resize the output to fixed pixel dimensions. |
| quality | image, document | Trade file size against fidelity. |
| strip_metadata | operation (compress) | Remove embedded metadata from the result. |
| split | document (pdf) | Split the document into separate page outputs. |

Always confirm the exact option names and accepted values for your specific source/target pair via `GET /v2/conversions` or the [Formats Explorer](https://www.api2convert.com/documentation/formats) — passing an unsupported option will be rejected.

---

# PDF operations

> PDF/A, booklets, rotate, split, protect, page layout and OCR.
> Source: https://www.api2convert.com/documentation/guides/pdf-operations

Beyond plain format conversion, the API offers a set of PDF-specific operations: rotating pages, splitting, controlling page layout, encryption, PDF/A compliance, booklet imposition, and OCR for searchable PDFs. Most of these run through the `document` category with the target `pdf`; a few are dedicated operations. All examples authenticate with the `x-oc-api-key` header.

## Merge multiple files into one PDF

Add two or more inputs to a single job with the target `pdf` and they are combined into one document, in the order the inputs are added. This works across PDFs, images (JPG, PNG) and office documents (DOCX, XLSX): each input is converted to PDF and then concatenated. There is no separate "merge" option — merging happens automatically whenever a job has more than one input and a single output target.

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

> The output order is the input order. To change the page order *after* the inputs are added, `PATCH` each input's `position` — see [Reorder inputs](https://www.api2convert.com/documentation/guides/job-lifecycle#reorder-inputs).

## Rotate pages

Rotate pages by passing a list of `{ "pages", "angle" }` entries. `pages` accepts ranges like `"1-3"`, single pages, or the keywords `first`/`last`/`even`/`odd`; `angle` is `90`, `180` or `270` degrees clockwise.

```json
{
  "conversion": [{
    "category": "document",
    "target": "pdf",
    "options": { "rotate": [{ "pages": "1-3", "angle": 90 }] }
  }],
  "input": [{ "type": "remote", "source": "https://example-files.online-convert.com/document/pdf/example.pdf" }]
}
```

## Split into one file per page

Set `one_file_per_page` to split a multi-page PDF so each page becomes its own output file.

```json
{
  "conversion": [{
    "category": "document",
    "target": "pdf",
    "options": { "one_file_per_page": true }
  }]
}
```

## Page layout

Control the output geometry with `page_size` (e.g. `a4`, `letter`), `orientation` (`portrait` or `landscape`), and per-side borders. Border values use the unit given in `border_unit`.

```json
{
  "conversion": [{
    "category": "document",
    "target": "pdf",
    "options": {
      "page_size": "a4",
      "orientation": "portrait",
      "border_top": 10,
      "border_bottom": 10,
      "border_left": 15,
      "border_right": 15,
      "border_unit": "mm"
    }
  }]
}
```

## Protect and encrypt

Encrypt the PDF and set permissions. `new_user_password` is required to open the file; `new_owner_password` guards permission changes; the `allow_*` flags restrict printing, copying, and modification.

```json
{
  "conversion": [{
    "category": "document",
    "target": "pdf",
    "options": {
      "new_user_password": "open-me",
      "new_owner_password": "owner",
      "allow_printing": false,
      "allow_copying": false,
      "allow_modification": false
    }
  }]
}
```

## PDF/A compliance

Use the `convert-pdfa` operation to convert to an archival PDF/A profile, and `validate-pdfa` to check an existing file for compliance without converting it. Pick the conformance level with `validation_profile`; `strict_mode` tightens conversion checks.

```json
{
  "conversion": [{
    "category": "operation",
    "target": "convert-pdfa",
    "options": { "validation_profile": "pdfa2b", "strict_mode": true }
  }]
}
```

```json
{
  "conversion": [{
    "category": "operation",
    "target": "validate-pdfa",
    "options": { "validation_profile": "pdfa2b" }
  }]
}
```

## Booklet

The `pdf-booklet` operation imposes pages for booklet printing. Configure the reading `direction`, the `paper_size`, how many `pages_per_sheet`, how blank pages are filled (`blank_page_fill`), and whether to add `crop_marks`.

```json
{
  "conversion": [{
    "category": "operation",
    "target": "pdf-booklet",
    "options": {
      "direction": "ltr",
      "paper_size": "a4",
      "pages_per_sheet": 2,
      "blank_page_fill": "last",
      "crop_marks": true
    }
  }]
}
```

## OCR and searchable PDFs

When converting a scanned document to PDF, enable `ocr` to produce a searchable text layer. Set the recognition `language` (ISO 639-2, e.g. `eng`), and optionally `ocr_page_structure` and `ocr_filter` to tune layout detection. This is the public OCR option and is distinct from any internal AI OCR target.

```json
{
  "conversion": [{
    "category": "document",
    "target": "pdf",
    "options": {
      "ocr": true,
      "language": "eng"
    }
  }]
}
```

> Stamping a watermark onto pages is covered in [Add watermark](https://www.api2convert.com/documentation/guides/add-watermark). To see every supported target and its options, use the [format explorer](https://www.api2convert.com/documentation/formats).

## Live options

Pick a PDF target or operation to see its current option schema:

---

# Image operations

> Resize, crop and rotate images.
> Source: https://www.api2convert.com/documentation/guides/image-operations

This guide covers operations that **edit** an image without changing its purpose: resizing, cropping, and rotating. Resizing is a dedicated operation, while cropping and rotating are options you set on a normal image conversion. To shrink file size see [Compress files](https://www.api2convert.com/documentation/guides/compress-files), and for generating preview-sized images see [Create thumbnails](https://www.api2convert.com/documentation/guides/create-thumbnails).

## Resize an image

The `resize-image` operation scales an image to new dimensions. Provide a `width` and/or `height` (in the unit set by `resize_by`, e.g. `px` or `perc`), and control how the source fits the target box with `resize_handling`. Optionally force an aspect ratio with `aspect_ratio` (e.g. `"16:9"`) or set the output format with `resize_target`.

| Option | Description |
| --- | --- |
| width | Target width (in the unit set by `resize_by`). |
| height | Target height (in the unit set by `resize_by`). |
| resize_by | Unit for width/height: `px`, `perc`, `inches`, `cm`, `mm`. |
| resize_handling | How the source fits the box: `stretch`, `keep_aspect_ratio_crop`, or `keep_aspect_ratio_fill_black` / `_white` / `_blurred` / `_transparent`. |
| aspect_ratio | Force an aspect ratio such as `"16:9"`; when set, `width`/`height` are ignored. |
| resize_target | Output image format: `jpg`, `png`, `webp`, `bmp`, `gif`, `tiff`, `ico`, `tga`. |
| dpi | Output resolution in dots per inch. |

Submit a job that resizes an image to 800×600 pixels:

```json
{
  "input": [
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
    }
  ],
  "conversion": [
    {
      "category": "operation",
      "target": "resize-image",
      "options": {
        "width": 800,
        "height": 600,
        "resize_by": "px",
        "resize_handling": "keep_aspect_ratio_crop"
      }
    }
  ]
}
```

```bash
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": "operation",
            "target": "resize-image",
            "options": {
                "width": 800,
                "height": 600,
                "resize_by": "px",
                "resize_handling": "keep_aspect_ratio_crop"
            }
        }
    ]
}'
```

## Crop an image

Cropping happens on a regular image conversion: target the output image format and set the four crop options together. All four are **required as a set** — the origin point (top-left corner) plus the size of the region to keep.

| Option | Description |
| --- | --- |
| crop_origin_x | X coordinate of the crop region's top-left corner, in pixels. |
| crop_origin_y | Y coordinate of the crop region's top-left corner, in pixels. |
| crop_width | Width of the region to keep, in pixels. |
| crop_height | Height of the region to keep, in pixels. |

Keep a 400×300 region starting 50 pixels in from the top-left of a JPG:

```json
{
  "conversion": [
    {
      "category": "image",
      "target": "jpg",
      "options": {
        "crop_origin_x": 50,
        "crop_origin_y": 50,
        "crop_width": 400,
        "crop_height": 300
      }
    }
  ]
}
```

> All four `crop_*` options must be supplied together. Providing only some of them is not a valid crop.

## Rotate an image

On an image conversion, the `rotate` option turns the image clockwise by the given number of degrees.

```json
{
  "conversion": [
    {
      "category": "image",
      "target": "jpg",
      "options": {
        "rotate": 90
      }
    }
  ]
}
```

## Live options

Pick an operation or image target to see its live options. Browse every target in the [format explorer](https://www.api2convert.com/documentation/formats).

---

# Video operations

> Cut, extract frames, slideshow, merge streams and edit video.
> Source: https://www.api2convert.com/documentation/guides/video-operations

Beyond converting between video containers, the API offers **operations** that edit and process video — trimming, extracting frames, building slideshows and muxing audio. Each runs as a job: set `category: "operation"` and the operation name as `target`. For the request envelope and how to add inputs, see [Quickstart](https://www.api2convert.com/documentation/guides/quickstart) and [Uploading files](https://www.api2convert.com/documentation/guides/uploading-files).

## Cut / trim a video

The `cut-video` operation extracts one or more segments from a video. Use `start_video`/`end_video` for a single range, `length` to set the duration, or `cut_points` together with `number_of_parts` to split into pieces.

```
"conversion": [{
  "category": "operation",
  "target": "cut-video",
  "options": {
    "start_video": "00:00:10.000",
    "end_video": "00:00:40.000"
  }
}]
```

Split into equal parts instead of trimming to a range:

```
"conversion": [{
  "category": "operation",
  "target": "cut-video",
  "options": { "number_of_parts": 3 }
}]
```

## Extract frames (video to image)

The `video-to-image` operation samples frames from a video and returns them as images. Control sampling rate with `images_per_time_unit` and `time_unit`, limit to a range with `start_video`/`end_video`, restrict to `keyframes_only`, and pick the image format with `target_format`.

```
"conversion": [{
  "category": "operation",
  "target": "video-to-image",
  "options": {
    "images_per_time_unit": 1,
    "time_unit": "second",
    "keyframes_only": false,
    "target_format": "jpg"
  }
}]
```

## Slideshow from images

The `slideshow` operation builds a single video from a set of image inputs. Choose the output container with `target_format`, the dimensions with `width`/`height`, the `framerate`, and add `transitions` between images.

```
"input": [
  { "type": "remote", "source": "https://example-files.online-convert.com/raster%20image/jpg/example.jpg" },
  { "type": "remote", "source": "https://example-files.online-convert.com/raster%20image/jpg/example_small.jpg" },
  { "type": "remote", "source": "https://example-files.online-convert.com/raster%20image/png/example.png" }
],
"conversion": [{
  "category": "operation",
  "target": "slideshow",
  "options": {
    "target_format": "mp4",
    "width": 1920,
    "height": 1080,
    "framerate": 30,
    "transitions": [{ "transition": "fade" }]
  }
}]
```

## Merge audio into video

The `merge-streams` operation muxes an audio track onto a video. Provide both a video and an audio input. Set the output container with `video_format`, keep or replace the original track with `keep_original_audio`, repeat a short track over a longer video with `loop_audio`, and join multiple audio inputs with `audio_concatenate` or smooth the join with `audio_fade`.

```
"input": [
  { "type": "remote", "source": "https://example-files.online-convert.com/video/mp4/example.mp4" },
  { "type": "remote", "source": "https://example-files.online-convert.com/audio/mp3/example.mp3" }
],
"conversion": [{
  "category": "operation",
  "target": "merge-streams",
  "options": {
    "video_format": "mp4",
    "keep_original_audio": false,
    "loop_audio": true
  }
}]
```

## Resize, rotate, flip and reframe while converting

You don't need an operation for basic transforms — when converting to a video target you can resize, rotate, flip and change the frame rate inline via the conversion `options`. Use `width` and `height` to scale, `rotate` to turn the picture, `mirror` (the flip tool — `horizontal` or `vertical`) to mirror it, and `framerate` to retime.

```
"conversion": [{
  "category": "video",
  "target": "mp4",
  "options": {
    "width": 1280,
    "height": 720,
    "rotate": 90,
    "mirror": "horizontal",
    "framerate": 24
  }
}]
```

> To extract an existing audio or video track without re-muxing, use the `extract-streams` operation. Browse every video target and its exact options in the [Formats Explorer](https://www.api2convert.com/documentation/formats).

## Live options

Pick an operation or video target to see its live options:

---

# Audio operations

> Adjust volume, normalize, trim and edit audio.
> Source: https://www.api2convert.com/documentation/guides/audio-operations

Beyond converting between audio formats, the API can edit and process audio in place: adjust loudness, trim a clip, change codec and quality, or merge several tracks into one. These capabilities are exposed either as dedicated operations (like `audio-volume`) or as options on a regular audio conversion. Browse every audio target in the [format explorer](https://www.api2convert.com/documentation/formats).

## Adjust and normalize volume

Use the `audio-volume` operation to apply a fixed gain or attenuation via the `volume` option, expressed as a relative decibel value such as `"+3dB"` or `"-6dB"`.

```json
{
  "input": [{ "type": "remote", "source": "https://example-files.online-convert.com/audio/mp3/example.mp3" }],
  "conversion": [{
    "category": "operation",
    "target": "audio-volume",
    "options": { "volume": "+3dB" }
  }]
}
```

To even out loudness instead of applying a fixed gain, enable EBU R128 normalization on an audio conversion with `normalize`, `normalize_type` and `normalize_target_level_ebu`.

```json
{
  "input": [{ "type": "remote", "source": "https://example-files.online-convert.com/audio/wav/example.wav" }],
  "conversion": [{
    "category": "audio",
    "target": "mp3",
    "options": {
      "normalize": true,
      "normalize_type": "ebu",
      "normalize_target_level_ebu": -23
    }
  }]
}
```

## Trim audio

Cut a clip to a time range by setting `start` and `end` on an audio conversion. Both use `HH:MM:SS` notation; the segment between them is kept.

```json
{
  "input": [{ "type": "remote", "source": "https://example-files.online-convert.com/audio/mp3/example.mp3" }],
  "conversion": [{
    "category": "audio",
    "target": "mp3",
    "options": {
      "start": "00:00:30",
      "end": "00:01:45"
    }
  }]
}
```

## Codec and quality while editing

When converting or editing audio you can control the output encoding with `audio_codec`, `audio_bitrate`, `channels` (`mono` or `stereo`) and the sample rate via `frequency`.

```json
{
  "input": [{ "type": "remote", "source": "https://example-files.online-convert.com/audio/wav/example.wav" }],
  "conversion": [{
    "category": "audio",
    "target": "aac",
    "options": {
      "audio_codec": "aac",
      "audio_bitrate": 192,
      "channels": "stereo",
      "frequency": 44100
    }
  }]
}
```

| Option | Purpose | Example |
| --- | --- | --- |
| `audio_codec` | Encoder used for the audio stream | `mp3`, `aac` |
| `audio_bitrate` | Target bitrate in kbps | `192` |
| `channels` | Channel layout | `mono`, `stereo` |
| `frequency` | Sample rate in Hz | `44100` |

## Submit a job

Send any of the bodies above to the job endpoint, authenticating with the lowercase `x-oc-api-key` header.

```bash
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/audio/wav/example.wav"
        }
    ],
    "conversion": [
        {
            "category": "audio",
            "target": "aac",
            "options": {
                "audio_codec": "aac",
                "audio_bitrate": 192,
                "channels": "stereo",
                "frequency": 44100
            }
        }
    ]
}'
```

## Merging audio tracks

To combine multiple audio files into a single track, use the merge-streams capability. See the [Video operations](https://www.api2convert.com/documentation/guides/video-operations#merge-audio-into-video) guide for the full request structure and supported combinations.

> Trim (`start`/`end`), normalization and codec options live on an audio *conversion* target (e.g. `"target": "mp3"`), while a simple gain change is the dedicated `audio-volume` *operation*. Pick whichever matches what you need to change.

## Live options

Pick an operation or audio target to see its live options:

---

# Create archives

> Create and extract password-protected archives.
> Source: https://www.api2convert.com/documentation/guides/create-archives

The archive capabilities let you bundle several inputs into a single compressed file, password-protect it, and unpack existing archives back into their original contents. Creating an archive is a normal conversion to an archive target; extracting one is an operation that returns a manifest of what is inside.

## Create an archive

Convert to an archive target to pack one or more inputs into a single file. Supported archive targets are 7Z, ZIP, GZ and BZ2. Add multiple objects to the `input` array and they are all packed into the same archive.

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

Submit the job with your API key:

```bash
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/document/pdf/example.pdf"
        },
        {
            "type": "remote",
            "source": "https://example-files.online-convert.com/raster%20image/png/example.png"
        }
    ],
    "conversion": [
        {
            "category": "archive",
            "target": "zip"
        }
    ]
}'
```

### Password-protect the archive

Pass `encrypt_password` in the conversion `options` to encrypt the output archive. Anyone opening it will need this password.

```json
{
  "conversion": [
    {
      "category": "archive",
      "target": "zip",
      "options": {
        "encrypt_password": "secret"
      }
    }
  ]
}
```

## Extract an archive

Use the `extract-archive` operation to unpack an existing archive. Enable the `summary` option to receive a JSON manifest describing the files contained in the archive.

```json
{
  "input": [
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/archive/zip/example.zip"
    }
  ],
  "conversion": [
    {
      "category": "operation",
      "target": "extract-archive",
      "options": {
        "summary": true
      }
    }
  ]
}
```

### Extract an encrypted archive

For password-protected archives, supply the password on the `input` object via `credentials.decrypt_password` so the archive can be opened before extraction.

```json
{
  "input": [
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/archive/zip/example.zip",
      "credentials": {
        "decrypt_password": "secret"
      }
    }
  ],
  "conversion": [
    {
      "category": "operation",
      "target": "extract-archive",
      "options": {
        "summary": true
      }
    }
  ]
}
```

> The `decrypt_password` belongs on the `input` (it unlocks the source), whereas `encrypt_password` belongs in the conversion `options` (it locks the new output). See the full list of archive targets in the [format explorer](https://www.api2convert.com/documentation/formats).

## Live options

Pick an archive target or the extract operation to see its live options:

---

# File analysis

> Read and edit metadata, and analyze image content.
> Source: https://www.api2convert.com/documentation/guides/file-analysis

The API can inspect and modify the data *about* a file in addition to converting it. Use the `metadata` category to read, write, or strip a file's metadata. Every request authenticates with the lowercase `x-oc-api-key` header.

## Read metadata

Convert into the `metadata` category with target `json` to receive the source file's metadata serialized as a JSON document. Nothing about the original file is changed — the output is a JSON file describing it.

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

```bash
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": "metadata",
            "target": "json"
        }
    ]
}'
```

## Edit metadata

To write metadata into the file, use category `metadata` with target `metadata` and provide the fields in the conversion's `metadata` field — a sibling of `options`, not inside it. The file is returned in its original format with the updated values applied.

```json
{
  "input": [
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
    }
  ],
  "conversion": [
    {
      "category": "metadata",
      "target": "metadata",
      "metadata": {
        "Copyright": "© 2026 Example"
      }
    }
  ]
}
```

## Remove metadata

To clear specific fields, set them to an empty string in the conversion's `metadata` — useful for stripping author, copyright, GPS or other embedded values before sharing a file.

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

> To strip *all* metadata (EXIF, GPS, …) from an image in one step, use the `compress` operation with `strip_metadata: true` — see [Compress files](https://www.api2convert.com/documentation/guides/compress-files).

## Analyze image content

Beyond reading the data *about* a file, the API can analyze what an image actually *depicts*. Convert with category `operation` and target `analyze-image` to receive a JSON report describing the image. Switch the analyses you need on or off with boolean options: `nsfw` flags Not-Safe-For-Work content, `age` estimates the age of any people depicted, and `prompt` adds a textual description of the image content. `nsfw` and `age` are enabled by default; `prompt` is off by default.

```json
{
  "input": [
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
    }
  ],
  "conversion": [
    {
      "category": "operation",
      "target": "analyze-image",
      "options": {
        "nsfw": true,
        "age": true,
        "prompt": true
      }
    }
  ]
}
```

For the full list of supported source formats see the [format explorer](https://www.api2convert.com/documentation/formats), and for how jobs, inputs, and results fit together review the [getting started](https://www.api2convert.com/documentation/guides/quickstart) guide.

## Live options

The options below are read live from the conversion engine — the metadata `json` (read) and `metadata` (edit/delete) targets, and the `analyze-image` operation:

---

# Extract assets

> Pull assets and media streams out of files.
> Source: https://www.api2convert.com/documentation/guides/extract-assets

Extract assets let you pull content *out* of a container file instead of converting it: embedded images and resources from documents, images from a PDF, or individual audio and video streams from a media container. Each capability is a dedicated target you call through the standard `conversion` array. Authenticate every request with the lowercase `x-oc-api-key` header.

## Extract embedded assets

The `extract-assets` target pulls embedded assets (such as images and other resources) out of a supported input file and returns them as separate outputs.

```json
{
  "input": [
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/document/docx/example.docx"
    }
  ],
  "conversion": [
    {
      "category": "operation",
      "target": "extract-assets"
    }
  ]
}
```

```bash
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/document/docx/example.docx"
        }
    ],
    "conversion": [
        {
            "category": "operation",
            "target": "extract-assets"
        }
    ]
}'
```

## Extract assets from a PDF

Use `extract-assets-from-pdf` to pull the images and assets embedded in a PDF. Set `allow_multiple_outputs` to `true` to receive one output file per extracted asset instead of a single bundled result.

```json
{
  "input": [
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/document/pdf/example.pdf"
    }
  ],
  "conversion": [
    {
      "category": "operation",
      "target": "extract-assets-from-pdf",
      "options": {
        "allow_multiple_outputs": true
      }
    }
  ]
}
```

> When `allow_multiple_outputs` is enabled, the completed job exposes several entries under `output` — one per extracted asset. Iterate over the array to download them all.

## Extract individual streams

The `extract-streams` target separates the individual audio and video streams contained in a media file. Provide the `stream` option to choose which stream to pull out of the container.

```json
{
  "input": [
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/video/mp4/example.mp4"
    }
  ],
  "conversion": [
    {
      "category": "operation",
      "target": "extract-streams",
      "options": {
        "stream": "audio"
      }
    }
  ]
}
```

> Stream indexes depend on the container. Inspect the file first to see which audio and video streams are available — see the [format explorer](https://www.api2convert.com/documentation/formats) and the [file analysis](https://www.api2convert.com/documentation/guides/file-analysis) guide.

## Live options

The options below are pulled live from the API for each extract target. Use them to refine the output.

---

# Compare files

> Diff two images, PDFs or videos.
> Source: https://www.api2convert.com/documentation/guides/compare-files

The compare operations diff two files of the same kind — a **reference** and a **candidate** — and produce a visual diff that highlights where they differ. Unlike most operations, these take **two inputs**: list the reference first, then the candidate.

## Two inputs

Provide both files in the `input` array. The first entry is treated as the reference, the second as the candidate. Both inputs can be remote URLs, uploads, or any other supported source type — see [Input sources](https://www.api2convert.com/documentation/guides/uploading-files).

## compare-image

Compares two images pixel-by-pixel using a configurable metric and renders a visual diff where the highlighted regions mark the differences. Tune the comparison with `method`, `threshold` and `diff_color`.

| Option | Values | Description |
| --- | --- | --- |
| method | `ae`, `mae`, `ncc`, `psnr`, `rmse`, `ssim` | The comparison metric: absolute error, mean absolute error, normalized cross-correlation, peak signal-to-noise ratio, root mean squared error, or structural similarity. |
| threshold | `0`–`100` | Sensitivity. Differences below this threshold are ignored; higher values tolerate more variation before a pixel is flagged. |
| diff_color | color name / hex | The color used to highlight the differing regions in the produced diff image. |

### Example: compare two remote images

```json
{
  "input": [
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/raster%20image/jpg/example_small.jpg"
    },
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
    }
  ],
  "conversion": [
    {
      "category": "operation",
      "target": "compare-image",
      "options": {
        "method": "ssim",
        "threshold": 5,
        "diff_color": "red"
      }
    }
  ]
}
```

```bash
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_small.jpg"
        },
        {
            "type": "remote",
            "source": "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
        }
    ],
    "conversion": [
        {
            "category": "operation",
            "target": "compare-image",
            "options": {
                "method": "ssim",
                "threshold": 5,
                "diff_color": "red"
            }
        }
    ]
}'
```

## compare-pdf

Diffs two PDF documents page by page and renders the differences visually, making it easy to spot content or layout changes between two revisions of a PDF.

```json
{
  "input": [
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/document/pdf/example.pdf"
    },
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/document/pdf/example.pdf"
    }
  ],
  "conversion": [
    {
      "category": "operation",
      "target": "compare-pdf",
      "options": {}
    }
  ]
}
```

## compare-video

Performs a frame-by-frame diff of two videos, highlighting the frames and regions where the candidate differs from the reference.

```json
{
  "input": [
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/video/mp4/example_small.mp4"
    },
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/video/mp4/example.mp4"
    }
  ],
  "conversion": [
    {
      "category": "operation",
      "target": "compare-video",
      "options": {}
    }
  ]
}
```

> Both inputs should be the same format and, ideally, the same dimensions (and for video, the same frame rate). Comparing mismatched files can produce a diff dominated by alignment differences rather than real content changes.

## Options reference

The live options below are pulled directly from the API. For the full list of supported source and target formats, see the [format explorer](https://www.api2convert.com/documentation/formats).

---

# Compress files

> Reduce file size by quality or target size.
> Source: https://www.api2convert.com/documentation/guides/compress-files

The `compress` operation reduces file size for images, PDFs, audio and video while keeping the original format. You control the trade-off between size and fidelity with a handful of options — pick a compression level, cap the output at a specific size, or strip metadata to shave off extra bytes.

## Basic request

Submit a compress job by sending the source file URL and a `conversion` entry with the `compress` target. The example below applies a high compression level.

```json
{
  "input": [
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
    }
  ],
  "conversion": [
    {
      "category": "operation",
      "target": "compress",
      "options": {
        "compression_level": "high"
      }
    }
  ]
}
```

```bash
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": "operation",
            "target": "compress",
            "options": {
                "compression_level": "high"
            }
        }
    ]
}'
```

## Options

| Option | Type | Description |
| --- | --- | --- |
| `compression_level` | string | Preset strength: `low`, `medium`, `high` or `best`. |
| `quality` | integer | Output quality from `0` (smallest) to `100` (best). Applies to lossy formats. |
| `compression_target` | string | Output format to compress into, when different from the source. |
| `file_size` | integer | Target maximum output size in KB. |
| `file_size_perc` | integer | Target output size as a percentage of the original file. |
| `strip_metadata` | boolean | Remove embedded metadata (EXIF, tags) to reduce size further. |

## Compress by quality

Set an explicit `quality` value to control how aggressively a lossy format such as JPG is re-encoded. Lower values mean smaller files and more visible artifacts.

```json
{
  "input": [
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/raster%20image/jpg/example.jpg"
    }
  ],
  "conversion": [
    {
      "category": "operation",
      "target": "compress",
      "options": {
        "quality": 70,
        "strip_metadata": true
      }
    }
  ]
}
```

## Target a file size

Use `file_size` to cap the output at a fixed number of kilobytes. This is handy when an upload or email attachment must stay under a known limit — for example, keeping a PDF under 2 MB.

```json
{
  "input": [
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/document/pdf/example.pdf"
    }
  ],
  "conversion": [
    {
      "category": "operation",
      "target": "compress",
      "options": {
        "file_size": 2048
      }
    }
  ]
}
```

> Use either `file_size` or `file_size_perc`, not both, in the same request. The engine compresses until the target is met or the lowest acceptable quality is reached, so very small targets may not be achievable for every input.

## Related guides

Compression keeps the source format. To change the format as well, see the format-specific guides and check which targets accept `compress` in the [formats explorer](https://www.api2convert.com/documentation/formats).

## Live options

---

# Add watermark

> Overlay a graphic on PDF pages, or an image/logo onto video.
> Source: https://www.api2convert.com/documentation/guides/add-watermark

api2convert can add a watermark to **PDF documents** and **videos**. To watermark a **PDF**, overlay an image or another PDF onto every page: provide **two** inputs — the base document first and the overlay (the watermark/stamp graphic) second — then enable either `stamp` or `watermark` on a `document` / `pdf` conversion and choose where the overlay is placed with `alignment`. To watermark a **video**, overlay an image (a logo or watermark) or another video with the `overlays` option — see *Watermark a video* at the end of this guide.

## How it works

The overlay is applied to *every* page of the base PDF. The order of inputs matters: the first input is the PDF to stamp, the second is the image (PNG, JPG) or PDF used as the overlay. Common overlay formats are PNG (for transparency), JPG, and single-page PDF.

> A transparent PNG overlay gives the cleanest result, since the surrounding area stays see-through regardless of `stamp` or `watermark` mode.

## Stamp vs. watermark

Both place the overlay on each page — the difference is opacity.

| Option | Effect | Typical use |
| --- | --- | --- |
| `stamp` | Opaque overlay drawn on top of the page content. | Logos, seals, "APPROVED" / "PAID" marks. |
| `watermark` | Semi-transparent overlay that lets the page show through. | "DRAFT" / "CONFIDENTIAL" background marks. |

Set exactly one of them to `true`.

## Alignment

Use `alignment` to position the overlay on the page.

| Value | Placement |
| --- | --- |
| `center` | Overlay centered on the page (default-style placement). |
| `top` | Overlay aligned to the top of the page. |
| `bottom` | Overlay aligned to the bottom of the page. |
| `stretch` | Overlay scaled to fill the whole page. |

## Full example

Two remote inputs — the document first, the overlay image second — producing a PDF with an opaque, centered stamp:

```json
{
  "input": [
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/document/pdf/example.pdf"
    },
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/raster%20image/png/example.png"
    }
  ],
  "conversion": [
    {
      "category": "document",
      "target": "pdf",
      "options": {
        "stamp": true,
        "alignment": "center"
      }
    }
  ]
}
```

To make the overlay a semi-transparent watermark instead, swap the options:

```json
{
  "options": {
    "watermark": true,
    "alignment": "stretch"
  }
}
```

Submit the job with your API key in the `x-oc-api-key` header:

```bash
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/document/pdf/example.pdf"
        },
        {
            "type": "remote",
            "source": "https://example-files.online-convert.com/raster%20image/png/example.png"
        }
    ],
    "conversion": [
        {
            "category": "document",
            "target": "pdf",
            "options": {
                "stamp": true,
                "alignment": "center"
            }
        }
    ]
}'
```

> For the exact options supported by the `pdf` target, see the [format explorer](https://www.api2convert.com/documentation/formats). For the end-to-end job lifecycle, see the [getting started guide](https://www.api2convert.com/documentation/guides/quickstart).

## Live options

Pick stamp or watermark to see its options (and a copyable request). Remember to add the overlay as the second input:

## Watermark a video

To watermark a video, add the `overlays` option to a video conversion (for example `mp4`). Each overlay draws an image — a logo or watermark — or another video on top of the output. Unlike the PDF watermark, a video overlay references its graphic by `input_id`, so it takes two requests: create the job with both files, read the overlay input's `id`, then add the conversion.

> Overlays work on every video target. Adding an overlay re-encodes the video, so it can't be combined with stream copy (`codec: "copy"`).

### Overlay options

| Option | Description |
| --- | --- |
| `input_id` | The `id` of the input to use as the overlay — an image or a video. Required. |
| `origin` | Corner the position is measured from: `top-left` (default), `top-right`, `bottom-left`, `bottom-right` or `center`. |
| `position_x` / `position_y` | Offset in pixels from the `origin`. |
| `width` / `height` | Scale the overlay to this size in pixels (optional). |
| `opacity` | Overlay opacity from `0` (invisible) to `1` (fully opaque), e.g. `"0.5"`. |

### Step 1 — create the job with both inputs

Add the base video first and the overlay image second. The response returns each input with an `id` — note the overlay's `id` for the next step.

```bash
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/video/mp4/example.mp4"
        },
        {
            "type": "remote",
            "source": "https://example-files.online-convert.com/raster%20image/png/example.png"
        }
    ]
}'
```

### Step 2 — add the conversion with the overlay

Reference the overlay input by its `id` and place it with `origin`, `position_x` / `position_y` and `opacity`:

```bash
curl -X POST "https://api.api2convert.com/v2/jobs/<job-id>/conversions" \
  -H "x-oc-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "mp4",
    "options": {
        "overlays": [
            {
                "input_id": "<overlay-input-id>",
                "origin": "bottom-right",
                "position_x": 20,
                "position_y": 20,
                "opacity": "0.5"
            }
        ]
    }
}'
```

> Pass multiple entries in `overlays` to stack several logos or watermarks. For the exact, current options see the [format explorer](https://www.api2convert.com/documentation/formats).

---

# Capture website

> Turn a URL into an image, PDF or HTML.
> Source: https://www.api2convert.com/documentation/guides/capture-website

Instead of uploading a file, you can point the API at a web page and have it rendered for you. By choosing a remote `input` with a capture `engine`, a single job can turn any URL into a screenshot image, a PDF, or a self-contained HTML snapshot. This guide shows the three engines with complete, copy-pasteable job bodies.

## How it works

The capture happens on the input side: you set `type` to `remote`, point `source` at the page URL, and pick an `engine`. The `conversion` block then defines the output you want. Set `process` to `true` to run the job immediately.

> Authenticate every request with the lowercase `x-oc-api-key` header. The capture engines live alongside the other download engines — see the [Download engines](https://www.api2convert.com/documentation/guides/input-engines) guide for the full reference.

## Screenshot to image

The `screenshot` engine renders the page in a headless browser and captures it as a raster image. Pair it with an image conversion such as `image/png` or `image/jpg`.

```json
{
  "input": [
    {
      "type": "remote",
      "source": "https://www.online-convert.com",
      "engine": "screenshot",
      "options": {
        "screen_width": 1280,
        "screen_height": 1024,
        "device_scale_factor": 1
      }
    }
  ],
  "conversion": [
    { "category": "image", "target": "png" }
  ],
  "process": true
}
```

```bash
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://www.online-convert.com",
            "engine": "screenshot",
            "options": {
                "screen_width": 1280,
                "screen_height": 1024,
                "device_scale_factor": 1
            }
        }
    ],
    "conversion": [
        {
            "category": "image",
            "target": "png"
        }
    ],
    "process": true
}'
```

### Screenshot options

These options control the virtual viewport used to render the page. They apply to both the `screenshot` and `screenshot_pdf` engines.

| Option | Description | Default |
| --- | --- | --- |
| `screen_width` | Viewport width in pixels. | 1440 |
| `screen_height` | Viewport height in pixels. | 3851 |
| `device_scale_factor` | Pixel density multiplier; raise it for sharper, higher-resolution captures. | 1 |

## Screenshot to PDF

The `screenshot_pdf` engine renders the page and writes it straight to a PDF document. The same screenshot options apply.

```json
{
  "input": [
    {
      "type": "remote",
      "source": "https://www.online-convert.com",
      "engine": "screenshot_pdf",
      "options": {
        "screen_width": 1280,
        "screen_height": 1024,
        "device_scale_factor": 1
      }
    }
  ],
  "conversion": [
    { "category": "document", "target": "pdf" }
  ],
  "process": true
}
```

## Full page to HTML

The `website` engine downloads the page and its assets and produces a self-contained HTML snapshot. Use a `document/html` conversion for the output.

```json
{
  "input": [
    {
      "type": "remote",
      "source": "https://www.online-convert.com",
      "engine": "website"
    }
  ],
  "conversion": [
    { "category": "document", "target": "html" }
  ],
  "process": true
}
```

> Need a different output format? Browse the [format explorer](https://www.api2convert.com/documentation/formats) to see every target and its options.

---

# Create thumbnails

> Generate thumbnails from images, PDFs and video.
> Source: https://www.api2convert.com/documentation/guides/create-thumbnails

The `thumbnail` operation generates a small preview image from an existing image, PDF, or video. It is ideal for building galleries, file previews, or page-by-page document overviews without downloading the full source file.

## How it works

Call the operation under the `conversion` array with `"category": "operation"` and `"target": "thumbnail"`. Point `input` at your source file and tune the output with the options below.

## Options

| Option | Description |
| --- | --- |
| `thumbnail_target` | Output image format: `png` or `jpg`. |
| `width` | Target width of the thumbnail in pixels. |
| `height` | Target height of the thumbnail in pixels. |
| `dpi` | Render resolution (dots per inch) used when rasterizing PDF pages. |
| `pages` | Which source pages to render, e.g. `"first"` or a range list like `"1-3,5"` (applies to PDF and multi-page input). |
| `allow_multiple_outputs` | When several pages are requested, set to `true` to receive one thumbnail file per page instead of a single combined output. |

## Example: PDF to first-page PNG thumbnail

This job renders the first page of a PDF as a 300 px-wide PNG thumbnail.

```json
{
  "input": [
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/document/pdf/example.pdf"
    }
  ],
  "conversion": [
    {
      "category": "operation",
      "target": "thumbnail",
      "options": {
        "thumbnail_target": "png",
        "width": 300,
        "pages": "first",
        "dpi": 150
      }
    }
  ]
}
```

Submit the job with your API key in the lowercase `x-oc-api-key` header:

```bash
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/document/pdf/example.pdf"
        }
    ],
    "conversion": [
        {
            "category": "operation",
            "target": "thumbnail",
            "options": {
                "thumbnail_target": "png",
                "width": 300,
                "pages": "first",
                "dpi": 150
            }
        }
    ]
}'
```

## Multiple page thumbnails

To produce a separate thumbnail for each of several pages, request a page range and enable `allow_multiple_outputs`.

```json
{
  "conversion": [
    {
      "category": "operation",
      "target": "thumbnail",
      "options": {
        "thumbnail_target": "jpg",
        "width": 200,
        "height": 280,
        "pages": "1-3,5",
        "allow_multiple_outputs": true
      }
    }
  ]
}
```

> The same operation works for video input, producing a single preview frame. For full document or image format conversions instead of previews, see the [format explorer](https://www.api2convert.com/documentation/formats).

## Live options

---

# Create hashes

> Generate MD5, SHA and other digests.
> Source: https://www.api2convert.com/documentation/guides/create-hashes

The API can generate a cryptographic digest (checksum) of any file by converting it to a `hash` target. This is useful for verifying file integrity, deduplication, and fingerprinting. Each algorithm is exposed as its own target under the `hash` category.

## How it works

Submit a job whose conversion targets the `hash` category with the algorithm you want as the `target`. The API reads your input file, computes the digest, and returns it as the result.

## Example: hash a remote file with SHA256

Point the API at a publicly reachable file and request the `sha256` target.

```json
{
  "input": [
    {
      "type": "remote",
      "source": "https://example-files.online-convert.com/archive/zip/example.zip"
    }
  ],
  "conversion": [
    {
      "category": "hash",
      "target": "sha256"
    }
  ]
}
```

Create the job by POSTing the payload (authenticate with the lowercase `x-oc-api-key` header):

```bash
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/archive/zip/example.zip"
        }
    ],
    "conversion": [
        {
            "category": "hash",
            "target": "sha256"
        }
    ]
}'
```

## Common algorithms

The most frequently used hash targets are **MD5**, **SHA1**, **SHA256**, **SHA384** and **SHA512**. Also available are **CRC32**, **ADLER32**, **RIPEMD160**, **WHIRLPOOL** and **BLOWFISH**. To switch algorithm, just change the `target` value:

```json
{
  "conversion": [
    {
      "category": "hash",
      "target": "md5"
    }
  ]
}
```

| Target | Algorithm | Typical use |
| --- | --- | --- |
| `md5` | MD5 | Fast (legacy/insecure) checksums, deduplication |
| `sha1` | SHA1 | Legacy integrity checks |
| `sha256` | SHA256 | General-purpose integrity and fingerprinting |
| `sha512` | SHA512 | Longer digest for stronger collision resistance |
| `crc32` | CRC32 | Quick error-detection checksums |

This is only a selection. Browse the [Formats Explorer](https://www.api2convert.com/documentation/formats) for the complete list of supported hash targets.

> Hashing is a one-way operation: a digest fingerprints a file for integrity checks and comparison, but the original file cannot be reconstructed from the hash. Use it to verify or identify content, not to encrypt or store recoverable data.

## Live options

Pick a hash algorithm to see its live options (including `hmac` for keyed hashing) and a copyable request:

---

# Output & cloud storage

> Download URLs and S3/GCS/Azure/FTP/Drive/YouTube export.
> Source: https://www.api2convert.com/documentation/guides/output-storage

By default, converted files are made available as download URLs. You can also push outputs straight to your own cloud storage.

## Download URLs

When a job completes, each entry in `output[]` has a `uri`, a `name`, a `size` and a `content_type`. Download URLs are valid for **24 hours**.

```
"output": [{ "uri": "https://.../result.pdf", "name": "result.pdf", "content_type": "application/pdf" }]
```

## Cloud export targets

Attach an `output_target` to a conversion to deliver results elsewhere. Supported providers:

| type | Destination |
| --- | --- |
| `amazons3` | Amazon S3 |
| `googlecloud` | Google Cloud Storage |
| `azure` | Azure Blob Storage |
| `ftp` | FTP server |
| `gdrive` | Google Drive |
| `youtube` | YouTube (video upload) |

## Example: export to S3

```
"conversion": [{
  "category": "image",
  "target": "png",
  "output_target": [{
    "type": "amazons3",
    "parameters": { "bucket": "my-bucket", "file": "out/result.png" },
    "credentials": { "...": "provider credentials" }
  }]
}]
```

Treat storage credentials as secrets. Required

parameters

differ per provider (e.g. S3 needs

bucket

+

file

, Azure needs a container + file).

## Build an output target

Pick a destination to see its `parameters` and `credentials`, with a copy-pasteable request preview. Required fields are pre-filled with example values — replace the credentials with your own.

---

# Webhooks & callbacks

> Get notified when a job finishes.
> Source: https://www.api2convert.com/documentation/guides/webhooks

Rather than polling a job's status, register a **webhook** and the API calls you back when the job changes. A webhook is just a `callback` URL you set when creating the job — api2convert sends an HTTP `POST` to it.

## Register a webhook

Set a publicly reachable `callback` URL on the job. Delivery is an outbound `POST` from our servers, so the URL must be reachable from the public internet:

```bash
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/document/docx/example.docx"
        }
    ],
    "conversion": [
        {
            "category": "document",
            "target": "pdf"
        }
    ],
    "process": true,
    "callback": "https://your-app.example.com/api2convert/webhook"
}'
```

## When it fires

- By default, the webhook fires once, when the job reaches a **final** status — `completed` or `failed`.
- Set `notify_status: true` on the job to be called on **every** status change instead.

## Payload

The request is an HTTP `POST` with `Content-Type: application/json`. The body is the **full job document** — the same JSON returned by `GET /v2/jobs/{id}`, including `status`, `output[]` (with the download URLs) and any `errors`/`warnings`. A brand-specific `User-Agent` is sent (e.g. `API2Convert API v2 Client (https://api.api2convert.com)`). The payload is **not** signed — there is no HMAC or `Authorization` header.

## Delivery, timeouts & retries

- Your endpoint has **3 seconds** to respond on the first attempt (**10 seconds** on retries).
- Acknowledge with any `2xx`. A `4xx` is treated as a permanent rejection and is **not retried**; a `5xx` or a timeout is **retried up to 10 times** (re-queued in the background).
- If a callback host fails repeatedly (~25 failures), it is briefly skipped (~30 seconds) to protect the delivery queue.

## Handling webhooks

- Respond quickly — within the timeout — with a `2xx`, then do any heavy work asynchronously.
- Make your handler idempotent, keyed on the job `id`: retries (and `notify_status`) can deliver the same job more than once.
- Read the download URLs from `output[]` promptly — they are valid for 24 hours.

Webhooks are

not cryptographically signed

, and the sender does

not verify your endpoint's TLS certificate

. Treat the callback URL as a secret and don't trust the payload blindly — confirm the referenced job is yours by re-fetching it with your API key (

GET /v2/jobs/{id}

) before acting on it.

---

# Errors & warnings

> Status codes, error and warning payloads.
> Source: https://www.api2convert.com/documentation/guides/errors-and-warnings

The API uses standard HTTP status codes, returns a JSON error body on failures, and surfaces per-item problems inside the job as `errors` and `warnings`.

## HTTP status codes

| Code | Meaning |
| --- | --- |
| 200 | OK — successful GET/PATCH. |
| 201 | Created — successful POST. |
| 204 | No content — successful DELETE, or empty list. |
| 400 | Bad request — invalid JSON, missing field, or a target your key may not use. |
| 401 | Unauthorized — missing or invalid API key/token. |
| 402 | Payment required — contract limit/quota exceeded. |
| 404 | Not found — unknown job/conversion/input/output id. |
| 409 | Conflict — invalid status transition (e.g. modifying a running job). |
| 429 | Too many requests — concurrent-conversion limit reached. |
| 500 | Server error. |

A `500` is usually transient. If you see repeated `500`s or timeouts across requests, check the [service status page](https://www.api2convert.com/documentation/guides/service-status) for a known platform incident before retrying — and back off exponentially.

## Error body

```json
{ "code": 400, "message": "Invalid input" }
```

## Job-level errors & warnings

Even a successful request can produce per-input or per-conversion problems. These appear in the job's `errors` and `warnings` arrays:

```
"errors": [{
  "source": "input",
  "id_source": "<input-id>",
  "code": 404,
  "message": "The file could not be downloaded"
}]
```

Use the `fail_on_input_error` and `fail_on_conversion_error` job flags to decide whether such problems fail the whole job or are reported as warnings while the rest proceeds.

## Error & warning codes

Codes the API can place in a job's `errors` and `warnings` arrays (the `code` field of each `UserError`/`UserWarning`).

### Download & remote-input errors

| Code | Message | Notes |
| --- | --- | --- |
| `1` | The file could not be downloaded. We are unable to resolve the host address or the host is unreachable. |  |
| `2` | The job can not be modified. | Only jobs with status incomplete or ready can be modified. |
| `5` | Empty or invalid file received. | The remote or locally uploaded file was empty or corrupted. Please try again. |
| `10` | We are not authorized to download Youtube videos. |  |
| `11` | We are not authorized to download metadata from the provided URL. |  |
| `12` | We are not authorized to download embedded contents from the provided URL. |  |
| `13` | The file specified was not found. | Specific for cloud services. |
| `14` | The specified bucket does not exist. |  |
| `15` | The server where we wanted to download the file is currently not available. | Specific for Amazon S3. |
| `16` | We cannot download the file, are you sure the specified region is the one of your bucket? | Specific for Amazon S3. |
| `17` | File not found, reasons for this error could be: bucket has incorrect permissions, you sent invalid credentials, or the file is really not there. | Specific for Amazon S3. |
| `18` | The token is invalid or has expired. | Specific for Amazon S3. |
| `19` | We could not connect to google cloud, are you sure that all credentials are correct? | Specific for Google Cloud. |
| `20` | We could not connect to azure, are you sure that all credentials are correct? | Specific for Azure. |
| `21` | The specified file was not found. | Specific for Azure. |
| `22` | There was an error that we could not recover, if this problem persists please contact support. | Specific for Azure. |
| `23` | The specified container does not exist. | Specific for Azure. |
| `24` | Azure could not authenticate the request, make sure that your accountkey credential is valid. | Specific for Azure. |
| `25` | Could not connect to FTP server, are you sure all connection parameters and credentials are correct? | Specific for remote FTP download. |
| `26` | There was an error that we could not recover, if this problem persists please contact support. | Specific for remote FTP download. |
| `27` | Could not login to the FTP server with the given credentials, are the credentials correct? | Specific for remote FTP download. |
| `28` | The FTP host cannot be resolved, are you sure it is correct? | Specific for remote FTP download. |
| `29` | The file specified was not found in the FTP server. | Specific for remote FTP download. |
| `33` | The file cannot be downloaded. Unknown input_id or missed credentials. |  |
| `34` | The total inputs file size for a conversion has been exceeded and your file discarded. | If you need more power, please upgrade your contract. |
| `35` | We could not connect to youtube, are you sure that all credentials are correct? |  |
| `39` | The AWS Access Key Id you provided does not exist. |  |
| `40` | The request signature we calculated does not match the signature you provided. Check your key and signing method. |  |
| `401` | The file could not be downloaded by our servers, because a password has been requested to access the data. |  |
| `402` | The file could not be downloaded by our servers, because a payment was required. |  |
| `403` | The file could not be downloaded by our servers, because a password has been requested to access the data. |  |
| `404` | The file could not be downloaded by our servers. Please verify the link you have provided. |  |
| `408` | The file could not be downloaded by our servers, because the remote server timed out. |  |
| `410` | The file could not be downloaded by our servers, because the link you have provided does not exists anymore. |  |
| `413` | The file could not be downloaded by our servers, because the file size too big. |  |
| `414` | The file could not be downloaded by our servers, because the URI you have provided it is too long. |  |
| `429` | The file could not be downloaded by our servers, because the remote server is too busy. Try again later. |  |
| `451` | The file could not be downloaded by our servers, because the remote resource it is unavailable for legal reasons. |  |
| `500` | The server where we wanted to download the file is currently not available. |  |
| `503` | The file could not be downloaded. We are unable to resolve the host address or the host is unreachable. |  |
| `504` | The file could not be downloaded by our servers, because the remote server timed out. |  |
| `509` | The file could not be downloaded by our servers, because the remote server reached its bandwidth limit. Try again later. |  |
| `511` | The file could not be downloaded by our servers, because a network authentication is required to reach the requested resource. |  |

### Cloud upload errors

| Code | Message | Notes |
| --- | --- | --- |
| `19` | We cannot upload the file, are you sure the specified region is the one of your bucket? | Specific for Amazon S3. |
| `20` | The server where we wanted to upload the file is currently not available. | Specific for Amazon S3. |
| `21` | A file with this name already exists in the cloud storage. |  |
| `22` | Problem uploading file to cloud storage, if this problem persists, please contact support. |  |
| `23` | We could not connect to azure, are you sure that all credentials are correct? | Specific for Azure. |
| `24` | Problem uploading file to cloud storage, if this problem persists, please contact support. | Specific for Azure. |
| `25` | There was an error that we could not recover, if this problem persists please contact support. | Specific for Azure. |
| `26` | Azure could not authenticate the request, make sure that your accountkey credential is valid. | Specific for Azure. |
| `27` | The specified container does not exist. | Specific for Azure. |
| `28` | Please, make sure that all the parameters required for this operation are correct, check the api documentation. | The JSON you sent to us is wrong or is missing important data. |
| `29` | Could not connect to FTP server, are you sure all connection parameters and credentials are correct? | Specific for remote FTP upload. |
| `30` | There was an error that we could not recover, if this problem persists please contact support. | Specific for remote FTP upload. |
| `31` | Could not login to the FTP server with the given credentials, are the credentials correct? | Specific for remote FTP upload. |
| `32` | The FTP host cannot be resolved, are you sure it is correct? | Specific for remote FTP upload. |
| `34` | The total inputs file size for a conversion has been exceeded and your file discarded. | You cannot convert the file because it is too big. You need to upgrade your contract. |
| `35` | We could not connect to youtube, are you sure that all credentials are correct? | Specific for YoutTube upload. |
| `36` | Problem uploading file to gdrive, if this problem persists, please contact support. | Specific for Google Drive upload. |
| `37` | Permission denied while trying to write file to FTP server. | Specific for remote FTP upload. |
| `38` | Problem uploading file to cloud storage, if this problem persists, please contact support. |  |
| `39` | The AWS Access Key Id you provided does not exist. |  |
| `40` | The request signature we calculated does not match the signature you provided. Check your key and signing method. |  |
| `41` | The specified bucket does not exist. |  |

### Local upload errors

| Code | Message | Notes |
| --- | --- | --- |
| `2` | The job can not be modified. | The job status does not allow any new input. |
| `3` | You reached maximum allowed file size in upload. | You cannot convert the file because it is too big. You need to upgrade your contract. |
| `4` | The job input limit has been reached. | The job cannot accept more inputs for your kind of contract. |
| `5` | Empty or invalid file received. |  |
| `6` | Problem uploading file. |  |
| `7` | Job not found. |  |
| `8` | Problem uploading file: Unsupported Content-Range header | You are not using the correct header for chunk upload. |
| `34` | The total inputs file size for a conversion has been exceeded and your file discarded. | You cannot convert the file because it is too big. You need to upgrade your contract. |
| `39` | The total number of inputs set for a conversion has been exceeded and your file discarded. | The job cannot accept more inputs for your kind of contract. |
| `426` | HTTP is not supported. Please switch to HTTPS instead. |  |

### Proxy errors

| Code | Message | Notes |
| --- | --- | --- |
| `1` | The file could not be downloaded. We are unable to resolve the host address or the host is unreachable. |  |
| `50` | The file could not be downloaded by our servers. You do not have permissions to convert files of this size. Please upgrade your account. |  |
| `51` | The file could not be downloaded by our servers, because the host answered: Daily Limit for Unauthenticated Use Exceeded. |  |
| `52` | The file could not be downloaded by our servers, because the host answered: The download quota for this file has been exceeded. |  |

### Conversion errors

| Code | Message | Notes |
| --- | --- | --- |
| `6000` | There has been an error converting your file. | Default conversion error code. We are not able to tell more. Please send us a ticket request. |
| `6001` | Your file is DRM protected and we therefore are not allowed to convert it. |  |
| `6002` | The file is password protected. Please, provide the password. |  |
| `6003` | The file can not be converted because the bitrate is set too low. Please set a higher bitrate or, in case you are converting a video, reduce the frame rate or decrease width and height of the video. |  |
| `6004` | Unfortunately we can not convert your file yet from your source file format to this target file format. | If you feel that this format should be added, please let us know! |
| `6005` | Your file is missing important meta data and we therefore can not convert it. | E.g. the moov atom is missing. |
| `6006` | The files inside an archive must be of the same type | E.g. you sent a ZIP with both JPGs and PNGs inside. |
| `6007` | To crop an image you have to specify a value for ALL of the followings: crop_origin_x, crop_origin_y, crop_width, crop_height |  |
| `6008` | To specify a custom page size, ALL of the following parameters must have a valid value: custom_page_size_width, custom_page_size_height, custom_page_size_unit |  |
| `6009` | Out of range pages for the requested conversion. Please, check that the passed page numbers in the parameters are within the document limits. |  |
| `6010` | Not enough data to start the conversion. Please, check all the parameters. |  |
| `6011` | We are not able to use the provided password to decrypt the file. |  |
| `6012` | There was a temporary error with your conversion. Please try again later. | We had a problem on our side. Normally it is auto fixed in a few seconds. |
| `6013` | To crop a video you have to specify a value for ALL of the followings: crop_origin_x, crop_origin_y, crop_width, crop_height |  |
| `6014` | None of the conversions finished successfully. |  |
| `6015` | The job input limit has been reached. |  |
| `6016` | Too few files to execute the requested conversion. |  |
| `6017` | Too many files to execute the requested conversion. |  |
| `6018` | The file seems to be broken and we are unable to fix it. |  |
| `6019` | Your file uses an unsupported encryption format. |  |
| `6020` | Your conversion took too long and was canceled. |  |
| `6021` | Width or Height exceed the limit for icons. Please make sure the largest side is set to max 256px. |  |
| `6022` | There has been an error converting your file. |  |
| `6023` | The job has an input file which is too old. |  |
| `6024` | We could not compress this file any further |  |
| `6025` | Unfortunately, during conversion we detected an issue. Probably you set wrong values for bitrate, width or height. Try changing values or select a different codec if available. |  |
| `6026` | Width or Height exceed the limit for AI upscaling. Please make sure the largest side is set to max 2000px. |  |
| `6027` | Unsupported input file format for the requested conversion. |  |
| `6028` | Unsupported output file format for the requested conversion. |  |
| `6029` | The input file is not a valid PDF |  |
| `6030` | All slides in the presentation are marked as hidden. |  |
| `6031` | The input file cannot be converted to the selected PDF/A standard. |  |
| `6032` | The input file cannot be converted to the selected PDF/A standard. Probably the original PDF contains errors that we cannot automatically fix. |  |
| `6033` | The input file cannot be converted to the selected PDF/A standard. |  |
| `6034` | Strict mode cannot be used via API. |  |
| `6035` | The input file cannot be converted to the selected PDF/A standard. |  |
| `6036` | We are not able to extract any embedded assets from the file. |  |
| `6037` | The values for width or height are too large. Please try again with smaller values. |  |
| `6038` | The resulting duration of the converted video is too long (>4 hrs). |  |
| `6039` | Please, retry the conversion without the OCR option. |  |
| `6040` | Some data is missing. |  |
| `6041` | Unknown audio channels layout. |  |
| `6042` | Input filter name is missed or unknown. |  |
| `6043` | Input id is missed or unknown. |  |
| `6044` | Volume value is missed. |  |
| `6045` | You cannot set an audio channels layout and filtering at the same time. Please, split it in two separate jobs. |  |
| `6046` | The input file is not compliant with the selected PDF/A validation profile. |  |
| `6047` | There has been an error validating your file. |  |
| `6048` | Please, retry the conversion without the OCR option. |  |
| `6049` | Please, retry the conversion with the OCR option. |  |
| `6051` | There has been an error converting your file. |  |
| `6052` | We could not extract any text from your file. |  |
| `6053` | We could not extract any audio from your file. |  |
| `6054` | AI upscale cannot be used to downscale an image. |  |
| `6056` | We are not able to extract any embedded assets from this file format yet. |  |
| `6057` | The input file cannot be converted to the selected PDF/A standard while in non strict mode. |  |
| `6058` | AI upscale percentage out of range. It should be between 101 and 400. |  |
| `6059` | Missing mandatory prompt. |  |
| `6060` | NSFW content detected. |  |
| `6061` | The images have different aspect ratio. |  |
| `6062` | We could not extract any text from your file. Have you specified the main language of your audio? |  |
| `6063` | Missing mandatory image file. |  |
| `6064` | There has been an error converting your file. |  |
| `6065` | There has been an internal error while converting your file. |  |
| `6066` | Unable to generate a thumbnail from the provided input file. |  |
| `6067` | We could not detect any faces in your file. |  |
| `6068` | Your file is missing important meta data and we therefore can not convert it. |  |
| `6069` | There has been an error converting your file. |  |
| `6070` | To make a slideshow at least one image file is needed. |  |
| `6071` | Fading value is missed. |  |
| `6072` | Insufficient audio inputs. Required audio inputs are missing. |  |
| `6073` | Input stream codec is not supported by the target container. Please, choose a specific one instead of "copy". |  |
| `6074` | To cut a video you need at least the cut_points OR the length options. |  |
| `6075` | To cut a video you need one of the options cut_points, length or number_of_parts ONLY. |  |
| `6076` | Invalid trimming times: The end time must be greater than the start time. Please ensure that the end time is set after the start time to define a valid trimming range. |  |
| `6077` | The specified trimming times exceed the video duration. |  |
| `6078` | Unable to determine the video duration. The input file may be corrupted or missing essential metadata. Please, retry without end_video and start_video trimming options. |  |
| `6079` | We could not extract any text from your file. If it contains scanned pages only, retry the conversion with the OCR option. If not, the file could be damaged. |  |
| `6080` | Metadata removal not supported for this file type. |  |
| `6081` | Cannot write metadata |  |
| `6082` | No metadata to edit received |  |
| `6083` | This operation needs exactly two input files |  |
| `6084` | This operation needs two documents with the same number of pages |  |
| `6085` | To merge videos we need video inputs or images or documents |  |
| `6086` | We cannot find the pixel data in your DICOM file |  |
| `6087` | The crop region is invalid. Please check that the crop values are positive and within the image bounds. |  |
| `6088` | Borders exceed page dimensions, no space left for content. |  |
| `6089` | Archive expands beyond allowed size limit. Reduce contents and retry. |  |
| `6090` | The input file contains too many text lines and cannot be converted. Please reduce the text content and try again. |  |
| `6091` | This file does not appear to be in its declared format. It looks like plain text that is too long to convert to an image. Please verify the file format or reduce its text content. |  |
| `6092` | We could not determine the number of pages of your PDF file. |  |
| `6093` | The requested output dimensions are too large to process. Please reduce the target width, height, or scale factor. |  |

### Conversion warnings

| Code | Message | Notes |
| --- | --- | --- |
| `20000` | Unfortunately, during conversion we detected an issue. We converted your file as best as possible, but it might be that it could only be converted partly. Please check it manually. | Probably something happened during the conversion but we are unable to tell more. Often this results in a usable file nonetheless. |
| `20001` | Impossible to write metadata inside the file | Some of the requested metadata were not written inside the converted file. |
| `20002` | Cannot write metadata | Some of the requested metadata were not written inside the converted file. |
| `20003` | Unfortunately, we can not yet convert your file from your source file format to this target file format. |  |
| `20004` | The rendered output may be incorrect |  |
| `20005` | Your file uses an unsupported encryption format. |  |
| `20006` | The DPI value may be incorrect |  |
| `20007` | We could not compress this file any further |  |
| `20008` | The version of the converted file has been downgraded |  |
| `20009` | It was not possible to preserve transfer functions in PDF 2.0 |  |
| `20010` | The selected language was not found. Text detection can be incorrect. |  |
| `20011` | The value for the audio frequency is too low. The conversion used the lowest possible value allowed. You can also try again with a higher value or with a different codec. |  |
| `20012` | The value for the audio frequency is too high. The conversion used the highest possible value allowed. You can also try again with a smaller value or with a different codec. |  |
| `20013` | The value for the audio frequency is not allowed. The conversion used the highest possible value allowed. You can also try again with another value or with a different codec. |  |
| `20014` | The sizes of the reference image and the compared image do not match. The result can be inaccurate. |  |
| `20015` | The sizes of the reference video and the compared video do not match. The result can be inaccurate. |  |
| `20016` | The codecs of the input files does not fit the video codec. A different one was chosen. |  |
| `20017` | The model and the upscale factor chosen failed the conversion. A different combination was automatically chosen. |  |
| `20018` | The width or height exceed the limit for AI upscaling for your file. The maximum possible size is provided. |  |
| `20019` | The requested voice is not available for your language. The default gender was used. |  |
| `20020` | The requested style cannot be applied for an unexpected error. |  |
| `20021` | The requested style was not found. |  |
| `20022` | During compression we detected a larger quality degradation. Please check the result. |  |
| `20023` | The original input file frame rate or the user selected frame rate is not compatible with the used video codec. A default compatible frame rate was used instead. |  |
| `20024` | The conversion may result in excessively loud audio, which can be harmful to your hearing and damage speakers or headphones. |  |
| `20025` | We could not compress this file any further. Target file size not reached. |  |
| `20026` | We could not extract any text from some or all pages. |  |
| `20027` | We could not convert the entire audio to text. Some parts may be missing. Please review the resulting file. |  |
| `20028` | We have compressed your file but could not reach the target file size without excessive quality loss |  |
| `20029` | The output PDF file is limited to a maximum number of pages. Some pages may be missing in the output file. |  |
| `20030` | Your conversion took longer than your plan allows, so you may have received only a partial result. Please check. |  |
| `20031` | The chosen paper size is smaller than your pages, so they were scaled down to fit the booklet sheets. |  |
| `20032` | Your document mixes different page sizes. They were normalised to fit the booklet sheets. |  |

---

# Rate limits & contracts

> Quotas, concurrency and contract limits.
> Source: https://www.api2convert.com/documentation/guides/rate-limits

Your plan (contract) determines how much you can do: file sizes, daily budgets, and how many conversions can run at once.

## Free tier

Every registered user gets **30 free credits every 24 hours**. Conversions consume credits; once the day's free credits are used up, further conversions return `402 Payment Required` until the 24-hour window resets — or you add a paid plan for higher quotas.

## Inspect your limits

`GET /v2/contracts` returns the contracts and limits attached to your API key.

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

## Concurrency

Each contract caps the number of **concurrent** conversions. Exceeding it returns `429 Too Many Requests` — back off and retry. List endpoints return the total count in the `X-Count` header.

## Quotas

Exceeding your contract's budget (e.g. monthly minutes or credits) returns `402 Payment Required`. Free keys have tighter limits, including the number of inputs per job and maximum file size.

## Pagination

Listing endpoints (e.g. `GET /v2/jobs`) return up to **50** items per page. Use `?page=N` to page through results.

## Best practices

- Use [webhooks](https://www.api2convert.com/documentation/guides/webhooks) instead of tight polling loops.
- On `429`, retry with exponential backoff.
- Track usage with the [statistics endpoints](https://www.api2convert.com/documentation/guides/statistics).

---

# Statistics

> Query your API usage by day, month or year.
> Source: https://www.api2convert.com/documentation/guides/statistics

Query your API usage aggregated by day, month or year.

## Endpoints

| Endpoint | Period |
| --- | --- |
| `GET /v2/stats/day/{YYYY-MM-DD}/{filter}` | A single day. |
| `GET /v2/stats/month/{YYYY-MM}/{filter}` | A whole month. |
| `GET /v2/stats/year/{YYYY}/{filter}` | A whole year. |

The `{filter}` segment is either `single` (just the current key) or `all` (across the account).

## Example

```bash
curl "https://api.api2convert.com/v2/stats/month/2026-06/single" \
  -H "x-oc-api-key: <your-api-key>"
```

Use statistics to monitor consumption against your [contract limits](https://www.api2convert.com/documentation/guides/rate-limits).

---

# Presets

> Reusable conversion templates.
> Source: https://www.api2convert.com/documentation/guides/presets

Presets are reusable conversion templates — a saved `category` + `target` + `options` you can apply by reference instead of repeating the settings on every job.

## List presets

`GET /v2/presets` (no auth required) returns the available presets, optionally filtered:

```bash
curl "https://api.api2convert.com/v2/presets?category=video&target=mp4" \
  -H "x-oc-api-key: <your-api-key>"
```

## Create your own

Authenticated users can manage custom presets:

```
POST   /v2/presets            → create
GET    /v2/presets/{id}       → read
PATCH  /v2/presets/{id}       → update
DELETE /v2/presets/{id}       → delete
```

```
POST /v2/presets
{
  "name": "Web image",
  "category": "image",
  "target": "webp",
  "options": { "width": 1600, "height": 900 }
}
```

Apply a preset's settings to a conversion to keep requests small and consistent across your integration.

---

# SDKs & libraries

> Official SDKs for PHP, Python, Node.js, Java, .NET, Go, Ruby and Rust.
> Source: https://www.api2convert.com/documentation/guides/sdks

Official SDKs wrap the REST API in idiomatic code for your language, so you can skip the HTTP plumbing — authentication, uploads, polling and downloads are handled for you. Prefer raw HTTP? Every [guide](https://www.api2convert.com/documentation/guides/quickstart) and the [API Reference](https://www.api2convert.com/documentation/reference) generate ready-to-paste snippets in your language.

## Official SDKs

Each library is open source on GitHub and released in lockstep with the API. Pick your language, install it, and pass your API key:

- [PHP](https://github.com/QaamGo/api2convert-php) Packagist Convert, compress and transform files in one call. `composer require api2convert/sdk`
- [Python](https://github.com/QaamGo/api2convert-python) PyPI One-line file conversion for Python 3. `pip install api2convert`
- [Node.js & TypeScript](https://github.com/QaamGo/api2convert-nodejs) npm A fully typed SDK for Node.js and TypeScript. `npm install @api2convert/sdk`
- [Java](https://github.com/QaamGo/api2convert-java) Maven Central A modern SDK for Java 17 and newer. `com.api2convert:api2convert-java:10.2.0`
- [.NET & C#](https://github.com/QaamGo/api2convert-dotnet) NuGet A .NET 8 SDK with zero runtime dependencies. `dotnet add package Api2Convert`
- [Go](https://github.com/QaamGo/api2convert-go) Go modules A standard-library-only SDK for Go. `go get github.com/QaamGo/api2convert-go`
- [Ruby](https://github.com/QaamGo/api2convert-ruby) RubyGems A zero-dependency SDK for Ruby. `gem install api2convert`
- [Rust](https://github.com/QaamGo/api2convert-rust) crates.io An idiomatic, blocking SDK for Rust. `cargo add api2convert`

Full installation instructions, usage examples and the changelog live in each repository’s README. All SDKs use the same `x-oc-api-key` authentication and follow the job → input → conversion → output lifecycle described in [Jobs & lifecycle](https://www.api2convert.com/documentation/guides/job-lifecycle).

## Any other language

No SDK for your stack? The API is plain JSON over HTTPS, so any HTTP client works. Every guide shows its requests in **cURL, Node.js, Python, PHP, Go, .NET, Java, Ruby and Rust** — switch languages with the tabs on any example — and the [API Reference](https://www.api2convert.com/documentation/reference) generates a snippet for every endpoint. You can also point an AI coding agent at our [Agent Skill](https://www.api2convert.com/documentation/downloads).

---

# Service status

> Check live API uptime and incident history, and subscribe to status updates.
> Source: https://www.api2convert.com/documentation/guides/service-status

API2Convert publishes a live **status page** at [status.api2convert.com](https://status.api2convert.com/). It is the canonical place to check whether the API is operating normally, review recent uptime, and get notified about incidents. The status page is hosted independently of the API, so it stays reachable even when the API itself is affected by an outage.

[Open the status page →](https://status.api2convert.com/)

## What it shows

- **Current availability** — whether the API is up or down right now.
- **Uptime history** — the percentage of time the API was available over the last **24 hours, 7 days, 30 days and 90 days**, plus a day-by-day calendar.
- **Status updates** — a timeline of recent incidents and maintenance announcements.

The status page tracks overall API availability (up / down); it does not report per-endpoint latency or per-format processing times. To measure your own usage and throughput, use the [statistics endpoints](https://www.api2convert.com/documentation/guides/statistics).

## Subscribe to updates

Use the **Subscribe** option on the status page to receive an email whenever the status changes or an incident is posted. This is the recommended way to hear about outages and planned maintenance — no polling required.

## Service status vs. API statuses

Don't confuse the service status page with the API's own status values — they answer different questions:

| Concept | Where to look | What it tells you |
| --- | --- | --- |
| Service status page | [status.api2convert.com](https://status.api2convert.com/) | Whether the whole API platform is operational right now, plus uptime history and incidents. |
| Job status | The `status.code` field on a job (e.g. `downloading`, `completed`, `failed`) | How one of your conversion jobs is progressing. See [Jobs & lifecycle](https://www.api2convert.com/documentation/guides/job-lifecycle). |
| Job status catalogue | `GET /v2/statuses` | The list of every possible job status code and its meaning (no API key required). |

## During an incident

If requests start failing with `500` responses or time out, check the status page first to see whether it is a known platform incident. While an incident is ongoing:

- Retry failed requests with **exponential backoff** rather than tight retry loops — see [rate limits & contracts](https://www.api2convert.com/documentation/guides/rate-limits).
- Prefer [webhooks & callbacks](https://www.api2convert.com/documentation/guides/webhooks) over polling, so queued jobs report in automatically once processing resumes.
- Distinguish a platform outage from a per-job problem: a genuine outage appears on the status page, whereas a single job that fails while the platform is healthy is usually an [input or conversion error](https://www.api2convert.com/documentation/guides/errors-and-warnings).