Compressions

Compression models shorten a long context, such as a contract, a knowledge base article, or retrieved documents, down to the parts that matter for one prompt. Use them before an expensive chat model when input tokens drive your cost, or when a context won’t fit the next model’s window. A compression costs a fraction of the input tokens it saves on a frontier model.

Not the same as context compression

Context compression is a setting that shrinks chat requests automatically. This endpoint is an explicit call you make, and you decide what to send next.

Send a compression request

Send context, the text to shorten, and prompt, the question it’s being shortened for. Both are required and can’t be blank.

curl https://api-gateway.merge.dev/v1/compressions \
  -H "Authorization: Bearer $MERGE_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "scaledown/compress",
    "context": "Northwind Supply'\''s master services agreement with Acme Corp was signed on 2025-03-01 and runs for three years. It covers pallet delivery to Acme'\''s warehouses in Chicago, Denver, and Atlanta, with a minimum of 40 pallets per month. Prices are fixed for the first year and then rise with the producer price index, capped at 4% per year. Invoices are due net 30 from the issue date. Late payments accrue 1.5% interest per month after a 10-day grace period, and Northwind may pause deliveries once an invoice is 45 days overdue. Disputed line items must be raised in writing within 15 days of the invoice; undisputed amounts stay due on the original date. Either party can terminate with 60 days'\'' written notice, or immediately for a material breach left uncured for 30 days. Disputes that can'\''t be settled by the account managers go to binding arbitration in Chicago under AAA commercial rules. Insurance: Northwind carries $5M in cargo coverage per shipment.",
    "prompt": "When is an invoice late, and what does lateness cost Acme?"
  }'

The cURL request returns:

{
  "object": "compression",
  "model": "compress",
  "vendor": "scaledown",
  "compressed_prompt": "Prices are fixed for the first year and then rise with the producer price index, capped at 4% per year. Invoices are due net 30 from the issue date. Late payments accrue 1.5% interest per month after a 10-day grace period, and Northwind may pause deliveries once an invoice is 45 days overdue.\n\nLate payments accrue 1.5% interest per month after a 10-day grace period, and Northwind may pause deliveries once an invoice is 45 days overdue. Disputed line items must be raised in writing within 15 days of the invoice; undisputed amounts stay due on the original date.",
  "original_tokens": 273,
  "compressed_tokens": 131,
  "compression_ratio": 0.48,
  "usage": {"input_tokens": 273, "output_tokens": 0, "total_tokens": 273, "cost": 1.365e-05}
}

compressed_prompt holds the parts of context relevant to prompt, not the prompt itself, so send both to the next model. compression_ratio is compressed_tokens divided by original_tokens. The text can repeat sentences and change their order, so use it as model input, not as text to show a person.

Reference

Field	Notes
`model`	Required. A compression model, such as `scaledown/compress`. Gateway `@alias/...` IDs return `400 alias_not_supported`.
`context`	Required. The text to shorten.
`prompt`	Required. The question or instruction the context is being shortened for.
`rate`	`auto` (the default), or the share of tokens to remove, between 0 and 1
`vendor`	Pin the execution vendor. A mismatch returns `400 vendor_unavailable`.
`customer`	Customer UUID to scope the key, budget, and usage to

Limit or error	Value
Unknown fields, such as `stream`	`422`, rather than being ignored
Blank `context` or `prompt`, or `rate` outside 0 to 1	`422` before any vendor call
A compression model sent to another endpoint, or another model sent here	`400 unsupported_endpoint_for_model`, naming the endpoint to use
DLP match	`422 blocked_by_dlp_policy`, including for organizations in redact mode

scaledown/compress bills the original tokens as input at $0.05 per million, with no output cost, reported as usage.cost in USD. It doesn’t stream, and it isn’t available to organizations with zero data retention. GET /v1/models lists it among the ScaleDown models, paged at 50 by default, so pass limit (up to 500) when you search.

Next steps

Context compression

Shrink long chat requests automatically, with no extra call

Prompt caching

Cut the cost of a context you send again and again