Browse Docs

On This Page

Applicability
Sending options
Schema version
Resize
Resize fields
Presets
Custom mode
Resize examples
PNG compression mode
Combined options
Server-side defaults
Omitting options

Options Reference

The options form field lets you control resize behavior and PNG compression mode. Pass it as a JSON string alongside file in the multipart form data.

To discover options programmatically, use the Schema endpoint which returns the same information as machine-readable JSON Schema.

Applicability

Not all options apply to every compressor. The table below shows which options are supported:

Compressor	Resize	Compression mode
JPG	yes	--
PNG	yes	yes
GIF	yes	--
Universal	yes	--
PDF	--	--
Office	yes	--

Resize on image compressors resizes the image itself. On Office compressors (Word, PowerPoint), it resizes embedded images within the document while preserving page layout. PDF compression has no user-controllable options.

Sending options

# resize to 1080p while compressing
curl -sS -X POST "https://api.tools.fast/compress" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@photo.jpg" \
  -F 'options={"_schemaVersion":1,"resize":{"enabled":true,"preset":"1080p","mode":"pixels","value":null}}'

using var form = new MultipartFormDataContent();
form.Add(new ByteArrayContent(File.ReadAllBytes("photo.jpg")), "file", "photo.jpg");
form.Add(new StringContent("""{"_schemaVersion":1,"resize":{"enabled":true,"preset":"1080p","mode":"pixels","value":null}}"""),
    "options");

var response = await http.PostAsync("https://api.tools.fast/compress", form);

$form = @{
    file    = Get-Item "photo.jpg"
    options = '{"_schemaVersion":1,"resize":{"enabled":true,"preset":"1080p","mode":"pixels","value":null}}'
}

Invoke-RestMethod -Method Post "https://api.tools.fast/compress" `
  -Headers @{ "X-Fast-Api-Key" = $Key } -Form $form

Schema version

Every options payload must include _schemaVersion. The current version is 1.

{ "_schemaVersion": 1 }

Resize

Available on image compressors (JPG, PNG, GIF, Universal) and Office compressors (Word, PowerPoint). Not available on the PDF compressor.

On image compressors, resize scales the image itself -- the longest edge is capped at the target size. Images smaller than the target are not upscaled.

On Office compressors (Word, PowerPoint), resize scales embedded images within the document. The document layout and page dimensions are preserved -- only the image data inside the file is resized.

{
  "_schemaVersion": 1,
  "resize": {
    "enabled": true,
    "preset": "1080p",
    "mode": "pixels",
    "value": null
  }
}

Resize fields

Field	Type	Required	Description
`enabled`	boolean	yes	Whether to resize
`preset`	string	yes	`"off"`, `"4k"`, `"2k"`, `"1080p"`, `"720p"`, or `"custom"`
`mode`	string	no	`"pixels"` or `"percentage"` (only used when preset is `"custom"`)
`value`	number\|null	no	Custom value (only used when preset is `"custom"`)

Presets

Preset	Longest edge	Notes
`off`	No resize	Default behavior
`4k`	3840 px
`2k`	2048 px	API only -- not shown in browser UI
`1080p`	1920 px
`720p`	1280 px
`custom`	Set via `mode` + `value`

Custom mode

When preset is "custom":

mode: "pixels" -- value sets the longest edge in pixels (100--10000)
mode: "percentage" -- value sets the scale percentage (1--99)

Resize examples

# resize to 720p
curl -sS -X POST "https://api.tools.fast/compress" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@photo.jpg" \
  -F 'options={"_schemaVersion":1,"resize":{"enabled":true,"preset":"720p","mode":"pixels","value":null}}'

# resize to custom 800px
curl -sS -X POST "https://api.tools.fast/compress" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@photo.jpg" \
  -F 'options={"_schemaVersion":1,"resize":{"enabled":true,"preset":"custom","mode":"pixels","value":800}}'

# resize embedded images in a Word doc
curl -sS -X POST "https://api.tools.fast/compress" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@report.docx" \
  -F 'options={"_schemaVersion":1,"resize":{"enabled":true,"preset":"1080p","mode":"pixels","value":null}}'

// resize to 720p
var options720 = """{"_schemaVersion":1,"resize":{"enabled":true,"preset":"720p","mode":"pixels","value":null}}""";

// resize to custom 800px
var optionsCustom = """{"_schemaVersion":1,"resize":{"enabled":true,"preset":"custom","mode":"pixels","value":800}}""";

// resize embedded images in an Office doc
var optionsOffice = """{"_schemaVersion":1,"resize":{"enabled":true,"preset":"1080p","mode":"pixels","value":null}}""";

PNG compression mode

Available on the PNG compressor only. Controls lossy vs lossless compression.

{
  "_schemaVersion": 1,
  "compression": {
    "mode": "lossless"
  }
}

Field	Type	Required	Description
`mode`	string	yes	`"lossy"` (default) or `"lossless"`

Lossy -- quantizes colors (libimagequant) then optimizes (Oxipng). Maximum compression, near-imperceptible quality loss.
Lossless -- Oxipng optimization only. Output is pixel-identical to the input.

Combined options

Resize and compression mode can be used together on PNGs:

# lossless compression + resize to 1080p
curl -sS -X POST "https://api.tools.fast/compress" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@screenshot.png" \
  -F 'options={"_schemaVersion":1,"resize":{"enabled":true,"preset":"1080p","mode":"pixels","value":null},"compression":{"mode":"lossless"}}'

var options = """{"_schemaVersion":1,"resize":{"enabled":true,"preset":"1080p","mode":"pixels","value":null},"compression":{"mode":"lossless"}}""";

using var form = new MultipartFormDataContent();
form.Add(new ByteArrayContent(File.ReadAllBytes("screenshot.png")), "file", "screenshot.png");
form.Add(new StringContent(options), "options");

var response = await http.PostAsync("https://api.tools.fast/compress", form);

$form = @{
    file    = Get-Item "screenshot.png"
    options = '{"_schemaVersion":1,"resize":{"enabled":true,"preset":"1080p","mode":"pixels","value":null},"compression":{"mode":"lossless"}}'
}

Invoke-RestMethod -Method Post "https://api.tools.fast/compress" `
  -Headers @{ "X-Fast-Api-Key" = $Key } -Form $form

