Create a job

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

Authorization

AuthorizationBearer token · headerrequired

A cvt_live_ API key from the dashboard, sent as Authorization: Bearer cvt_live_…. Keep it on your server.

Request body

requiredapplication/json

input_formatstringrequired

Format id of the file you upload, such as png or docx. See Formats.

target_formatstringrequired

Format id to convert to. It must differ from input_format and be a target the input can reach.

input_bytesintegerrequired

Exact size of the upload in bytes.

min 1 · max 2000000000

Responses

200

The job was reserved. Upload the file to upload_url next.

jobJob

One conversion and its state.

Show properties

idstringrequired

Job id, prefixed job_.

statusstringrequired

created → queued → running → succeeded or failed. cancelled can happen at any point before the job finishes. uploaded is reserved and not used yet.

Allowed:createduploadedqueuedrunningsucceededfailedcancelled

input_formatstring

target_formatstring

input_bytesinteger | null

Size you reserved

attemptinteger

How many times a worker has picked up the job. Starts at 0.

error_codestring | null

Why a failed job failed (conversion_failed, expired_or_exhausted or worker_shutdown), otherwise null.

expires_atstring<date-time>required

When the job and its files are deleted

upload_urlstring<uri>

Signed URL. Send the file bytes to it with PUT.

upload_expires_ininteger

Seconds until upload_url stops accepting uploads. Always 900.

400

unsupported_format or file_too_large.

errorobject

Show properties

codestring

messagestring

401

unauthorized: no Authorization: Bearer header.

errorobject

Show properties

codestring

messagestring

403

unauthorized (key invalid or revoked) or a billing limit.

errorobject

Show properties

codestring

messagestring

404

not_found: the job does not exist, belongs to another account, or has expired.

errorobject

Show properties

codestring

messagestring

429

rate_limited: more than 120 requests in a minute for this key.

errorobject

Show properties

codestring

messagestring

502

storage_unavailable: object storage did not answer. Retry with backoff.

errorobject

Show properties

codestring

messagestring

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Bodyapplication/json

input_formatstring*Format id of the file you upload, such as `png` or `docx`. See [Formats](https://convt.app/docs/reference/formats).target_formatstring*Format id to convert to. It must differ from `input_format` and be a target the input can reach.input_bytesinteger*Exact size of the upload in bytes.

Request

curl -X POST 'https://convt-api-production.up.railway.app/v1/jobs' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "input_format": "png",
  "target_format": "webp",
  "input_bytes": 48213
}'

import axios from "axios";

const response = await axios.request({
  method: "POST",
  url: "https://convt-api-production.up.railway.app/v1/jobs",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  data: "{\n  \"input_format\": \"png\",\n  \"target_format\": \"webp\",\n  \"input_bytes\": 48213\n}"
});

const response = await fetch("https://convt-api-production.up.railway.app/v1/jobs", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"input_format\": \"png\",\n  \"target_format\": \"webp\",\n  \"input_bytes\": 48213\n}"
});

import requests

response = requests.post(
    "https://convt-api-production.up.railway.app/v1/jobs",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"input_format\": \"png\",\n  \"target_format\": \"webp\",\n  \"input_bytes\": 48213\n}",
)

Response

{
  "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
}

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

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

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

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}