---
search:
  tags:
    - Jobs
    - POST
seo:
  description: >-
    Reserves one conversion and returns a signed upload_url that stays valid for
    15 minutes… Reference for the POST /v1/jobs endpoint in the convt API.
sidebar:
  label: Create a job
  badge: POST
title: Create a job
type: openapi-operation
---
Reserves one conversion and returns a signed `upload_url` that stays valid for 15 minutes (`upload_expires_in` is 900 seconds).

`input_bytes` must be the exact size of the file you will upload, from 1 byte to 2 GB. The upload signature binds `Content-Length`, so a different size fails at upload or at start.

Creating a job reserves 1 cent against your spend cap until the job finishes. A job that fails or is cancelled releases the reservation.

`POST /v1/jobs`

**Request body** (`application/json`, required)

- `input_format` (string, required) — Format id of the file you upload, such as \`png\` or \`docx\`. See \[Formats\](https://convt.app/docs/reference/formats).
- `target_format` (string, required) — Format id to convert to. It must differ from \`input\_format\` and be a target the input can reach.
- `input_bytes` (integer, required) — Exact size of the upload in bytes.

Request body example:

```json
{
  "input_format": "png",
  "target_format": "webp",
  "input_bytes": 48213
}
```

**Responses**

- `200` — The job was reserved. Upload the file to \`upload\_url\` next.
- `400` — \`unsupported\_format\` or \`file\_too\_large\`.
- `401` — \`unauthorized\`: no \`Authorization: Bearer\` header.
- `403` — \`unauthorized\` (key invalid or revoked) or a billing limit.
- `404` — \`not\_found\`: the job does not exist, belongs to another account, or has expired.
- `429` — \`rate\_limited\`: more than 120 requests in a minute for this key.
- `502` — \`storage\_unavailable\`: object storage did not answer. Retry with backoff.

Response example, 200:

```json
{
  "job": {
    "id": "job_01k6z7v4q8m3x2a9b5c0d1e2f3",
    "status": "created",
    "input_format": "png",
    "target_format": "webp",
    "input_bytes": 48213,
    "attempt": 0,
    "error_code": null,
    "expires_at": "2026-10-08T12:00:00Z"
  },
  "upload_url": "https://bucket.example/job_01k6z7v4q8m3x2a9b5c0d1e2f3/upload?X-Amz-Signature=…",
  "upload_expires_in": 900
}
```

Response example, 400:

```json
{
  "error": {
    "code": "unsupported_format",
    "message": "This input cannot reach the chosen target format."
  }
}
```

Response example, 403:

```json
{
  "error": {
    "code": "limit_reached",
    "message": "Your allowance or spend cap has been reached."
  }
}
```