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 conversation protocols §

GPT-Load accepts four conversation protocols as peers, and an AccessKey can allow several at once. Images, embeddings, reranking, decisions, and live voice have separate protocol permissions.

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; native Gemini uses /v1beta/models/…:embedContent or :batchEmbedContents.
Image generation and editing — /v1/images/generations, /v1/images/edits
Token Counting — /v1/messages/count_tokens and Gemini's countTokens.
Text reranking: POST /v1/rerank, with the independent rerank protocol. No streaming or protocol conversion.
JEV decisions: POST /v1/decisions, executed natively by Jev or OpenRouter with the independent decisions protocol.
Codex live voice uses the independent codex-live protocol; it is not another text mode of Responses WebSocket.

Gemini, New API, and GPT-Load support native gemini-embeddings. The Gemini channel can also convert text-only OpenAI Embeddings requests to native Gemini batch embeddings, supporting dimensions and float/base64 output but not token-ID input.

Codex live voice setup guide →

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.

View protocols and operations by channel →

Native search uses POST /v1/alpha/search with the openai-responses protocol on CLIProxyAPI, New API, and GPT-Load channels. It is not a chat-protocol conversion and does not imply that every upstream account supports search.

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:

Response continuation uses the original credential

For native HTTP/SSE Responses supporting upstream storage, the gateway records returned response IDs. With the same AccessKey, previous_response_id selects only the original credential if it remains eligible, regardless of soft affinity; failure never switches accounts.

Converted, stateless, and new explicitly store:false responses are not registered. Unknown, expired, or evicted IDs are rejected locally, including IDs created outside the gateway or before the upgrade. Bindings can recover only after a successful graceful-shutdown save; crash recovery is not guaranteed.

conversation and other resource operations are not guaranteed to return to the original credential. Use a single-credential Group or confirm upstream sharing. Relay channels guarantee only the same next hop.

GET /v1/responses supports native WebSocket for OpenAI, Codex, xAI, GPT-Load, CLIProxyAPI, and Sub2API. Each connection binds an upstream Session; Codex continuation is limited to the original connection. There is no WS→HTTP conversion or guaranteed context recovery after reconnect. See Runtime Settings for the toggle.

Codex WebSocket supports sending response.interrupt during generation with the response_id of the current response on the same connection. The gateway forwards it immediately on the existing upstream connection; after the interruption is acknowledged, previous_response_id can continue the conversation. Late or repeated interrupts for a finished response are ignored and do not affect the next turn. If the upstream reports the interruption as response.incomplete with no output and output_tokens of 0, the connection still closes and continuation is unavailable.

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.

Responses extension passthrough on CLIProxyAPI and New API excludes response retrieval, deletion, cancellation, input items, and Input Tokens. Ordinary previous_response_id continuations still rely on upstream storage. Inputs requiring undeclared resource capabilities are rejected locally without probing the upstream.

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 — Responses; distinguish response ID continuation from other resource references.

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