Protocols and conversion boundaries

Four conversation protocols §

GPT-Load accepts four chat protocols. They are peers, and an AccessKey can allow several at once. Images, embeddings, reranking, decisions, speech synthesis, 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.

Protocol endpoints §

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

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.
• Speech synthesis: POST /v1/audio/speech uses the separate audio-speech protocol. Only native, non-streaming requests are supported; there is no protocol conversion.
• Codex live voice uses the independent codex-live protocol; it is not another text mode of Responses WebSocket.

Speech synthesis currently supports only OpenRouter and Mistral. Requests must be JSON with a model field; voice, voice_id, response_format, and other parameters follow the selected channel. OpenRouter can return audio bytes, while Mistral can return JSON containing audio_data. Clients should handle the response according to its actual Content-Type.

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 §

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.

Requests with Anthropic advisor tools require a native route. For advisor model availability, access restrictions, and pricing, see Model management.

Stateful requests §

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

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 send complete readable context each time, reducing dependence on storage in the original account. Encrypted history and item IDs may still be bound to that account, so continuation with any credential is not guaranteed, and input token usage may increase.

Before sending output to the client, HTTP/SSE and WebSocket Responses can attempt one cleanup replay on the same credential if upstream explicitly rejects encrypted history or history item IDs. For WebSocket, this is limited to the first turn on a new connection. The replay counts against retry_count and obeys error rules and credential cooldowns. No replay is made after content or tool activity; compaction and item_reference are not removed automatically.

If the same rejection persists after cleanup and replay, HTTP returns 400 encrypted_content_recovery_exhausted. Resend complete readable history or start a new conversation. If a bound upstream WebSocket connection becomes invalid, the client must still reconnect and resend.

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.