Configuring an AI coding assistant or LLM gateway often feels like Russian roulette. Developers routinely stare at settings screens in tools like OpenCode, Cline, Cursor, or LiteLLM, blindly selecting 'Chat completions' and hoping for a 200 OK. When the connection fails with a 404 or 401, debugging becomes a game of guesswork. The root cause is rarely the API key itself, but a fundamental misunderstanding of how Base URLs and API formats interact to construct the final HTTP request.

The Core Formula: Base URL + API Format Path

Your AI client essentially acts as a two-part URL builder combined with a JSON translator. The full request URL is constructed by concatenating the Base URL with the specific API Format path. For instance, setting the Base URL to 'https://opencode.ai/zen/go/v1' and selecting 'Chat completions' results in a POST request to 'https://opencode.ai/zen/go/v1/chat/completions'. However, the API format does more than just append a path suffix; it dictates the authentication headers, the JSON request body structure, the response shape, and the Server-Sent Events (SSE) streaming schema.

Dialect #1: Chat Completions (The Universal Standard)

Introduced by OpenAI, the '/chat/completions' endpoint has become the de facto 'USB-C' of the LLM ecosystem. It is supported by cloud gateways like OpenRouter, Groq, and DeepSeek, as well as local engines like Ollama and vLLM. This protocol is stateless, requiring the client to resend the entire conversation history within a 'messages' array on every turn. Authentication uses a standard 'Authorization: Bearer ' header, and the system prompt is embedded within the messages array with the role set to 'system'. For 90% of proxies and open-weight models, this is the correct default.

Dialect #2: Anthropic Messages (Native Claude Features)

Anthropic refused to copy OpenAI’s standard, designing '/v1/messages' with stricter structural guarantees for features like Prompt Caching and Extended Thinking. Sending an OpenAI-formatted body to a native Anthropic endpoint results in an immediate rejection. This dialect requires an 'x-api-key' header and an explicit 'anthropic-version' header, rather than a Bearer token. Crucially, the system prompt moves to a top-level 'system' field, and 'max_tokens' becomes mandatoryβ€”omitting it triggers a 400 Bad Request. Tool calling also differs, using structured 'tool_use' and 'tool_result' content blocks instead of OpenAI's 'tool_calls' array.

Dialect #3: Responses (OpenAI's Agentic Protocol)

As models evolve from simple chatbots to autonomous agents like GPT-5 and Codex, the '/responses' API addresses the inefficiencies of stateless chat. It supports server-side state via 'previous_response_id', allowing conversation history to be chained without resending massive JSON arrays. The system guidance moves to a top-level 'instructions' field, and the prompt is handled via an 'input' field. While it retains Bearer authentication, it introduces first-class support for server-executed tools and structured reasoning traces. A hidden gotcha: 'previous_response_id' carries history, but 'instructions' do not automatically persist across turns, requiring manual resending for strict system rules.

Common Configuration Pitfalls

Three specific mistakes plague developers. First, the 'Double /v1 Trap' occurs when a Base URL ending in '/v1' is combined with an API format that also includes '/v1', creating a broken path like '/v1/v1/messages'. Second, a 400 Bad Request often signals a format mismatch (e.g., missing 'max_tokens' for Anthropic) rather than an invalid API key. Third, incorrect format selection breaks streaming in IDEs, causing chat panes to freeze or display raw JSON because SSE chunk schemas are incompatible across the three dialects.

Key Takeaways

  • Use Chat completions for Ollama, DeepSeek, Groq, Gemini, and OpenRouter.
  • Use Anthropic messages for direct Claude connections or native gateways to preserve caching and thinking blocks.
  • Use Responses for modern OpenAI Codex and reasoning models that require stateful agentic workflows.
  • Always verify if your Base URL includes '/v1' to avoid path duplication errors with Anthropic endpoints.

The Bottom Line

Stop treating API format selection as a guess. Understanding the distinct URL construction and JSON schemas of Chat Completions, Anthropic Messages, and Responses is the only way to eliminate configuration errors and unlock native features like server-side state and prompt caching.

Sources

https://dev.to/f0und404/stop-guessing-your-ai-client-settings-chat-completions-vs-anthropic-messages-vs-responses-api-3pi8