How does OpenRouter map an OpenAI-shaped request onto a non-OpenAI vendor's API?

## The gateway's real job Accepting an OpenAI-shaped body is easy. The work is in translating it into APIs that are not OpenAI-shaped at all, and translating the answers back so that a single client parser works everywhere. Anthropic's Messages API is the clearest example of a structurally different target, so it makes the best worked case, but the same class of transformation happens for every non-OpenAI vendor. ## Request-side transformations **System prompt placement.** OpenAI models a system prompt as a message in the array with `role: "system"`. Anthropic models it as a separate top-level parameter, outside the conversation turns. The gateway therefore extracts your system messages from `messages` and sets them where the vendor expects them. If you send several, they have to be consolidated, because the target has one slot. **Required fields.** Anthropic requires a `max_tokens` on every request; OpenAI treats it as optional. A request that omits it cannot simply be forwarded, so the gateway supplies a value. That is worth knowing operationally: if your output looks truncated on one vendor and not another with identical code, an implicit cap is the first thing to check, and setting `max_tokens` explicitly removes the ambiguity. **Content shape.** OpenAI's `content` is a string or a list of typed parts; other vendors use their own block structures for text and images. Multi-part user content gets rewritten into whatever block vocabulary the target speaks, and a model with no image support cannot receive image parts at all. **Tool calling.** This is the transformation with the most moving pieces. In the OpenAI shape you define `tools` as JSON-Schema functions, the assistant answers with `tool_calls`, each having an id, and you reply with a `role: "tool"` message carrying that `tool_call_id`. Vendors with block-structured messages instead put a tool-use block inside the assistant turn and expect the result as a tool-result block inside the next user turn, correlated by the vendor's own id. The gateway maps ids and roles in both directions so your loop stays in the OpenAI idiom. **Alternation and merging.** Some vendors are strict about turns alternating user/assistant and about the first turn being a user turn. Two consecutive user messages, or a conversation that opens with an assistant message, may have to be merged or adjusted to satisfy the target — a detail that occasionally makes a transcript reach the model slightly differently than you wrote it. ## Response-side transformations The reply is folded back into the familiar envelope: `choices[0].message` with `role` and `content`, `tool_calls` when tools were invoked, a `finish_reason`, and a `usage` object with prompt, completion and total token counts. The finish-reason mapping is the part worth memorising, because your control flow keys on it. A vendor's "model finished its turn" becomes `stop`; "hit the token cap" becomes `length`; "wants to call a tool" becomes `tool_calls`; a safety stop maps to the content-filter value. Alongside the normalised value, the gateway also exposes the upstream provider's raw stop reason, which is what you want in logs when the normalised value is too coarse to explain a behaviour. Streaming is normalised too: whatever event grammar the vendor uses upstream — and they differ substantially — comes out as OpenAI-style SSE chunks with `choices[].delta` fragments terminated by `data: [DONE]`. ## Where the translation is lossy A normaliser can only express what the common shape can express. Vendor features with no OpenAI counterpart either get an OpenRouter-specific extension field — the gateway defines a few unified extensions, such as a `reasoning` object for models that expose reasoning effort — or they are simply not reachable through the standard body. Fine-grained vendor-only controls, newly launched capabilities, and idiosyncratic response metadata are the usual casualties, and the lag between a vendor shipping a feature and a gateway exposing it is real. ## What to do with this knowledge Write code against the normalised shape, but log the raw stop reason and the served model so you can explain divergence. Set `max_tokens` explicitly instead of relying on a default you did not choose. Keep one system message rather than several, so consolidation is not making a decision for you. And when a tool loop misbehaves on one vendor only, suspect the id-and-role mapping, not your own loop, before rewriting application logic.