Chat Completions vs Responses vs Messages: the three API shapes.

Quick answer: one industry standard, one successor, one parallel dialect.

Chat completions (POST /v1/chat/completions) is the shape almost everything speaks: a stateless messages array in, a choices array out. OpenAI shipped it in 2023, and it became the industry's lingua franca; nearly every vendor and every gateway implements it, which is what the phrase OpenAI-compatible means in practice. Responses (POST /v1/responses) is OpenAI's designated successor: a superset that adds server-side conversation state, a different item-based response structure, and built-in tools. OpenAI recommends it for new projects and keeps chat completions supported; adoption outside OpenAI is real but partial, driven by tools like Codex CLI that require it. Messages (POST /v1/messages) is Anthropic's native shape: similar in spirit to chat completions but different in load-bearing details, a required max_tokens, a top-level system field, typed content blocks, and its own streaming event vocabulary. Claude-native tooling speaks it, and multi-vendor gateways expose it alongside chat completions so Anthropic SDK code ports with a base-URL change.

The shapes side by side.

The table compresses the differences that actually change your code. Everything in it is verified against the vendors' current documentation as of July 2026.

What the differences mean in code.

The two stateless shapes look similar until you port between them. Anthropic requires max_tokens on every request where OpenAI defaults it. Anthropic hoists the system prompt out of the messages array into a top-level field and enforces strict user/assistant alternation. Tool flows differ structurally: chat completions returns tool_calls on the assistant message and takes results as role: tool messages, while Messages embeds tool_use blocks in assistant content and takes tool_result blocks inside the next user message. Streaming parsers are not reusable across them: one emits delta chunks, the other a vocabulary of named events. Responses changes a more fundamental assumption: that the client owns the transcript. With store and previous_response_id, the server can carry conversation state between turns, so the client sends only the new input. OpenAI's stated motivations are agentic: preserved reasoning context between turns for its reasoning models, better cache utilization than resending history, and built-in tools that execute server-side. The trade is coupling: a stateful integration assumes the endpoint remembers, which is exactly the property a portable multi-vendor integration cannot assume. Responses can also run stateless, sending full input each turn, and that mode is what any cross-vendor Responses compatibility converges on.

# 1) Chat completions: stateless, portable
client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "system", "content": "Be terse."},
              {"role": "user", "content": "Summarize this file."}])

# 2) Responses: server may hold the thread
client.responses.create(
    model="gpt-5.5",
    input="Summarize this file.",
    previous_response_id=prev_id)   # state lives upstream

# 3) Messages: Anthropic dialect
anthropic_client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,                # required
    system="Be terse.",             # top-level, not a role
    messages=[{"role": "user", "content": "Summarize this file."}])

Which tools speak which shape.

The portability hierarchy follows directly. Code written against stateless chat completions moves anywhere, including to Anthropic models through a gateway that translates. Code written against Messages moves across any endpoint serving that shape. Code written against stateful Responses currently moves the least, not because the shape is bad, but because server-side state is the hardest feature to replicate across vendors.

• Chat completions: the default dialect of the ecosystem. OpenAI's SDKs, LangChain, LlamaIndex, Open WebUI, LibreChat, Cline, Aider, OpenClaw's openai-completions provider type, and effectively every "bring your own endpoint" field in every tool.
• Responses: OpenAI's own newer surfaces, most prominently Codex CLI, plus frameworks adding opt-in support. Third-party serving of the shape exists (the Open Responses effort) but is far from universal; treat Responses-only tools as OpenAI-coupled unless a provider documents the endpoint.
• Messages: Claude Code, the Anthropic SDKs, and Claude-native agent tooling. OpenClaw exposes it as the anthropic-messages provider type; multi-vendor gateways serve it so this class of tools can route through them.

Pay-as-you-go · transparent per-model pricing

Selected models are priced below official list prices. Exact input, output, cache, and per-request prices are shown for each model.

What a gateway translates, exactly.

A multi-vendor gateway sits in front of models whose native dialects differ, so translation is its core competence. Concretely, when a chat-completions request names a Claude model, the gateway maps the messages array onto Anthropic's shape, hoisting the system role into the system field, converting tool definitions and tool messages into Anthropic's block structure, supplying required fields, and then maps the reply back: content blocks into choices[].message, stop_reason into finish_reason, input_tokens into prompt_tokens. Streaming gets re-encoded the same way, Anthropic's named events becoming delta chunks mid-flight. APIsRouter runs that translation behind both of its surfaces: /v1/chat/completions accepts OpenAI-shape requests for any catalog model, and /v1/messages accepts Anthropic-shape requests likewise, so both SDKs work as-is with a base URL change. The Responses shape is the moving part of the landscape; it is not part of this gateway's documented surface today, so tools that strictly require /v1/responses should stay pointed at OpenAI, and the docs page is the source of truth as that evolves. The limits of translation are worth stating plainly: a gateway can map shapes, but it cannot conjure semantics a model does not have, and vendor-exclusive parameters either pass through to the one vendor that honors them or get dropped. Well-behaved gateways document which; parameter surprises are the debugging tax of any translation layer.

Choosing a shape for new code in 2026.

Default to chat completions. It is the shape with universal serving, the one every gateway, proxy, and self-hosted runtime accepts, and the one that keeps model choice a config value. Structure the integration so base URL and model id come from configuration, and the same code addresses GPT, Claude, DeepSeek, or Gemini-family models by string. Choose Responses when you are deliberately buying OpenAI's agentic platform: server-held state, built-in tools, and reasoning-context continuity are real capabilities, and for OpenAI-committed products they are worth the coupling. Keep the rest of the stack on the portable shape so the coupling stays local. Choose Messages when your tooling is Claude-native, and route it through an endpoint that serves the shape for gateway economics without a rewrite. And if you maintain a tool others will point at their own endpoints: speak chat completions first, add the other shapes as options, which is exactly the pattern OpenClaw's provider types follow.

FAQ