Why 'OpenAI compatible' is not a full integration contract across LLM APIs

One label, four protocols

A post on dev.to from XiuAI, the company behind the XiuRouter multi-model gateway, argues that the "OpenAI compatible" label is convenient shorthand yet does not amount to an integration contract. Two clients can share the same API key and base domain while sending different request paths, authentication headers, payload shapes, streaming events and tool-call formats. The gap becomes visible when coding agents, SDKs or production applications are connected to a gateway that fronts several providers.

XiuRouter itself exposes four text-generation routes: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages and Gemini GenerateContent. The article's central rule is to pick the protocol the client actually speaks, not one inferred from a model name or a compatibility badge. A model reachable through Chat Completions in one service group is not guaranteed to work through Responses, Messages or GenerateContent.

Match the route to the client

According to the article's routing guidance, Codex, agents and newer OpenAI-style applications belong on the Responses route; Claude Code and Anthropic SDKs belong on Anthropic Messages; existing OpenAI-compatible applications that lack Responses support belong on Chat Completions; and Gemini SDKs belong on GenerateContent. Where client documentation is unclear, the author recommends inspecting the client's official configuration guide or its request logs rather than trusting a generic compatibility badge.

Base URL pitfalls

A frequent misconfiguration involves how clients construct URLs. OpenAI-compatible SDKs typically append /v1 themselves, so the configured base URL must include it. A Claude client that appends /v1/messages, or a Gemini client that appends /v1beta/models/..., should instead be given the bare API root. Mixing the conventions produces duplicated paths such as /v1/v1/messages, which the article links to configuration fields labelled "API URL" without stating whether they expect a domain, a base path or a complete endpoint.

For direct requests, the four paths are POST /v1/chat/completions, POST /v1/responses, POST /v1/messages and POST /v1beta/models/{model}:generateContent.

Authentication differs per protocol

Authentication is also protocol-specific. OpenAI-compatible requests use an Authorization: Bearer header. Anthropic Messages uses x-api-key together with an anthropic-version header, and XiuRouter also accepts a Bearer token on that route for gateway clients such as Claude Code. Gemini accepts x-goog-api-key and the key query parameter, though the article prefers headers because query-string keys can end up in access logs and copied URLs.

Verify the exact production combination

Before shifting application traffic, the article recommends a single small request through the exact combination of API key, model ID, service group, protocol, streaming mode and whichever tool or structured-output features are needed. First list the models visible to the scoped key, then send a minimal request through the intended route, then confirm the result in usage records: key, model, service group, endpoint, token counts, status and cost. The test itself is billable, so current pricing should be checked first.

Known compatibility boundaries

A gateway route can support core text handling without implementing every provider feature. XiuRouter's stated boundaries include no dedicated /v1/messages/count_tokens route (Claude Code treats token counting as optional and can fall back to inference, but the end-to-end task still needs verifying). The Responses route is stateless, so stored conversations, previous_response_id, background mode and provider-hosted tools are out of scope. The gateway exposes Gemini GenerateContent rather than the Gemini Interactions API, and files, fine-tuning, image variations and some legacy endpoints are not implemented. Tool calls, structured output, prompt caching, streaming events and token accounting can also change when an inbound request is converted to an upstream provider's format.

Safer migrations with scoped keys

The article advises one key per application or environment, limited by model, service group, quota, expiration and IP scope. For migration, keep the incumbent provider configured, add the gateway as a separate provider or environment, test a small non-critical task, compare output, streaming, tool calls, token accounting, latency and cost, then move traffic gradually while retaining the previous provider as a rollback path.

Why it matters

Most teams treat "OpenAI compatible" as a checkbox, and this piece is a practical catalogue of where that assumption fails: request paths, auth headers, statefulness, token counting and tool-call conversion. As multi-model gateways increasingly sit between coding agents and providers, mismatches surface as broken retries, unfinished agent tasks or usage records that disagree with client expectations. The lesson generalises beyond XiuRouter: identify the protocol your client actually sends, test it on the exact combination destined for production, and never treat a base-URL change as proof of full compatibility.