Browse Docs

On This Page

Examples
Method + path
Auth
Content type
Form fields
Response
Example response
Full workflow
With webhook notification
Unsupported format error
Errors

Endpoint: Compress

POST /compress — compress any supported file. The server detects the format from the file extension and routes to the appropriate compressor automatically.

Examples

# compress a JPG
curl -sS -X POST "https://api.tools.fast/compress" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@photo.jpg"

# compress a PNG
curl -sS -X POST "https://api.tools.fast/compress" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@screenshot.png"

# compress a PDF
curl -sS -X POST "https://api.tools.fast/compress" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@document.pdf"

# compress a HEIC image
curl -sS -X POST "https://api.tools.fast/compress" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@photo.heic"

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("X-Fast-Api-Key", "fast_prod_your_key_here");

using var form = new MultipartFormDataContent();
form.Add(new ByteArrayContent(File.ReadAllBytes("photo.jpg")), "file", "photo.jpg");

var response = await http.PostAsync("https://api.tools.fast/compress", form);
var job = await response.Content.ReadFromJsonAsync<JsonElement>();
var jobId = job.GetProperty("id").GetString();

$headers = @{ "X-Fast-Api-Key" = "fast_prod_your_key_here" }

# compress a JPG
Invoke-RestMethod -Method Post "https://api.tools.fast/compress" `
  -Headers $headers -Form @{ file = Get-Item "photo.jpg" }

# compress a PNG
Invoke-RestMethod -Method Post "https://api.tools.fast/compress" `
  -Headers $headers -Form @{ file = Get-Item "screenshot.png" }

# compress a PDF
Invoke-RestMethod -Method Post "https://api.tools.fast/compress" `
  -Headers $headers -Form @{ file = Get-Item "document.pdf" }

Method + path

POST /compress

The server resolves the compressor from the file extension. Supported formats: JPG, PNG, GIF, WebP, AVIF, HEIC, TIFF, BMP, PSD, 20+ RAW camera formats, PDF, DOCX, PPTX.

Auth

Required: X-Fast-Api-Key

Content type

multipart/form-data required.

Form fields

Field	Required	Type	Description
`file`	yes	file	The file to compress
`options`	no	JSON string	Resize and compression settings (see Options)
`webhookUrl`	no	string	HTTPS URL to receive a webhook POST on job completion
`webhookSecret`	no (required with `webhookUrl`)	string	Shared secret for HMAC-SHA256 signature verification (16–256 chars)
`webhookEvents`	no	string	Comma-separated event filter: `succeeded`, `failed`, or both (default: both)

Notes:

Exactly one file per request.
The file extension must match a supported format.
The options field is a JSON string — not a nested multipart section. See Options Reference for the full schema.

Response

202 Accepted with job details.

Example response

{
  "id": "019c56454f8b755996c45a4874a1f3f6",
  "status": "Queued",
  "fileName": "photo",
  "format": "jpg",
  "...": "see JobAcceptedResponse model for all fields"
}

Full workflow

API_KEY="fast_prod_your_key_here"

# 1) submit
JOB_ID=$(curl -sS -X POST "https://api.tools.fast/compress" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@photo.jpg" | jq -r '.id')

# 2) poll
while true; do
  STATUS=$(curl -sS "https://api.tools.fast/compress/job/${JOB_ID}" \
    -H "X-Fast-Api-Key: $API_KEY" | jq -r '.status')
  [ "${STATUS}" = "Succeeded" ] && break
  [ "${STATUS}" = "Failed" ] || [ "${STATUS}" = "Canceled" ] && exit 1
  sleep 1
done

# 3) download
curl -sS "https://api.tools.fast/compress/job/${JOB_ID}/download" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -o "photo-compressed.jpg"

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("X-Fast-Api-Key", "fast_prod_your_key_here");

// 1) submit
using var form = new MultipartFormDataContent();
form.Add(new ByteArrayContent(File.ReadAllBytes("photo.jpg")), "file", "photo.jpg");
var submit = await http.PostAsync("https://api.tools.fast/compress", form);
var job = await submit.Content.ReadFromJsonAsync<JsonElement>();
var jobId = job.GetProperty("id").GetString();

// 2) poll
string status;
do
{
    await Task.Delay(1000);
    var poll = await http.GetFromJsonAsync<JsonElement>(
        $"https://api.tools.fast/compress/job/{jobId}");
    status = poll.GetProperty("status").GetString()!;
} while (status is "Queued" or "Running");

// 3) download
var output = await http.GetByteArrayAsync(
    $"https://api.tools.fast/compress/job/{jobId}/download");
File.WriteAllBytes("photo-compressed.jpg", output);

$headers = @{ "X-Fast-Api-Key" = "fast_prod_your_key_here" }

# 1) submit
$job = Invoke-RestMethod -Method Post "https://api.tools.fast/compress" `
  -Headers $headers `
  -Form @{ file = Get-Item "photo.jpg" }

# 2) poll
do {
  $status = (Invoke-RestMethod "https://api.tools.fast/compress/job/$($job.id)" `
    -Headers $headers).status
  if ($status -in "Failed", "Canceled") { throw "Job $($job.id) $status" }
  Start-Sleep -Seconds 1
} while ($status -ne "Succeeded")