Server-side defaults

These settings are applied automatically and cannot be changed via the API. Documented here for transparency.

Compressor	Default behavior
JPG	Quality 85, progressive encoding, optimized Huffman coding, metadata stripped
PNG (lossy)	Quality 95, dither 0.5, effort 9
PNG (lossless)	Oxipng only, no quantization
GIF	Dither 0.5, effort 9, metadata stripped
Universal	JPEG quality 85 for opaque images, PNG quality 80 for transparent images
PDF	Screen preset (72 DPI), linearized for web viewing
Office	Embedded images recompressed at JPEG quality 85

Omitting options

The options field is entirely optional. If omitted, the compressor uses its server-side defaults with no resize.

Entitlements

JPG Compressor

# Options Reference

The `options` form field lets you control resize behavior and PNG compression mode. Pass it as a JSON string alongside `file` in the multipart form data.

To discover options programmatically, use the [Schema endpoint](../endpoints/schema.md) which returns the same information as machine-readable JSON Schema.

## Applicability

Not all options apply to every compressor. The table below shows which options are supported:

| Compressor | Resize | Compression mode |
|------------|:------:|:----------------:|
| [JPG](jpg.md) | yes | -- |
| [PNG](png.md) | yes | yes |
| [GIF](gif.md) | yes | -- |
| [Universal](universal.md) | yes | -- |
| [PDF](pdf.md) | -- | -- |
| [Office](office.md) | yes | -- |

**Resize** on image compressors resizes the image itself. On Office compressors (Word, PowerPoint), it resizes _embedded images_ within the document while preserving page layout. PDF compression has no user-controllable options.

## Sending options

### cURL
```bash
# resize to 1080p while compressing
curl -sS -X POST "https://api.tools.fast/compress" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@photo.jpg" \
  -F 'options={"_schemaVersion":1,"resize":{"enabled":true,"preset":"1080p","mode":"pixels","value":null}}'
```

### C#
```csharp
using var form = new MultipartFormDataContent();
form.Add(new ByteArrayContent(File.ReadAllBytes("photo.jpg")), "file", "photo.jpg");
form.Add(new StringContent("""{"_schemaVersion":1,"resize":{"enabled":true,"preset":"1080p","mode":"pixels","value":null}}"""),
    "options");

var response = await http.PostAsync("https://api.tools.fast/compress", form);
```

### PowerShell
```powershell
$form = @{
    file    = Get-Item "photo.jpg"
    options = '{"_schemaVersion":1,"resize":{"enabled":true,"preset":"1080p","mode":"pixels","value":null}}'
}

Invoke-RestMethod -Method Post "https://api.tools.fast/compress" `
  -Headers @{ "X-Fast-Api-Key" = $Key } -Form $form
