Skip to content
LLM Router
Gateway API

OpenAI Chat Completion

Create chat completions using the OpenAI Chat Completion API format

POST/v1/chat/completions

Creates a completion for the chat message. The Edgee API is OpenAI-compatible and works with any model and provider. Supports both streaming and non-streaming responses.

Create a chat completion, optionally streamed as SSE. 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.

POSThttps://edgee.io/v1/chat/completions

Try this endpoint

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

Comma-separated analytics tags. Trimmed and merged with body tags.

Enable debug capture for this request. Does not add a debug object to the API response.

Turn tool-result trimming on or off. Overrides the API key setting for this request only. Values are case-insensitive, and a missing or invalid value keeps the key's setting.

Turn MCP tool surface reduction on or off. The threshold and resolver mode still come from the API key. Overrides the API key setting for this request only. Values are case-insensitive, and a missing or invalid value keeps the key's setting.

Turn output brevity on or off. Overrides the API key setting for this request only. Values are case-insensitive, and a missing or invalid value keeps the key's setting.

Session identifier used to group request usage.

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/chat/completions' \
  --header "Authorization: Bearer $EDGEE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "model": "openai/gpt-5.2",
  "messages": [
    {
      "role": "user",
      "content": "Hello!"
    }
  ],
  "max_completion_tokens": 256
}'
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>.

Parameters

X-Edgee-Tagsheader · string

Comma-separated analytics tags. Trimmed and merged with body tags.

X-Edgee-Debugheader · string

Enable debug capture for this request. Does not add a debug object to the API response.

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

Turn tool-result trimming on or off. Overrides the API key setting for this request only. Values are case-insensitive, and a missing or invalid value keeps the key's setting.

X-Edgee-Compression-Tool-Surface-Reductionheader · string

Turn MCP tool surface reduction on or off. The threshold and resolver mode still come from the API key. Overrides the API key setting for this request only. Values are case-insensitive, and a missing or invalid value keeps the key's setting.

X-Edgee-Compression-Brevityheader · string

Turn output brevity on or off. Overrides the API key setting for this request only. Values are case-insensitive, and a missing or invalid value keeps the key's setting.

X-Edgee-Session-Idheader · string

Session identifier used to group request usage.

Request body

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
Show schema
thought_signaturestring

Opaque provider thought signature to preserve when replaying tool calls.

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.

{
  "model": "openai/gpt-5.2",
  "messages": [
    {
      "role": "user",
      "content": "Hello!"
    }
  ],
  "max_completion_tokens": 256
}

Responses

200Chat completion created successfully

application/json

idstringrequired

A unique identifier for the chat completion.

objectstringrequired

The object type, which is always `chat.completion`.

Values: chat.completion
createdintegerrequired

The Unix timestamp (in seconds) of when the chat completion was created.

modelstringrequired

The model used for the chat completion.

choicesarrayrequired

Model completion choices. Number of choices depends on the provider and dispatch path.

Show schema
indexintegerrequired

The index of the choice in the list of choices.

messageobjectrequired
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.

finish_reasonstring

The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence, `length` if the maximum number of tokens specified in the request was reached, `content_filter` if content was omitted due to a flag from our content filters, or `tool_calls` if the model called a tool.

Values: stop, length, content_filter, tool_calls
usageobjectrequired

Usage on shared converted Chat responses. Native responses preserve the provider’s usage representation, which may use prompt_tokens_details/completion_tokens_details rather than these Gateway detail fields.

Show schema
prompt_tokensintegerrequired

Number of tokens in the prompt.

completion_tokensintegerrequired

Number of tokens in the generated completion.

total_tokensintegerrequired

Total number of tokens used in the request (prompt + completion).

input_tokens_detailsobject

Additional details about input tokens.

Show schema
cached_tokensinteger

Number of cached tokens read from the prompt cache.

cache_creation_tokensinteger

Number of tokens written to the prompt cache (Anthropic-style cache creation).

cache_creation_5m_tokensinteger

Cache-write tokens for this TTL, omitted when zero.

cache_creation_1h_tokensinteger

Cache-write tokens for this TTL, omitted when zero.

output_tokens_detailsobject

Additional details about output tokens.

Show schema
reasoning_tokensinteger

Number of reasoning tokens in the output.

compressionobject

Token compression metrics. Present in the response when token compression was applied to the request. The `usage.prompt_tokens` field reflects the compressed token count actually billed by the provider.

Show schema
saved_tokensintegerrequired

Estimated saved input tokens, calibrated to the provider token count from the ratio of local counts before and after compression.

cost_savingsintegerrequired

Estimated savings in nanodollars. Divide by 1,000,000,000 to convert to USD: 27,000,000 nanodollars = $0.027.

reductionnumberrequired

Percentage reduction: 100 × estimated saved tokens / estimated pre-compression tokens, calibrated to provider usage.

time_msintegerrequired

Time taken to perform compression, in milliseconds.

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "openai/gpt-5.2",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I assist you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 10,
    "total_tokens": 20,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens_details": {
      "reasoning_tokens": 0
    }
  },
  "compression": {
    "saved_tokens": 450,
    "cost_savings": 27000,
    "reduction": 48.99884991374353,
    "time_ms": 12
  }
}

text/event-stream

Server-Sent Events stream. Each event is a JSON object prefixed with 'data: ' and followed by two newlines. The stream consists of multiple `ChatCompletionChunk` objects, and optionally a final chunk with usage statistics if `stream_options.include_usage` is true.

string
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.

403Key inactive, expired, model restriction or other permission failure.

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.

429Usage or routing-strategy budget exhausted, or provider rate limit.

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.

502Upstream provider failure.

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.

503Usage accounting or upstream service temporarily unavailable.

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.

529Upstream provider overloaded (when preserved by the request path).

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