# How to Control Prompt Compression on a Per‑Request Basis in FreeLLMAPI

> Control FreeLLMAPI prompt compression per request using the X-FreeLLM-Compress header. Override global settings for individual API calls and optimize your LLM interactions.

- Repository: [Tashfeen/freellmapi](https://github.com/tashfeenahmed/freellmapi)
- Tags: how-to-guide
- Published: 2026-08-28

---

**Use the `X-FreeLLM-Compress` request header to override compression settings for individual API calls without changing global configuration.**

FreeLLMAPI processes prompt compression **before** caching, routing, and provider selection occur. While operators set a baseline mode via dashboard or environment variables, clients can fine-tune compression behavior per-request using a dedicated HTTP header. This guide explains the complete mechanism as implemented in the [tashfeenahmed/freellmapi](https://github.com/tashfeenahmed/freellmapi) repository.

## How the X-FreeLLM-Compress Header Works

The compression pipeline in [`server/src/services/compression/pipeline.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/compression/pipeline.ts) reads the `X-FreeLLM-Compress` header and merges it with the global configuration. The `compressRequest` function normalizes the header value and resolves the effective compression mode using these rules:

| Header value | Behavior |
|--------------|----------|
| `off` | **Disables compression entirely** for this request, regardless of global settings |
| `on` | Uses the **currently configured global mode** (e.g., `lossless`, `standard`, or `aggressive`) |
| `lossless` / `standard` / `aggressive` | Forces that specific engine **only if it does not exceed** the global mode; otherwise capped to global setting |

The pipeline **cannot be used to escalate** compression beyond what the operator allows. If a client requests `aggressive` but the global mode is `standard`, the pipeline silently downgrades to `standard`. This preserves the "master‑switch" guarantee that clients cannot bypass operator-configured limits.

## Sending Per‑Request Compression Headers

### Disable Compression for a Single Request

Force zero compression when you need raw prompt fidelity:

```typescript
await fetch('https://api.free.llm/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-FreeLLM-Compress': 'off',
  },
  body: JSON.stringify({
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Detailed technical specification...' }]
  })
});

```

### Use the Globally Configured Mode

Explicitly opt into the server's current setting without hardcoding a value:

```typescript
await fetch('https://api.free.llm/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-FreeLLM-Compress': 'on',
  },
  body: JSON.stringify({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: 'Summarize this article...' }]
  })
});

```

### Request a Specific Engine (Downgrade-Only)

Attempt `aggressive` compression, which succeeds only if permitted globally:

```typescript
await fetch('https://api.free.llm/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-FreeLLM-Compress': 'aggressive',
  },
  body: JSON.stringify({
    model: 'claude-3-opus',
    messages: [{ role: 'user', content: 'Long document for analysis...' }]
  })
});

```

If the global mode is `standard`, this request receives `standard` compression without error.

## Inspecting Compression Results

The server returns the **actual compression mode applied** and **estimated savings** in the response header `X-FreeLLM-Compress`:

```typescript
const response = await fetch(/* ... */);
const compressionInfo = response.headers.get('X-FreeLLM-Compress');

// Example: "standard; saved~=1840"
console.log('Compression used:', compressionInfo);

```

This feedback loop lets clients verify whether their requested mode was honored or downgraded.

## Implementation Details in the Source Code

According to the FreeLLMAPI source code, the per-request control flow spans several key files:

- **[`server/src/services/compression/pipeline.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/compression/pipeline.ts)** — Core `compressRequest` function that parses `req.headers['x-freellm-compress']`, resolves the effective mode, executes engines, and sets the response header.

- **[`server/src/services/compression/config.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/compression/config.ts)** — Stores global configuration and provides fingerprinting helpers for cache key generation.

- **[`server/src/routes/compression.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/compression.ts)** — Admin API for reading and updating global compression settings.

- **[`server/src/routes/responses.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/responses.ts)** — Demonstrates pipeline invocation for chat completions and response header attachment.

The behavior is documented in [`docs/compression.md`](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/compression.md) (lines 28–38), which confirms the header value semantics and downgrade-only enforcement.

## Global vs. Per‑Request Priority

The resolution hierarchy ensures operator control:

1. Client sends `X-FreeLLM-Compress` header
2. Pipeline normalizes the value
3. **Ceiling check**: Requested mode is capped to global mode if higher
4. Resolved mode executes through compression engines
5. Result metadata returned in response header

This design balances **client flexibility** with **operator governance**—clients can reduce compression intensity or accept the default, but never exceed configured limits.

## Summary

- **`X-FreeLLM-Compress: off`** guarantees zero compression for sensitive prompts
- **`X-FreeLLM-Compress: on`** defers to the globally configured mode
- **Specific engine values** (`lossless`, `standard`, `aggressive`) work only at or below the global setting
- Response header `X-FreeLLM-Compress` reveals the actual mode applied and character savings
- The `compressRequest` function in [`server/src/services/compression/pipeline.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/compression/pipeline.ts) implements all header parsing and mode resolution

## Frequently Asked Questions

### What happens if I send an invalid X-FreeLLM-Compress value?

The pipeline treats unrecognized values as **no override**, falling back to the global configuration. No error is returned; the request proceeds with default compression.

### Can I use per-request compression with all FreeLLMAPI endpoints?

The header is honored by any route invoking the compression pipeline, including chat completions via [`server/src/routes/responses.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/responses.ts). Administrative endpoints in [`server/src/routes/compression.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/compression.ts) bypass client headers and use direct configuration access.

### Why can't I escalate above the global mode?

This restriction prevents clients from circumventing cost controls, latency guarantees, or content policies set by operators. The "master-switch" design in [`server/src/services/compression/pipeline.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/services/compression/pipeline.ts) enforces this ceiling during mode resolution.

### How do I check my current global compression setting?

Query the admin endpoint or inspect the `FREELLMAPI_COMPRESSION` environment variable. The dashboard and [`server/src/routes/compression.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/compression.ts) routes expose current configuration without requiring code changes.