Conversions

A conversion is an asynchronous job: you create it, then fetch its status until it completes.

#Create a conversion

POST /conversions

{
  "inputKey": "inputs/8f2b...",
  "source": "png",
  "target": "webp",
  "options": { "quality": 82 }
}

| Field | Type | Notes | | --- | --- | --- | | inputKey | string | From the /uploads response | | source | string | Source format id (e.g. png, mp4, wav) | | target | string | Target format id (e.g. webp, mp3) | | options | object | Optional. quality, width, height, crf, bitrate |

Returns { "jobId": "..." }.

#Get a conversion

GET /conversions/:jobId

{
  "status": "done",
  "downloadUrl": "https://...",
  "bytesOut": 18233
}

status is one of pending, processing, done or error. When error, an error field describes what went wrong.

#Batch conversions

Convert many files at once — each to its own target — with POST /conversions/batch:

{
  "items": [
    { "inputKey": "inputs/a", "source": "png", "target": "webp" },
    { "inputKey": "inputs/b", "source": "mov", "target": "mp3" },
    { "inputKey": "inputs/c", "source": "heic", "target": "jpeg" }
  ]
}

Returns one entry per item (in order). Unsupported pairs are reported per item rather than failing the whole request:

{
  "jobs": [
    { "jobId": "8f2b…", "source": "png", "target": "webp" },
    { "jobId": "1a4c…", "source": "mov", "target": "mp3" },
    { "source": "heic", "target": "jpeg", "error": "unsupported conversion" }
  ]
}

Up to 25 items per batch (HTTP 413 beyond that); each input still obeys the per-file size limit. Poll each jobId as usual.

#Options

• quality (1–100) — image/audio quality where supported.
• width / height — resize output; aspect ratio is preserved when one is given.
• crf (0–51) — video constant rate factor; lower is higher quality.
• bitrate — audio bitrate in kbps (e.g. 192).

See the formats reference for the full list of source and target ids.