OpenAI-Compatible vs Anthropic-Compatible APIs: Developer Migration Guide

OpenAI-compatible and Anthropic-compatible APIs solve the same basic problem—send messages to a model and receive generated content—but they are not interchangeable contracts. Authentication is easy to adapt. The harder differences appear in system instructions, content blocks, tool loops, streaming events, reasoning state, structured output, errors, and usage accounting.

This OpenAI vs Anthropic API migration guide maps those differences for AI developers and explains when a compatibility endpoint is enough and when a native adapter is safer.

This article was reviewed against current OpenAI and Anthropic documentation on August 26, 2026. Exact fields vary by endpoint, model, and SDK version.

OpenAI vs Anthropic API: quick comparison

Concern	OpenAI-style API	Anthropic Messages API
Authentication	Authorization: Bearer ...	x-api-key plus version header
System instruction	Message role or endpoint-specific instruction	Top-level system
Response body	Choices or Responses output items	Typed content blocks
Tool request	Function or tool call item	tool_use content block
Tool result	Tool-role message or tool output item	tool_result content block
Streaming	Endpoint-specific SSE events or deltas	Message/content-block lifecycle events
Structured output	Endpoint/model-specific JSON or schema features	Use native capabilities and validation; compatibility support differs

The safest architecture defines a small internal request and response contract, then implements provider adapters. Do not expose every provider parameter through product code.

OpenAI has more than one current contract

“OpenAI-compatible” often means Chat Completions because many SDKs support its messages shape. OpenAI also provides the Responses API, whose items, tools, and streaming semantics are not identical. Record which contract a gateway implements instead of labeling both simply “OpenAI API.”

type ApiDialect =
  | "openai-chat-completions"
  | "openai-responses"
  | "anthropic-messages";

System and message conversion

A converter must preserve instruction priority. Anthropic’s OpenAI SDK compatibility layer documents that system and developer messages are hoisted and concatenated into one initial system message. That can change behavior when an application interleaves instructions later in a conversation.

Define one immutable system contract at the start of your normalized request. If your product depends on multiple priority levels, write explicit tests; do not assume a compatibility layer preserves them exactly.

Content blocks and multimodal input

Anthropic responses are arrays of typed content blocks. OpenAI Chat Completions commonly exposes assistant message content and tool calls, while Responses uses output items. A normalized response should preserve the type instead of flattening everything into one string.

type NormalizedContent =
  | { type: "text"; text: string }
  | { type: "tool_call"; id: string; name: string; arguments: unknown }
  | { type: "reasoning"; data: unknown }
  | { type: "refusal"; message: string };

Validate image, file, audio, and document support per route. A client library may accept a content type that a compatibility endpoint ignores or rejects.

Tool calling requires a state machine

Normalized step	Required data
Model requests tool	Tool call ID, name, validated arguments
Application authorizes	Policy result, user approval if required
Tool executes	Operation ID, result, error, side-effect status
Result returns to model	Original call ID and typed tool result
Model completes	Visible answer, finish reason, resolved model

Do not translate only field names. Preserve call IDs, ordering, parallel-call behavior, error results, and any reasoning state the route requires. Enforce tool schemas in your application even if an API claims strict tool arguments.

Streaming events are not portable text chunks

Both ecosystems use server-sent events, but their event types and assembly rules differ. Anthropic emits message and content-block lifecycle events. OpenAI event shapes depend on Chat Completions or Responses.

Build each provider parser into the same application events:

response.started
text.delta
tool_call.started
tool_call.arguments.delta
usage.updated
response.completed
response.failed

Test a disconnect in the middle of text and tool arguments. Never execute a tool from incomplete streamed JSON.

Compatibility endpoints have deliberate limits

Anthropic’s official OpenAI SDK compatibility page says the layer is mainly for testing and comparison, and recommends the native Claude API for full features in most long-term production use. Its documented limits include ignored strict tool settings, unsupported prompt caching through the compatibility layer, a single completion, and transformed system/developer messages. Some unsupported fields can be ignored rather than rejected.

This leads to a simple rule: a compatibility endpoint is excellent for a fast proof of concept and common chat flows. Use native adapters when the product depends on provider-specific reasoning, caching, files, advanced tools, precise structured output, or long-lived agent state.

Normalize errors without erasing them

Normalized class	Examples	Action
invalid_request	400 or unsupported parameter	Fix request; no fallback loop
authentication	401	Stop and rotate/correct key
permission	403	Review route and policy
rate_limited	429	Honor Retry-After and inspect quota type
temporary_upstream	5xx, Anthropic 529, network timeout	Bounded retry, then approved failover
stream_interrupted	Error after initial 200	Invalidate partial structured output

Preserve raw provider status, error type, request ID, and headers alongside the normalized class. Support teams need the original evidence.

Usage and cost normalization

Store input, cached input where reported, output, and reasoning-related usage without assuming every provider counts the same way. Compare the amount billed by the route, not just locally estimated tokens.

type NormalizedUsage = {
  inputTokens?: number;
  cachedInputTokens?: number;
  outputTokens?: number;
  totalTokens?: number;
  billedAmount?: number;
  currency?: string;
  raw: unknown;
};

Migration sequence

1. Inventory every field, tool, content type, and stream event in use.
2. Define the smallest normalized contract your product needs.
3. Write native adapters and retain raw response metadata.
4. Build protocol tests for tools, streams, errors, and usage.
5. Run task-quality and safety evaluations on both routes.
6. Canary new conversations while keeping old sessions pinned.
7. Measure accepted tasks per dollar and p95 latency.
8. Keep a one-step route rollback.

Once both adapters pass the same contract, use the policy in our multi-model AI routing guide to select routes, cap retries, record the resolved model, and fail over only when the workload permits substitution.

FAQ

Final recommendation

For an OpenAI vs Anthropic API migration, start with compatibility to reduce implementation time, but treat it as a documented dialect. Normalize common messages, tools, events, errors, and usage; preserve provider-specific extensions; and choose native APIs when the product depends on their advanced features.

Official sources

• Anthropic OpenAI SDK compatibility
• Claude API overview
• OpenAI text generation guide
• OpenAI Responses API reference