For a mode direct-to-code migration guide, see our API reference migration guide.

As we continue to improve and expand our AI capabilities, we are excited to introduce our new Messages API, which offers several advantages over our legacy Text Completions API.

This guide will help you migrate your existing applications from the Text Completions API to the Messages API, ensuring a smooth transition and unlocking access to our latest features and improvements.

Why upgrade to the Messages API?

The Messages API offers several key benefits:

Image processing: The Messages API is the only way to process images with Claude, enabling you to leverage our advanced computer vision capabilities for tasks such as image classification, object detection, and more.
Building with Claude 3 models: Our latest and most powerful Claude 3 models (Haiku, Sonnet, and Opus) can only be called via the Messages API. By upgrading, you'll be able to take advantage of their enhanced performance and capabilities.
Improved error handling: The Messages API allows us to return more informative and helpful error messages, making it easier for you to diagnose and resolve issues in your requests.
Better request validation: With the Messages API, we can validate your API requests more effectively, ensuring that you receive the highest quality results and the best possible performance from our models.

How to upgrade to the Messages API

The easiest way to upgrade from the Text Completions API to the Messages API is to use our web Console to convert your prompts. By using the Console, you can quickly and easily migrate your prompts and requests to the Messages API without having to manually rewrite your code.

Simply follow these steps:

1. Go to the Console and select the model you want to use

Within the Console, there is a model settings panel at the bottom right of the messages area. That panel houses a drop down menu where you can select the correct model for your migrated prompt.

This is also where you can adjust any additional parameters as needed, such as temperature and maximum tokens to sample. For more information about our parameters, see the Messages API documentation.

2. Transfer your prompt into the appropriate Console message fields

Text Completions API prompts are multiline strings that encompass all parts of a prompt, such as both the system prompt and the user turn. The Messages API splits the various parts of a prompt, such as the system prompt and the user turn, into separate fields.

For example, let's take this Text Completions API prompt:

Today is March 4, 2024.

Human: What are 3 ways to cook apples?

Assistant:

Without using the Console, transitioning this prompt would require you to rewrite your code entirely into the Messages API. However, dropping the separate parts of your prompt (system prompt & user prompt) into the corresponding Console fields allows you to extract correct pre-formatted code out of the box.

In the Console, the above prompt would look like this:

Notice that there is no Human: or Assistant: text, and that the system prompt and the user prompt belong in different message fields.

3. Copy the pre-formatted code

Once all parts of your prompt are in place and the parameters have been adjusted, click the </> Get Code button on the top right to view and copy the corresponding Messages API code snippet, for both Pyton and TypeScript.

For our example prompt, the automated Python output from the </> Get Code menu would be:

import anthropic

client = anthropic.Anthropic(
    # defaults to os.environ.get("ANTHROPIC_API_KEY")
    api_key="my_api_key",
)
message = client.messages.create(
    model="claude-3-opus-20240229",
    max_tokens=1000,
    temperature=0,
    system="Today is March 4, 2024.",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What are 3 ways to cook apples?"
                }
            ]
        }
    ]
)
print(message.content)

Note: The Console does not yet allow you to prefill Claude's response (i.e., prefilling text in the Assistant turn), but the underlying Messages API does. See our guide on prefilling Claude's response for examples on how to format a Messages API request with this technique.

Migrating from other models

If you're currently using a different AI platform or model and want to switch to Claude with the Messages API, we've created a comprehensive guide to help you through the process. See migrating from other models for detailed instructions on how to adapt your prompts and code to our platform.

API Documentation

For more information on the Messages API and its capabilities, please consult our API documentation:

If you have any questions or need further assistance with upgrading to the Messages API, please don't hesitate to reach out to our support team. We're here to help you make the most of our AI capabilities and ensure a smooth transition to Claude.