Skip to content
LLM Router
Gateway API

Compress

Compress a request payload without calling any LLM provider

POST/v1/compress

Compresses an LLM request payload and returns it with the messages, input, system, and tools fields replaced by their compressed versions. No LLM call is made — this is a pure pre-processing step.

Intended for teams running their own LLM gateways (Oracle, Vercel, Cloudflare) who want Edgee token compression without routing requests through Edgee.

To select Anthropic Messages parsing, include a top-level system field (an empty string is sufficient). Otherwise, a payload with input uses Responses parsing, and other payloads use Chat Completions parsing.

The returned compression.compression_rate is the fraction of tokens remaining: 0.81 means 19% saved. These are local tokenizer counts, not provider billing measurements.

Tool-result trimming is enabled by default on this endpoint. Set x-edgee-compression-tool-result-trimming: false to return the original payload without added compression metadata. 0 and off also disable trimming; values are case-insensitive. An omitted or invalid value leaves trimming enabled.

Compresses an LLM request payload and returns it with the `messages`, `input`, `system`, and `tools` fields replaced by their compressed versions. Accepts OpenAI Chat Completions, Anthropic Messages, and OpenAI Responses API formats — the wire format is auto-detected from the request body. No LLM provider is called. This is a pure pre-processing step intended for teams running their own LLM gateways who want Edgee token compression without routing requests through Edgee.

POSThttps://edgee.io/v1/compress

Try this endpoint

Configure your request, then run the curl command in your terminal or send it from this page.

Tool-result trimming is on by default on this endpoint. Set to `false`, `0` or `off` to get the payload back unchanged, without the `compression` field. Values are case-insensitive, and an invalid value leaves trimming on.

Run in your terminal

Set EDGEE_API_KEY to your Gateway API key in your terminal, then copy and run this command. Gateway requests may consume credits.

curl
curl --include --no-buffer --globoff --request POST 'https://edgee.io/v1/compress' \
  --header "Authorization: Bearer $EDGEE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "model": "openai/gpt-5.2",
  "messages": [
    {
      "role": "user",
      "content": "Hello!"
    }
  ]
}'
Send from browser

Your request is relayed through the Edgee documentation server to the Gateway. Your key is used only for this request and is not stored.

Authentication

Use an Edgee Gateway API key. Send it as Authorization: Bearer <key> or x-api-key: <key>.

Parameters

X-Edgee-Compression-Tool-Result-Trimmingheader · string

Tool-result trimming is on by default on this endpoint. Set to `false`, `0` or `off` to get the payload back unchanged, without the `compression` field. Values are case-insensitive, and an invalid value leaves trimming on.

Request body

An LLM request payload to compress. Accepts any of three wire formats — the format is auto-detected from the request body: a top-level `"system"` key indicates Anthropic Messages format; a top-level `"input"` key indicates OpenAI Responses API format; otherwise, OpenAI Chat Completions format is assumed. Include a top-level system field (even an empty string) to select Anthropic parsing when compressing a Messages payload. Format conversion can normalize message/tool content; other top-level fields are retained.

Option 1

Native dispatch preserves provider-specific JSON fields when the destination supports the caller’s format. Cross-format routing converts through the Gateway’s shared representation: provider-only features are not guaranteed to survive. Support for reasoning, images, built-in tools and structured outputs depends on the destination model.

modelstringrequired

Model identifier from GET /v1/models, in author/model format, or a configured global alias. Append :provider to request a specific provider route. Available models and providers depend on your key and organization policies.

messagesarrayrequired

A list of messages comprising the conversation so far. The shared typed converter also accepts input as an alias, but messages is the portable Chat Completions field for native providers.

Show schema
rolestringrequired

The role of the message author. Required properties vary by role: - `system`, `user`, `developer`: requires `content` - `assistant`: `content` is optional (can be empty if `tool_calls` is present) - `tool`: requires `content` and `tool_call_id`

Values: system, user, assistant, tool, developer
contentunion

Text or multimodal parts. Required for system, developer, user and tool turns; nullable/optional for assistant tool calls.

Show schema
Option 1
string
Option 2
Option 1
typestringrequired
Values: text
textstringrequired
cache_controlobject
Option 2
typestringrequired
Values: image_url
image_urlobjectrequired
Option 3
typestringrequired
Values: input_image
image_urlstringrequired
detailstring
Option 4
typestringrequired
Values: image
sourceunionrequired
Option 5

Provider-native content such as audio; not guaranteed to survive cross-format conversion.

