Principle:Ollama Ollama Anthropic API Compatibility
| Knowledge Sources | |
|---|---|
| Domains | API Compatibility, Protocol Translation |
| Last Updated | 2025-02-15 00:00 GMT |
Overview
Anthropic API Compatibility is the principle of translating between Anthropic's Messages API format and a host system's native request/response format, enabling clients built for the Anthropic API to interact transparently with alternative inference backends. This involves mapping Anthropic-specific constructs such as message roles, content blocks, tool use schemas, and streaming event types into equivalent internal representations.
Core Concepts
Protocol Translation
Protocol translation involves converting HTTP requests conforming to one API specification into the internal data structures of another system. In the context of Anthropic API compatibility, this means parsing incoming JSON payloads that follow Anthropic's Messages API schema (with fields like model, messages, max_tokens, system, and tools) and mapping them to the host system's native chat completion request format. The reverse translation converts native responses back into Anthropic-conformant JSON, including proper content block structures and stop reason codes.
Content Block Mapping
Anthropic's Messages API uses a structured content block system where each message contains an array of typed content blocks (text, image, tool_use, tool_result). Compatibility layers must faithfully translate these block types into the host format. Text blocks map directly, image blocks require base64 data URI construction, tool_use blocks must be converted to the host's function calling format, and tool_result blocks must be recognized as assistant-requested tool outputs fed back into the conversation.
Streaming Event Translation
Anthropic's streaming protocol uses Server-Sent Events (SSE) with specific event types: message_start, content_block_start, content_block_delta, content_block_stop, message_delta, and message_stop. A compatibility layer must transform the host system's native streaming chunks into this precise event sequence, maintaining proper ordering and including usage statistics in the appropriate delta events.
Role and Parameter Normalization
Different API specifications use different conventions for message roles, parameter names, and default values. Anthropic uses assistant and user roles with a separate system parameter, while other systems may embed the system prompt as a message with role system. Temperature, top_p, top_k, and stop sequences may have different naming conventions or valid ranges that require normalization during translation.
Implementation Notes
In the Ollama codebase, Anthropic API compatibility is implemented through a dedicated handler layer that intercepts HTTP requests to the /api/chat-compatible Anthropic endpoint, translates incoming Anthropic Messages API requests into Ollama's native chat request format, invokes the standard inference pipeline, and translates the response stream back into Anthropic-conformant SSE events. The translation layer handles all Anthropic content block types including text, images, and tool use, and properly maps stop reasons (end_turn, max_tokens, stop_sequence, tool_use) to their Anthropic equivalents.