# 3) download
Invoke-RestMethod "https://api.tools.fast/compress/job/$($job.id)/download" `
  -Headers $headers -OutFile "photo-compressed.jpg"

With webhook notification

# Compress with webhook — no polling needed
curl -sS -X POST "https://api.tools.fast/compress" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@photo.jpg" \
  -F "webhookUrl=https://example.com/webhooks/fast" \
  -F "webhookSecret=whsec_your_secret_here"

using var form = new MultipartFormDataContent();
form.Add(new ByteArrayContent(File.ReadAllBytes("photo.jpg")), "file", "photo.jpg");
form.Add(new StringContent("https://example.com/webhooks/fast"), "webhookUrl");
form.Add(new StringContent("whsec_your_secret_here"), "webhookSecret");

var response = await http.PostAsync("https://api.tools.fast/compress", form);
// No polling needed — your webhook endpoint will be called on completion

# Compress with webhook — no polling needed
Invoke-RestMethod -Method Post "https://api.tools.fast/compress" `
  -Headers $headers `
  -Form @{
    file = Get-Item "photo.jpg"
    webhookUrl = "https://example.com/webhooks/fast"
    webhookSecret = "whsec_your_secret_here"
  }

See Webhooks for payload schema, signature verification, and retry policy.

Unsupported format error

If the file extension isn't supported, you'll get a 400 with the list of supported formats:

{
  "error": "compress.unsupported_format",
  "detail": "Unsupported file format: '.mp3'.",
  "supportedFormats": [".avif", ".bmp", ".docx", ".gif", ".jpg", "..."]
}

Errors

See Errors for the full error reference with JSON examples.

Status	Codes	Cause
`400`	`request.invalid_content_type`, `request.no_files`, `request.empty_file`, `request.invalid_extension`, `compress.unsupported_format`	Bad request payload
`401`	`api_key.invalid_or_ip_not_allowed`	Invalid API key or IP not allowlisted
`402`	`entitlements.insufficient_credits`	Not enough credits
`413`	`request.file_too_large`	File exceeds size limit
`429`	`rate_limited`, `queue.limit_exceeded`	Throttled

Cost Estimate

Jobs

# Endpoint: Compress

`POST /compress` — compress any supported file. The server detects the format from the file extension and routes to the appropriate compressor automatically.

## Examples

### cURL
```bash
# compress a JPG
curl -sS -X POST "https://api.tools.fast/compress" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@photo.jpg"

# compress a PNG
curl -sS -X POST "https://api.tools.fast/compress" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@screenshot.png"

# compress a PDF
curl -sS -X POST "https://api.tools.fast/compress" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@document.pdf"

# compress a HEIC image
curl -sS -X POST "https://api.tools.fast/compress" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@photo.heic"
```

### C#
```csharp
using var http = new HttpClient();
http.DefaultRequestHeaders.Add("X-Fast-Api-Key", "fast_prod_your_key_here");

using var form = new MultipartFormDataContent();
form.Add(new ByteArrayContent(File.ReadAllBytes("photo.jpg")), "file", "photo.jpg");

var response = await http.PostAsync("https://api.tools.fast/compress", form);
var job = await response.Content.ReadFromJsonAsync<JsonElement>();
var jobId = job.GetProperty("id").GetString();
```

### PowerShell
```powershell
$headers = @{ "X-Fast-Api-Key" = "fast_prod_your_key_here" }

# compress a JPG
Invoke-RestMethod -Method Post "https://api.tools.fast/compress" `
  -Headers $headers -Form @{ file = Get-Item "photo.jpg" }

# compress a PNG
Invoke-RestMethod -Method Post "https://api.tools.fast/compress" `
  -Headers $headers -Form @{ file = Get-Item "screenshot.png" }

# compress a PDF
Invoke-RestMethod -Method Post "https://api.tools.fast/compress" `
  -Headers $headers -Form @{ file = Get-Item "document.pdf" }
```

## Method + path

- `POST /compress`

The server resolves the compressor from the file extension. Supported formats: JPG, PNG, GIF, WebP, AVIF, HEIC, TIFF, BMP, PSD, 20+ RAW camera formats, PDF, DOCX, PPTX.

## Auth

- Required: `X-Fast-Api-Key`

## Content type

- `multipart/form-data` required.

## Form fields

| Field | Required | Type | Description |
|-------|----------|------|-------------|
| `file` | yes | file | The file to compress |
| `options` | no | JSON string | Resize and compression settings (see [Options](../compressors/options.md)) |
| `webhookUrl` | no | string | HTTPS URL to receive a webhook POST on job completion |
| `webhookSecret` | no (required with `webhookUrl`) | string | Shared secret for HMAC-SHA256 signature verification (16–256 chars) |
| `webhookEvents` | no | string | Comma-separated event filter: `succeeded`, `failed`, or both (default: both) |

Notes:

- Exactly one file per request.
- The file extension must match a supported format.
- The `options` field is a JSON string — not a nested multipart section. See [Options Reference](../compressors/options.md) for the full schema.