object
namestring

An optional name for the participant. Provides the model information to differentiate between participants of the same role. Used for `system`, `user`, `assistant`, and `developer` roles.

tool_call_idstring

Required for tool messages; matches an assistant tool call ID.

refusalstring

The refusal message from the model, if any. Used for `assistant` role only.

tool_callsarray

The tool calls made by the assistant. Used for `assistant` role only.

Show schema
idstringrequired

The ID of the tool call.

typestringrequired

The type of the tool call.

Values: function
functionobjectrequired
Show schema
namestringrequired

The name of the function to call.

argumentsstringrequired

The arguments to call the function with, as JSON.

extra_contentobject
Show schema
googleobject
cache_controlobject

Anthropic cache breakpoint metadata when translating supported system, user or tool content. Cache behavior depends on the destination provider.

reasoning_contentstring

Reasoning text from the provider, when exposed by the requested reasoning policy.

max_tokensinteger

The maximum number of tokens that can be generated in the chat completion.

streamboolean

If set, partial message deltas will be sent, as in OpenAI. Streamed chunks are sent as Server-Sent Events (SSE).

Default: false
stream_optionsobject

Options for streaming response.

Show schema
include_usageboolean

Request usage in the final usage chunk before the [DONE] sentinel. It does not add a second [DONE] event.

toolsarray

Function tools and provider-specific tools. Native paths preserve provider tool types; cross-format conversion supports only representable tool semantics.

Show schema

Standard function tool. Provider-native tool objects are also accepted by native Chat-compatible dispatch.

typestringrequired

Discriminator for the standard function tool variant.

Values: function
functionobjectrequired
Show schema
namestringrequired

The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.

descriptionstring

A description of what the function does, used by the model to choose when and how to call the function.

parametersobject

The parameters the functions accepts, described as a JSON Schema object. See the guide for examples, and the JSON Schema reference for documentation about the format.

tool_choiceunion

Tool selection. required/any request tool use; support for none and forced functions depends on provider and conversion path.

Show schema
Option 1

none declines tools; auto lets the model choose; required/any requests tool use. Provider support varies.

none | auto | required | anystring
Option 2

Object form of a tool selection mode.

typestringrequired
Values: auto, none, any, required
Option 3
typestringrequired

The type of the tool.

Values: function
functionobjectrequired
Show schema
namestringrequired

The name of the function to call.

tagsarray

Optional tags to categorize and label the request. Useful for filtering and grouping requests in analytics and logs. Can also be sent via the `x-edgee-tags` header as a comma-separated string.

Show schema
string
enable_debugboolean

Enable request debug capture. Gateway-only field; does not add debug information to the response.

max_completion_tokensinteger

Alias of max_tokens. Use one spelling, not both.

temperaturenumber

Sampling temperature; supported range depends on the destination model.

top_pnumber

Nucleus sampling probability; support depends on the destination model.

reasoning_effortstring

Requested effort; common values include none, minimal, low, medium, high, xhigh and max. The supported vocabulary is model-specific. Cross-format routing maps supported values and can omit unrepresentable levels.

reasoning_summarystring

Gateway reasoning-display override. Common values: auto, concise, detailed. For Chat Completions, positive reasoning effort normally exposes reasoning_content unless overridden.

reasoning_enabledboolean

Gateway override for reasoning intent on cross-format requests; false explicitly declines reasoning.

reasoning_budget_tokensinteger

Legacy Anthropic thinking budget, used only when translating to a compatible destination.

Option 2

Native dispatch preserves provider-specific JSON fields when the destination supports the caller’s format. Cross-format routing converts through the Gateway’s shared representation: provider-only features are not guaranteed to survive. Support for reasoning, images, built-in tools and structured outputs depends on the destination model.

modelstringrequired

Model identifier from GET /v1/models, in author/model format, or a configured global alias. Append :provider to request a specific provider route. Available models and providers depend on your key and organization policies.

max_tokensintegerrequired

Maximum number of tokens to generate

messagesarrayrequired

Array of message objects

Show schema
rolestringrequired

The role of the message

Values: user, assistant
contentunionrequired
Show schema
Option 1

Simple text content

string
Option 2

Array of content blocks

Common Anthropic content blocks. Native dispatch can carry additional provider-specific blocks; conversion paths only preserve supported content. Cross-provider reasoning is emitted as text, never as forged signed thinking blocks.

