Message Format Converter

Why Message Format Conversion Matters

Every major AI provider uses a different message format for their chat completion API. OpenAI uses a messages array where system instructions are included as a message with role "system". Anthropic separates the system prompt into its own parameter and uses content blocks for rich content. Google Gemini uses "contents" with "parts" and maps the AI role to "model" instead of "assistant". These differences create friction for developers who want to support multiple providers or migrate between them.

This converter bridges the gap by translating between all three formats automatically. Build your conversation using the visual message builder, specify an optional system prompt, and get the equivalent request structure for any provider. The output includes the complete request body as JSON, ready-to-use Python code with the official SDK, and JavaScript code with the official npm package. Every conversion handles the nuances of role mapping, system prompt placement, and content structure differences.

Format Differences Explained

OpenAI uses the most straightforward format. Messages are an array of objects with role (system, user, assistant) and content (string or array). System messages are placed at the beginning of the messages array. For multi-modal content, the content field becomes an array of typed objects with text and image_url blocks. Tool calls use the tool_calls field in assistant messages with function name and arguments as a JSON string.

Anthropic separates the system prompt from the messages array into a top-level system parameter. Messages only use "user" and "assistant" roles — there is no "system" role in the messages array. Content can be a string or an array of typed content blocks (text, image, tool_use, tool_result). Images use base64 data with explicit media types rather than URLs. Tool calls appear as content blocks with type "tool_use" and the input as a parsed JSON object (not a string).

Google Gemini uses contents instead of messages, parts instead of content, and model instead of assistant. System instructions are in a separate system_instruction field with its own parts array. Images use inline_data with mime_type and data fields. Tool definitions use function_declarations within a tools array, and tool calls use functionCall parts with name and args.

Key Translation Rules

When converting from OpenAI to Anthropic: extract system messages from the array and join their content into the Anthropic system parameter. Map "user" and "assistant" roles directly. Convert string content to the Anthropic string format. Convert content arrays by mapping "text" blocks to Anthropic text blocks and "image_url" blocks to Anthropic image blocks (note: you need to fetch and base64-encode the URL images). Convert tool_calls to tool_use content blocks, changing arguments from JSON string to parsed object.

When converting from Anthropic to OpenAI: move the system parameter into the messages array as the first message with role "system". Map roles directly. Convert content blocks to OpenAI format: text blocks become text objects, image blocks with base64 become image_url blocks (you may need to create data URIs). Convert tool_use content blocks to tool_calls with function name and arguments as JSON string. Convert tool_result blocks to messages with role "tool".

When converting from either to Google Gemini: rename "messages" to "contents", "content" to "parts", and "assistant" to "model". Move system prompts to system_instruction. Convert text content to {"text": "..."} parts. Convert images to inline_data format. Convert tool calls to functionCall parts. Google does not support a separate "system" role in contents, so system instructions must use the dedicated field.

Practical Migration Scenarios

The most common migration scenario is moving from OpenAI to Anthropic. Many developers start with OpenAI and later want to add Claude support for its longer context window, better instruction following, or specific capabilities like Constitutional AI safety. The conversion layer is typically 20-30 lines of code: extract system messages, map roles, and restructure content blocks. This converter generates that exact code for you.

Another common scenario is building a multi-provider abstraction layer. Applications like LangChain, LiteLLM, and custom routing systems need to translate a single internal format to multiple provider formats. Understanding the exact differences between formats — as documented in this tool — is essential for building a reliable abstraction. The generated code can serve as the foundation for your provider-specific adapters. For comparing API behavior across providers, LockML provides cross-provider testing tools.

Handling Edge Cases

System prompts require special attention because each provider handles them differently. OpenAI allows multiple system messages anywhere in the conversation. Anthropic allows a single system parameter (or array of system content blocks). Google uses a separate system_instruction field. When converting from OpenAI's multi-system-message pattern, concatenate all system messages into a single system parameter for Anthropic and Google.

Tool call format differences are the most complex to translate. OpenAI sends arguments as a JSON string that you must parse. Anthropic sends input as an already-parsed object. Google sends args as an object. Tool results also differ: OpenAI uses a "tool" role message, Anthropic uses a "user" role message with tool_result content blocks, and Google uses functionResponse parts in the next user turn. The converter handles all these differences automatically, generating the correct format for each provider.

Image handling varies significantly. OpenAI accepts image URLs directly. Anthropic requires base64-encoded data with explicit media types (though URL support exists). Google uses inline_data with mime_type. When converting image-containing messages, you may need to fetch and re-encode images depending on the source and target formats. The converter notes these requirements in the generated code comments. For image optimization before API submission, Krzen provides compression tools.