```

## Schema version

Every options payload must include `_schemaVersion`. The current version is **1**.

```json
{ "_schemaVersion": 1 }
```

## Resize

Available on image compressors (JPG, PNG, GIF, Universal) and Office compressors (Word, PowerPoint). Not available on the PDF compressor.

On **image compressors**, resize scales the image itself -- the longest edge is capped at the target size. Images smaller than the target are not upscaled.

On **Office compressors** (Word, PowerPoint), resize scales embedded images within the document. The document layout and page dimensions are preserved -- only the image data inside the file is resized.

```json
{
  "_schemaVersion": 1,
  "resize": {
    "enabled": true,
    "preset": "1080p",
    "mode": "pixels",
    "value": null
  }
}
```

### Resize fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `enabled` | boolean | yes | Whether to resize |
| `preset` | string | yes | `"off"`, `"4k"`, `"2k"`, `"1080p"`, `"720p"`, or `"custom"` |
| `mode` | string | no | `"pixels"` or `"percentage"` (only used when preset is `"custom"`) |
| `value` | number\|null | no | Custom value (only used when preset is `"custom"`) |

### Presets

| Preset | Longest edge | Notes |
|--------|-------------|-------|
| `off` | No resize | Default behavior |
| `4k` | 3840 px | |
| `2k` | 2048 px | API only -- not shown in browser UI |
| `1080p` | 1920 px | |
| `720p` | 1280 px | |
| `custom` | Set via `mode` + `value` | |

### Custom mode

When `preset` is `"custom"`:

- **`mode: "pixels"`** -- `value` sets the longest edge in pixels (100--10000)
- **`mode: "percentage"`** -- `value` sets the scale percentage (1--99)

### Resize examples

### cURL
```bash
# resize to 720p
curl -sS -X POST "https://api.tools.fast/compress" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@photo.jpg" \
  -F 'options={"_schemaVersion":1,"resize":{"enabled":true,"preset":"720p","mode":"pixels","value":null}}'

# resize to custom 800px
curl -sS -X POST "https://api.tools.fast/compress" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@photo.jpg" \
  -F 'options={"_schemaVersion":1,"resize":{"enabled":true,"preset":"custom","mode":"pixels","value":800}}'

# resize embedded images in a Word doc
curl -sS -X POST "https://api.tools.fast/compress" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@report.docx" \
  -F 'options={"_schemaVersion":1,"resize":{"enabled":true,"preset":"1080p","mode":"pixels","value":null}}'
```

### C#
```csharp
// resize to 720p
var options720 = """{"_schemaVersion":1,"resize":{"enabled":true,"preset":"720p","mode":"pixels","value":null}}""";

// resize to custom 800px
var optionsCustom = """{"_schemaVersion":1,"resize":{"enabled":true,"preset":"custom","mode":"pixels","value":800}}""";

// resize embedded images in an Office doc
var optionsOffice = """{"_schemaVersion":1,"resize":{"enabled":true,"preset":"1080p","mode":"pixels","value":null}}""";
```

## PNG compression mode

Available on the PNG compressor only. Controls lossy vs lossless compression.

```json
{
  "_schemaVersion": 1,
  "compression": {
    "mode": "lossless"
  }
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `mode` | string | yes | `"lossy"` (default) or `"lossless"` |

- **Lossy** -- quantizes colors (libimagequant) then optimizes (Oxipng). Maximum compression, near-imperceptible quality loss.
- **Lossless** -- Oxipng optimization only. Output is pixel-identical to the input.

### Combined options

Resize and compression mode can be used together on PNGs:

### cURL
```bash
# lossless compression + resize to 1080p
curl -sS -X POST "https://api.tools.fast/compress" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@screenshot.png" \
  -F 'options={"_schemaVersion":1,"resize":{"enabled":true,"preset":"1080p","mode":"pixels","value":null},"compression":{"mode":"lossless"}}'
```

### C#
```csharp
var options = """{"_schemaVersion":1,"resize":{"enabled":true,"preset":"1080p","mode":"pixels","value":null},"compression":{"mode":"lossless"}}""";

using var form = new MultipartFormDataContent();
form.Add(new ByteArrayContent(File.ReadAllBytes("screenshot.png")), "file", "screenshot.png");
form.Add(new StringContent(options), "options");

var response = await http.PostAsync("https://api.tools.fast/compress", form);
```

### PowerShell
```powershell
$form = @{
    file    = Get-Item "screenshot.png"
    options = '{"_schemaVersion":1,"resize":{"enabled":true,"preset":"1080p","mode":"pixels","value":null},"compression":{"mode":"lossless"}}'
}

Invoke-RestMethod -Method Post "https://api.tools.fast/compress" `
  -Headers @{ "X-Fast-Api-Key" = $Key } -Form $form
```

## Server-side defaults

These settings are applied automatically and cannot be changed via the API. Documented here for transparency.

| Compressor | Default behavior |
|------------|-----------------|
| **JPG** | Quality 85, progressive encoding, optimized Huffman coding, metadata stripped |
| **PNG (lossy)** | Quality 95, dither 0.5, effort 9 |
| **PNG (lossless)** | Oxipng only, no quantization |
| **GIF** | Dither 0.5, effort 9, metadata stripped |
| **Universal** | JPEG quality 85 for opaque images, PNG quality 80 for transparent images |
| **PDF** | Screen preset (72 DPI), linearized for web viewing |
| **Office** | Embedded images recompressed at JPEG quality 85 |

## Omitting options

The `options` field is entirely optional. If omitted, the compressor uses its server-side defaults with no resize.

Copied.