Option 1
typestringrequired
Values: text
textstringrequired
cache_controlobject
Option 2
typestringrequired
Values: tool_use
idstringrequired
namestringrequired
inputobjectrequired
Option 3
typestringrequired
Values: tool_result
tool_use_idstringrequired
contentunionrequired
is_errorboolean
Default: false
cache_controlobject
Option 4
typestringrequired
Values: image
sourceunionrequired
cache_controlobject
Option 5
typestringrequired
Values: thinking
thinkingstringrequired
signaturestring

Preserve provider-issued signatures when replaying history. Unsigned thinking blocks are stripped before upstream Anthropic calls.

Option 6
typestringrequired
Values: redacted_thinking
datastringrequired
systemunion
Show schema
Option 1

System prompt as a string

string
Option 2

System prompt as content blocks

Common Anthropic content blocks. Native dispatch can carry additional provider-specific blocks; conversion paths only preserve supported content. Cross-provider reasoning is emitted as text, never as forged signed thinking blocks.

Option 1
typestringrequired
Values: text
textstringrequired
cache_controlobject
Show schema
typestringrequired
Values: ephemeral
ttlstring
Values: 5m, 1h
Option 2
typestringrequired
Values: tool_use
idstringrequired
namestringrequired
inputobjectrequired
Option 3
typestringrequired
Values: tool_result
tool_use_idstringrequired
contentunionrequired
Show schema
Option 1
string
Option 2
Option 1
typestringrequired
Values: text
textstringrequired
cache_controlobject
Option 2
typestringrequired
Values: image
sourceunionrequired
is_errorboolean
Default: false
cache_controlobject
Show schema
typestringrequired
Values: ephemeral
ttlstring
Values: 5m, 1h
Option 4
typestringrequired
Values: image
sourceunionrequired
Show schema
Option 1
typestringrequired
Values: url
urlstringrequired
Option 2
typestringrequired
Values: base64
media_typestringrequired
datastringrequired
cache_controlobject
Show schema
typestringrequired
Values: ephemeral
ttlstring
Values: 5m, 1h
Option 5
typestringrequired
Values: thinking
thinkingstringrequired
signaturestring

Preserve provider-issued signatures when replaying history. Unsigned thinking blocks are stripped before upstream Anthropic calls.

Option 6
typestringrequired
Values: redacted_thinking
datastringrequired
streamboolean

Enable streaming responses

Default: false
toolsarray

Tool definitions

Show schema
namestringrequired

The name of the tool

descriptionstring

Description of what the tool does

input_schemaobject

JSON Schema describing the tool's input parameters

Default: {"type":"object","properties":{}}
cache_controlobject
Show schema
typestringrequired
Values: ephemeral
ttlstring
Values: 5m, 1h
tool_choiceobject
Show schema
Option 1
typestringrequired

Model decides whether to use tools

Values: auto
Option 2
typestringrequired

Model must use one of the provided tools

Values: any
Option 3
typestringrequired
Values: tool
namestringrequired

Name of the specific tool to use

enable_debugboolean

Enable request debug capture. Gateway-only field; does not add debug information to the response.

tagsarray

Optional tags to categorize and label the request. Useful for filtering and grouping requests in analytics and logs. Can also be sent via the `x-edgee-tags` header as a comma-separated string.

Show schema
string
temperaturenumber
top_pnumber
thinkingobject
Show schema
typestringrequired

adaptive, disabled, or legacy enabled; supported modes depend on the model.

displaystring

summarized or omitted. Default display depends on the model.

budget_tokensinteger

Required for legacy enabled thinking; adaptive models do not use this budget.

output_configobject

Only effort is portable through the shared representation. Other fields such as format and task_budget are provider-native and are not preserved by every cross-format path.

Show schema
effortstring

Requested effort; common values include none, minimal, low, medium, high, xhigh and max. The supported vocabulary is model-specific. Cross-format routing maps supported values and can omit unrepresentable levels.

Option 3

Native dispatch preserves provider-specific JSON fields when the destination supports the caller’s format. Cross-format routing converts through the Gateway’s shared representation: provider-only features are not guaranteed to survive. Support for reasoning, images, built-in tools and structured outputs depends on the destination model.

modelstringrequired

Model identifier from GET /v1/models, in author/model format, or a configured global alias. Append :provider to request a specific provider route. Available models and providers depend on your key and organization policies.

inputunionrequired

The input to the model. Either a plain string (treated as a single user message) or a flat array of typed input items (messages, function calls, function call outputs).

Show schema
Option 1
string
Option 2

