Response Format

Every request to the Compressor API returns a structured JSON response. At minimum, each response includes a unique request identifier and reflects the outcome of the operation via the HTTP status code. Depending on the size of the input and the processing mode, responses fall into one of two categories: synchronous results or asynchronous job acknowledgements.

Synchronous Responses

For small to medium-sized files — where compression or optimization completes quickly — the API holds the HTTP connection open and returns a full result payload once processing finishes.

A successful synchronous response includes:

• A unique id identifying the request
• A downloadable url pointing to the processed file
• Detailed metadata for both the input and output files
• File hashes to support integrity checks and tracking

Example:

{
  "id": "38a8bb5e-7b50-4a22-a0a6-b9602fccb225",
  "url": "https://api.compressor.app/1765712100/38a8bb5e-7b50-4a22-a0a6-b9602fccb225/image.jpeg",
  "input": {
    "name": "image.jpg",
    "type": "image",
    "format": "jpeg",
    "mime": "image/jpeg",
    "size": 588603,
    "sha1": "aad2a74bc3c322b2a1db120ed0d8804c1b23e9bb"
  },
  "output": {
    "name": "image.jpeg",
    "type": "image",
    "format": "jpeg",
    "mime": "image/jpeg",
    "size": 257042,
    "sha1": "0fa123704be4c84af340f3f6ede800ba254344c2"
  }
}

The returned url may point to temporary storage or to a permanent destination if an External Storage Connector was used. Input and output hashes can be used for deduplication, auditing, or downstream verification.

Asynchronous Responses

For long-running operations — such as large videos, archives, batch jobs, or any file exceeding 32 MB — the API automatically switches to asynchronous mode. In these cases, the request returns immediately without waiting for processing to complete.

The response contains only the job identifier and initial status:

{
  "id": "38a8bb5e-7b50-4a22-a0a6-b9602fccb225",
  "status": "enqueued"
}

You can use this id to track progress and retrieve results via Webhooks or Long Polling. Full job lifecycle handling is covered in the dedicated Async Processing documentation.

Error Responses

If a request fails, the API returns an appropriate HTTP status code (typically in the 4xx or 5xx range) along with a structured error response. Error payloads include:

• The HTTP error code
• A unique request id
• A human-readable message describing the issue

Example:

{
  "success": false,
  "id": "0c3a7bf4-9986-4f4a-bb72-155e9111c5de",
  "message": "Incoming request body does not contain a valid JSON data"
}

Some error responses — such as validation failures — may include an additional errors array with field-level details, as described in the Validation Errors section.

When contacting support about a failed request, always include the request id to speed up investigation.