Protocols and conversion boundaries

The gateway can convert between protocols, but it is not an all-purpose translator. This page explains the boundaries and what happens when unsupported combinations occur.

Four protocols §

GPT-Load accepts four client protocols. They are independent protocols, and one AccessKey may allow multiple protocols:

OpenAI Chat Completions — The broadest compatibility; most compatible clients and third-party services use it.
OpenAI Responses — A newer API supporting stateful multi-turn continuation.
Anthropic Messages — The native endpoint for Claude clients.
Gemini — The native endpoint for Gemini clients.

OpenAI is two protocols

Chat Completions and Responses are two independent protocols, not old and new versions of one API. The OpenAI preset enables both, but each has its own endpoint and capabilities.

Protocol endpoints §

Clients use each protocol's usual endpoint; Group names are not needed in the path:

Protocol	Main entry
OpenAI Chat Completions	/v1/chat/completions
OpenAI Responses	/v1/responses and its resource path
Anthropic Messages	/v1/messages
Gemini	/v1beta/models/…

In addition to conversation, these interfaces are also provided (availability depends on upstream channels):

Model list — /v1/models and /v1beta/models.
Vector Embedding — /v1/embeddings
Image generation and editing — /v1/images/generations, /v1/images/edits
Token Counting — /v1/messages/count_tokens and Gemini's countTokens.

GET /v1/models returns an Anthropic model list when the anthropic-version header is non-empty; otherwise it returns the OpenAI Chat Completions format. Direct callers should send the header required by their client protocol.

How conversion happens §

The client protocol and upstream channel protocol are not necessarily the same. For example, when Claude Code uses Anthropic Messages with an OpenAI channel, the gateway converts the request to OpenAI format and the response back to Anthropic format.

Conversion is transparent to the client. The conversion process is visible in the request log; inspect it first for response-format issues. See Monitoring and troubleshooting.

No conversion occurs when protocols are the same, so requests pass through with minimal changes. This path provides the lowest latency and best compatibility.

Cases that cannot be converted §

It is not a universal translator

Each channel declares which protocols and capabilities it supports. The gateway converts only between declared capabilities; it does not force arbitrary protocols or JSON into another format.

Common conversion failure scenarios:

The target channel does not support this feature — For example, requesting image generation from a text-only model.
Protocol-specific parameters have no equivalents — Some parameters exist in only one protocol and may be dropped or rejected during conversion.
The model does not support this feature — For example, sending image input to a model without vision support.

For these failures, the most direct solution is to align the client protocol with the channel protocol: pair a Claude client with an Anthropic channel to reduce conversion.

Stateful requests §

OpenAI Responses can continue context through previous_response_id, conversation, or an existing resource ID. These requests have one prerequisite:

Stateful request depends on the same credential

Context exists on the upstream side and is usually bound to the credential that created it. If a request switches credentials, the upstream cannot find the previous session.
Current session affinity uses prompt prefixes and does not read previous_response_id, conversation, or any other resource ID, so it cannot provide strongly consistent routing. For reliable stateful-resource access, ensure the Group has only one credential or confirm that the upstream permits sharing a resource across credentials.

Another option is to avoid stateful interfaces and send the full context on every request. Any credential can then handle it and load is distributed more evenly, at the cost of more input tokens.

Which protocol should be used §

No protocol is universally best; choose for the use case:

Client already set. — Use the client's native protocol to minimize conversion: Anthropic for Claude Code, Gemini for Gemini CLI.
Write your own code — Chat Completions offers the broadest compatibility and makes switching upstreams easiest.
Stateful continuation required — Use Responses and enable session affinity.

An AccessKey can select multiple protocols. If unsure, enable all required protocols; unused ones have no side effects. See AccessKey.