Typed input items understood by the shared converter. additional_tools supplies inline tool declarations. Native Responses accepts further item types. On cross-format conversion unrecognized items (including replayed reasoning/computer items) are skipped; do not assume provider-only conversation state is portable.

Option 1
rolestringrequired

The role of the message author.

Values: user, assistant, system, developer
contentunion

Message content. Either a plain string or an array of typed content parts.

Show schema
Option 1
string
Option 2
Option 1
typestringrequired
Values: input_text
textstringrequired
Option 2
typestringrequired
Values: output_text
textstringrequired
Option 3
typestringrequired
Values: text
textstringrequired
Option 4
typestringrequired
Values: input_image
image_urlstringrequired

Image URL or data URL.

detailstring
Option 5
typestringrequired
Values: image_url
image_urlobjectrequired
Option 6

Provider-native parts are not portable across all formats.

object
Option 2
typestringrequired
Values: function_call
call_idstringrequired

Identifier linking this call to its `function_call_output`.

namestringrequired

Name of the function the assistant is calling.

argumentsstring

Arguments passed to the function, encoded as a JSON string.

Default: "{}"
Option 3
typestringrequired
Values: function_call_output
call_idstringrequired

Identifier matching the `function_call` item this is responding to.

outputunionrequired

Tool result as text or multimodal content parts.

Show schema
Option 1
string
Option 2
Option 1
typestringrequired
Values: input_text
textstringrequired
Option 2
typestringrequired
Values: output_text
textstringrequired
Option 3
typestringrequired
Values: text
textstringrequired
Option 4
typestringrequired
Values: input_image
image_urlstringrequired

Image URL or data URL.

detailstring
Option 5
typestringrequired
Values: image_url
image_urlobjectrequired
Option 6

Provider-native parts are not portable across all formats.

object
Option 4
typestringrequired
Values: additional_tools
rolestring
Values: developer
toolsarray
Show schema

Function, freeform and namespaced tools are understood by the converter. Namespaces are flattened for dispatch and restored on returned function calls. Other provider-native types can pass through natively but are dropped during typed conversion.

Option 1
typestringrequired
Values: function
namestringrequired
descriptionstring
parametersobject
Option 2
typestringrequired
Values: custom
namestringrequired
descriptionstring
formatobject

Native grammar constraint. Cross-format conversion uses an input string parameter and does not enforce the grammar.

Option 3
typestringrequired
Values: namespace
namestringrequired
toolsarray
instructionsstring

System-level instruction prepended to the conversation. An alternative to including a `system` role message in the `input` array.

streamboolean

If set, the response is streamed as Server-Sent Events (SSE).

Default: false
max_output_tokensinteger

Maximum number of tokens to generate.

toolsarray

Tools available to the model. Uses the Responses API flat format (no nested `function` key).

Show schema

Function, freeform and namespaced tools are understood by the converter. Namespaces are flattened for dispatch and restored on returned function calls. Other provider-native types can pass through natively but are dropped during typed conversion.

Option 1
typestringrequired
Values: function
namestringrequired
descriptionstring
parametersobject
Option 2
typestringrequired
Values: custom
namestringrequired
descriptionstring
formatobject

Native grammar constraint. Cross-format conversion uses an input string parameter and does not enforce the grammar.

Option 3
typestringrequired
Values: namespace
namestringrequired
toolsarray
Show schema

Function, freeform and namespaced tools are understood by the converter. Namespaces are flattened for dispatch and restored on returned function calls. Other provider-native types can pass through natively but are dropped during typed conversion.

Option 1
typestringrequired
Values: function
namestringrequired
descriptionstring
parametersobject
Option 2
typestringrequired
Values: custom
namestringrequired
descriptionstring
formatobject

Native grammar constraint. Cross-format conversion uses an input string parameter and does not enforce the grammar.

Option 3
typestringrequired
Values: namespace
namestringrequired
toolsarray
tool_choiceunion

Tool selection on native Responses paths. Cross-format conversion supports modes and the shared nested function form; flat forced-function names are not preserved on every conversion path.

Show schema
Option 1

Bare-string mode. `auto` lets the model decide; `none` forbids tool calls.

auto | none | required | anystring
Option 2

Object form of a tool selection mode.

typestringrequired
Values: auto, none, any, required
Option 3

Native Responses forced-function form. The shared typed tool-choice representation uses {type:function,function:{name:...}}; the flat name is not preserved on every cross-format path.

typestringrequired
Values: function
namestringrequired

Name of the function to call.

temperaturenumber