## Response

`202 Accepted` with job details.

### Example response

```json
{
  "id": "019c56454f8b755996c45a4874a1f3f6",
  "status": "Queued",
  "fileName": "photo",
  "format": "jpg",
  "...": "see JobAcceptedResponse model for all fields"
}
```

## Full workflow

### cURL
```bash
API_KEY="fast_prod_your_key_here"

# 1) submit
JOB_ID=$(curl -sS -X POST "https://api.tools.fast/compress" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@photo.jpg" | jq -r '.id')

# 2) poll
while true; do
  STATUS=$(curl -sS "https://api.tools.fast/compress/job/${JOB_ID}" \
    -H "X-Fast-Api-Key: $API_KEY" | jq -r '.status')
  [ "${STATUS}" = "Succeeded" ] && break
  [ "${STATUS}" = "Failed" ] || [ "${STATUS}" = "Canceled" ] && exit 1
  sleep 1
done

# 3) download
curl -sS "https://api.tools.fast/compress/job/${JOB_ID}/download" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -o "photo-compressed.jpg"
```

### C#
```csharp
using var http = new HttpClient();
http.DefaultRequestHeaders.Add("X-Fast-Api-Key", "fast_prod_your_key_here");

// 1) submit
using var form = new MultipartFormDataContent();
form.Add(new ByteArrayContent(File.ReadAllBytes("photo.jpg")), "file", "photo.jpg");
var submit = await http.PostAsync("https://api.tools.fast/compress", form);
var job = await submit.Content.ReadFromJsonAsync<JsonElement>();
var jobId = job.GetProperty("id").GetString();

// 2) poll
string status;
do
{
    await Task.Delay(1000);
    var poll = await http.GetFromJsonAsync<JsonElement>(
        $"https://api.tools.fast/compress/job/{jobId}");
    status = poll.GetProperty("status").GetString()!;
} while (status is "Queued" or "Running");

// 3) download
var output = await http.GetByteArrayAsync(
    $"https://api.tools.fast/compress/job/{jobId}/download");
File.WriteAllBytes("photo-compressed.jpg", output);
```

### PowerShell
```powershell
$headers = @{ "X-Fast-Api-Key" = "fast_prod_your_key_here" }

# 1) submit
$job = Invoke-RestMethod -Method Post "https://api.tools.fast/compress" `
  -Headers $headers `
  -Form @{ file = Get-Item "photo.jpg" }

# 2) poll
do {
  $status = (Invoke-RestMethod "https://api.tools.fast/compress/job/$($job.id)" `
    -Headers $headers).status
  if ($status -in "Failed", "Canceled") { throw "Job $($job.id) $status" }
  Start-Sleep -Seconds 1
} while ($status -ne "Succeeded")

# 3) download
Invoke-RestMethod "https://api.tools.fast/compress/job/$($job.id)/download" `
  -Headers $headers -OutFile "photo-compressed.jpg"
```

### With webhook notification

### cURL
```bash
# Compress with webhook — no polling needed
curl -sS -X POST "https://api.tools.fast/compress" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@photo.jpg" \
  -F "webhookUrl=https://example.com/webhooks/fast" \
  -F "webhookSecret=whsec_your_secret_here"
```

### C#
```csharp
using var form = new MultipartFormDataContent();
form.Add(new ByteArrayContent(File.ReadAllBytes("photo.jpg")), "file", "photo.jpg");
form.Add(new StringContent("https://example.com/webhooks/fast"), "webhookUrl");
form.Add(new StringContent("whsec_your_secret_here"), "webhookSecret");

var response = await http.PostAsync("https://api.tools.fast/compress", form);
// No polling needed — your webhook endpoint will be called on completion
```

### PowerShell
```powershell
# Compress with webhook — no polling needed
Invoke-RestMethod -Method Post "https://api.tools.fast/compress" `
  -Headers $headers `
  -Form @{
    file = Get-Item "photo.jpg"
    webhookUrl = "https://example.com/webhooks/fast"
    webhookSecret = "whsec_your_secret_here"
  }
```

See [Webhooks](../webhooks.md) for payload schema, signature verification, and retry policy.

## Unsupported format error

If the file extension isn't supported, you'll get a `400` with the list of supported formats:

```json
{
  "error": "compress.unsupported_format",
  "detail": "Unsupported file format: '.mp3'.",
  "supportedFormats": [".avif", ".bmp", ".docx", ".gif", ".jpg", "..."]
}
```

## Errors

See [Errors](../errors.md) for the full error reference with JSON examples.

| Status | Codes | Cause |
|--------|-------|-------|
| `400` | `request.invalid_content_type`, `request.no_files`, `request.empty_file`, `request.invalid_extension`, `compress.unsupported_format` | Bad request payload |
| `401` | `api_key.invalid_or_ip_not_allowed` | Invalid API key or IP not allowlisted |
| `402` | `entitlements.insufficient_credits` | Not enough credits |
| `413` | `request.file_too_large` | File exceeds size limit |
| `429` | `rate_limited`, `queue.limit_exceeded` | Throttled |

Copied.