# Compress.FAST API

Compress images, PDFs, and Office documents with one HTTP request. Built for AI agents and server-side integrations.

> **Free to start** — [create an account](https://accounts.tools.fast/account/register?utm_source=compress.fast&utm_medium=api-docs) and get 500 Pro credits instantly, no credit card required. Credits are shared across all Tools.FAST services.

## Base URL

`https://api.tools.fast`

## Authentication

Pass your key in `X-Fast-Api-Key`.

```http
X-Fast-Api-Key: fast_prod_...
```

The API is designed for **server-side integrations**. Browser-based requests are restricted to first-party origins — call the API from your backend.

## Using an AI agent?

Copy-paste this into Claude Code, ChatGPT, Cursor, or any AI coding assistant:

<!-- code-tabs:start default=curl -->
### cURL
```text
Download the Compress.FAST skill and reference docs, then use them to complete my task:

curl -fsSL https://compress.fast/SKILL.md -o SKILL.md
mkdir -p reference && curl -fsSL https://compress.fast/api/docs.md -o reference/docs.md
curl -fsSL https://compress.fast/compress.fast.sh -o compress.fast.sh && chmod +x compress.fast.sh

Read SKILL.md to understand how to use the Compress.FAST API.
```

### PowerShell
```text
Download the Compress.FAST skill and reference docs, then use them to complete my task:

Invoke-RestMethod "https://compress.fast/SKILL.md" -OutFile SKILL.md
New-Item -ItemType Directory -Force -Path reference | Out-Null
Invoke-RestMethod "https://compress.fast/api/docs.md" -OutFile reference/docs.md
Invoke-RestMethod "https://compress.fast/compress.fast.ps1" -OutFile compress.fast.ps1

Read SKILL.md to understand how to use the Compress.FAST API.
```
<!-- code-tabs:end -->

> **Reference doc size** — the snippets above download `docs.md` (~32k tokens, full API reference). See [For AI Agents](for-ai.md) for details.

Your agent downloads a skill guide, the core API reference, and a CLI wrapper, then compresses files autonomously. Set `TOOLS_FAST_API_KEY` as an environment variable, or lock your API key to your IP address and pass it directly to the agent — see [For AI Agents](for-ai.md) for full setup.

## Quickstart

<!-- code-tabs:start default=curl -->
### cURL
```bash
API_KEY="fast_prod_your_key_here"
INPUT="./photo.jpg"

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

# 2) poll for terminal status
while true; do
  STATUS=$(curl -sS "https://api.tools.fast/compress/job/${JOB_ID}" \
    -H "X-Fast-Api-Key: ${API_KEY}" | jq -r '.status')

  if [ "${STATUS}" = "Succeeded" ]; then
    break
  fi

  if [ "${STATUS}" = "Failed" ] || [ "${STATUS}" = "Canceled" ]; then
    echo "job ended with status=${STATUS}"
    exit 1
  fi

  sleep 1
done

# 3) download compressed output
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 compression
$job = Invoke-RestMethod -Method Post "https://api.tools.fast/compress" `
  -Headers $headers `
  -Form @{ file = Get-Item "photo.jpg" }

# 2) poll for terminal status
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 compressed output
Invoke-RestMethod "https://api.tools.fast/compress/job/$($job.id)/download" `
  -Headers $headers -OutFile "photo-compressed.jpg"
```
<!-- code-tabs:end -->

## How it works

1. `POST /compress` with multipart form data (`file` field).
2. `GET /compress/job/{id}` until terminal status.
3. `GET /compress/job/{id}/download` to retrieve the compressed output.

## Discovery endpoints

Three discovery endpoints help clients understand what's available:

| Endpoint | Description |
|----------|-------------|
| `GET /compress/compressors` | List all compressors with costing, limits, and format graph |
| `GET /compress/schema` | JSON Schema for compressor options |
| `GET /compress/estimate/{format}` | Estimate credit cost before uploading |

Like all endpoints, these require `X-Fast-Api-Key` and return limits personalized to your plan.

## Supported compressors

| Format | Input Types |
|--------|-------------|
| JPG | `.jpg`, `.jpeg` |
| PNG | `.png` |
| GIF | `.gif` |
| PDF | `.pdf` |
| Office | `.docx`, `.pptx` |
| Universal Image | 37+ image formats |

All formats use the unified `POST /compress` endpoint — the format is auto-detected from the file extension.

## Credit-based pricing

Every compression costs credits. Check your balance at `GET /compress/entitlements/me`. Credits are shared across all Tools.FAST services (Convert.FAST, Compress.FAST, etc.).

## Typical response times

| Compression type | Typical time |
|-----------------|-------------|
| JPG, PNG, GIF images | 1--3 seconds |
| Universal image (37+ formats) | 2--5 seconds |
| PDF documents | 3--10 seconds |
| Office documents (DOCX, PPTX) | 3--10 seconds |

Times depend on file size and server load. Use polling for real-time status updates.

## Rate limits

All API endpoints are rate-limited. Each account can have up to **18 jobs queued + running** at a time — submitting beyond this limit returns `429` with a `Retry-After` header. Up to **6** of those jobs will run concurrently; additional jobs stay queued until a slot opens. See the [Rate Limits](rate-limits.md) page for details.

## File retention

**Output files are available for download for 1 hour after job completion, then automatically deleted.** After that, `GET /compress/job/{id}/download` returns `410 Gone`. To clean up immediately after downloading, call `DELETE /compress/job/{id}` — this removes the job and its output files from our servers right away.

**Webhooks** — receive a POST notification when a job completes instead of polling. Pass `webhookUrl` and `webhookSecret` when submitting a job. See [Webhooks](webhooks.md) for the full guide.

## All Compressors

> `POST /compress` — auto-detects format from file extension. `GET /compress/compressors` returns rich metadata with costing, limits, and format graph.

### Images (4) | 1 cr/5 MB | max 1 GB

| Endpoint | Formats | Options |
|----------|---------|---------|
| `/compress/gif` | gif | resize |
| `/compress/jpg` | jpg | resize |
| `/compress/png` | png | resize, compression |
| `/compress/image` | 37+ formats (jpg, png, webp, avif, heic, heif, tiff, ...) | resize |

### Documents (2) | 1 cr/5 MB | max 1 GB

| Endpoint | Formats | Options |
|----------|---------|---------|
| `/compress/pdf` | pdf | — |
| `/compress/office` | docx, pptx | resize |