Sampling temperature. Range and support depend on the destination model.

top_pnumber

Nucleus sampling probability. Alternative to temperature.

tagsarray

Optional tags to categorize and label the request. Useful for filtering and grouping requests in analytics and logs. Can also be sent via the `x-edgee-tags` header as a comma-separated string.

Show schema
string
enable_debugboolean

Enable request debug capture. Gateway-only field; does not add debug information to the response.

reasoningobject
Show schema
effortstring

Requested effort; common values include none, minimal, low, medium, high, xhigh and max. The supported vocabulary is model-specific. Cross-format routing maps supported values and can omit unrepresentable levels.

summarystring

Requested reasoning display: auto, concise or detailed. May be omitted on destinations that cannot represent it.

Responses

200Request compressed successfully. The response mirrors the input format with the `messages`, `input`, `system`, and `tools` fields replaced by their compressed versions. All other fields pass through unchanged. A `compression` metadata object is appended when trimming runs. When the tool-result-trimming header disables compression, the original payload is returned without added compression metadata.

application/json

The original request payload with compressed content fields replaced. All fields not touched by compression (`model`, `temperature`, `top_p`, `stop_sequences`, etc.) pass through unchanged. A `compression` object is appended when tool-result trimming runs. When trimming is disabled by the request header, the original payload is returned without added compression metadata.

compressionobject

Token compression metrics appended when `/v1/compress` runs tool-result trimming.

Show schema
techniquestringrequired

The compression technique applied. Always `tool` (tool-result trimming).

Values: tool
applied_strategiesarrayrequired

Names of the compression strategies that were applied to the request.

Show schema
string
compression_ratenumberrequired

Remaining token ratio: compressed_input_tokens / uncompressed_input_tokens. 0.81 means 19% saved; 1 means no reduction (also used for empty input).

uncompressed_input_tokensintegerrequired

Token count of the original, uncompressed input.

compressed_input_tokensintegerrequired

Local token count after compression. No provider is called and this count is not a provider billing measurement.

compression_time_msintegerrequired

Wall-clock time taken to perform compression, in milliseconds.

errorstring

Human-readable error message if compression partially failed. Present only when an error occurred during compression.

tool_statsobject

Per-tool compression statistics. Present only when `tool_result_trimming` was applied.

{
  "model": "openai/gpt-5.2",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "What is the capital of France?"
    },
    {
      "role": "assistant",
      "content": "Paris."
    },
    {
      "role": "tool",
      "tool_call_id": "call_abc",
      "content": "<trimmed>"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string"
            }
          }
        }
      }
    }
  ],
  "compression": {
    "technique": "tool",
    "applied_strategies": [
      "tool_result_trimming"
    ],
    "compression_rate": 0.81,
    "uncompressed_input_tokens": 1000,
    "compressed_input_tokens": 810,
    "compression_time_ms": 12
  }
}
400Malformed request, invalid/disabled model or provider, or unsupported conversion.

application/json

OpenAI-shaped Gateway error. Native upstream errors can retain provider-specific details.

errorobjectrequired
Show schema
messagestringrequired

A human-readable error message.

typestringrequired

High-level error category.

codestring

Machine-readable error code, for example unauthorized, invalid_json, bad_model_id, model_disabled, provider_disabled, usage_limit_exceeded, usage_unavailable, provider_error or internal_error. Not an exhaustive enum.

paramstring

Name of the request parameter that caused the error, when applicable.

401Missing or invalid API credentials.

application/json

OpenAI-shaped Gateway error. Native upstream errors can retain provider-specific details.

errorobjectrequired
Show schema
messagestringrequired

A human-readable error message.

typestringrequired

High-level error category.

codestring

Machine-readable error code, for example unauthorized, invalid_json, bad_model_id, model_disabled, provider_disabled, usage_limit_exceeded, usage_unavailable, provider_error or internal_error. Not an exhaustive enum.

paramstring

Name of the request parameter that caused the error, when applicable.

500Internal processing error.

application/json

OpenAI-shaped Gateway error. Native upstream errors can retain provider-specific details.

errorobjectrequired
Show schema
messagestringrequired

A human-readable error message.

typestringrequired

High-level error category.

codestring

Machine-readable error code, for example unauthorized, invalid_json, bad_model_id, model_disabled, provider_disabled, usage_limit_exceeded, usage_unavailable, provider_error or internal_error. Not an exhaustive enum.

paramstring

Name of the request parameter that caused the error, when applicable.

Download the OpenAPI specification