Start a job

Seals the uploaded file, checks that its size matches input_bytes, and queues the job. The response usually shows queued.

Calling start again is safe: a job that is no longer created is returned as it is. If the uploaded size does not match, the job is cancelled and the call fails with size_mismatch. Reserve a new job to try again.

If nothing was uploaded, start fails with 502 storage_unavailable and the job stays created. Check that your PUT succeeded before you retry.

POST/v1/jobs/{id}/start

Authorization

AuthorizationBearer token · headerrequired

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

Path parameters

idstringrequired

The job id returned when you created the job, such as job_01k6z7v4q8m3x2a9b5c0d1e2f3.

Responses

200

The job, now queued, or unchanged if it was already started.

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

400

size_mismatch: the upload's size differs from input_bytes. The job is cancelled.

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

Parameters

idpath*The job id returned when you created the job, such as `job_01k6z7v4q8m3x2a9b5c0d1e2f3`.

Request

curl -X POST 'https://convt-api-production.up.railway.app/v1/jobs/job_01k6z7v4q8m3x2a9b5c0d1e2f3/start' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

import axios from "axios";

const response = await axios.request({
  method: "POST",
  url: "https://convt-api-production.up.railway.app/v1/jobs/job_01k6z7v4q8m3x2a9b5c0d1e2f3/start",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json"
  }
});

const response = await fetch("https://convt-api-production.up.railway.app/v1/jobs/job_01k6z7v4q8m3x2a9b5c0d1e2f3/start", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json"
  }
});

import requests

response = requests.post(
    "https://convt-api-production.up.railway.app/v1/jobs/job_01k6z7v4q8m3x2a9b5c0d1e2f3/start",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json"
    },
)

Response

{
  "id": "job_01k6z7v4q8m3x2a9b5c0d1e2f3",
  "status": "queued",
  "input_format": "png",
  "target_format": "webp",
  "input_bytes": 48213,
  "attempt": 0,
  "error_code": null,
  "expires_at": "2026-10-08T12:00:00Z"
}

{
  "error": {
    "code": "size_mismatch",
    "message": "Uploaded size must match the reservation and stay within 2 GB."
  }
}

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

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

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

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

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