Codestral API Tutorial: Getting Started With Mistral’s API

Codestral is a state-of-the-art generative model optimized for code generation tasks, including fill-in-the-middle (FIM) and code completion. Trained across over 80 programming languages, Codestral excels in both common and less commonly used languages, making it a versatile tool for developers.

By leveraging the Codestral API, we can automate and integrate code generation into our workflows. In this tutorial, we’ll provide a step-by-step guide to using Codestral API.

If you want to get an overview of Codestral, check out my article on What is Mistral’s Codestral.

Codestral API Endpoints

Codestral offers two main API endpoints to cater to different user needs:

• codestral.mistral.ai: Ideal for individual users and small-scale integrations. This endpoint is currently free until August 1, 2024, after which it will become a monthly subscription service.
• api.mistral.ai: Designed for business and high-demand use cases, this endpoint offers higher rate limits and robust support for large-scale applications.

Mistral recommends the codestral.mistral.ai endpoint if you intend to use Codestral as part of an IDE plugin or if you plan to build tools that expose endpoints directly to users, allowing them to bring their own API keys.

Mistral recommends the api.mistral.ai endpoint for all other use cases due to its higher rate limits and suitability for business applications.

In this tutorial, we’ll use the codestral.mistral.ai endpoint to showcase Codestral's capabilities.

Getting Started With the Codestral API

Acquiring an API Key

To use the Codestral API, you need to sign up for a Mistral AI account and obtain an API key. Follow these steps::

Step 1: Sign up

Visit Mistral AI's sign-up page and create an account.

Step 2: Get an API key

For api.mistral.ai, navigate to the API Keys tab and click Create new key to generate your API key.

For codestral.mistral.ai: Head to the Codestral tab (the one with a “New” badge below the API Keys tab) and follow the instructions on the page to obtain your API key. Note that there’s currently a waiting list, and you’ll need to provide a phone number to sign up. Once approved, you’ll be able to access your API key along with two codestral.mistral.ai specific endpoints on the same page, as shown below:

This article uses the codestral.mistral.ai endpoints to showcase Codestral, so all the examples provided will be tailored to that.

Authentication

To authenticate our API requests, we'll create two Python functions using the requests library. These functions will handle the communication with Codestral's two API endpoints, incorporating the obtained API key into the request headers for authentication. Here are the two functions:

1. call_chat_endpoint — to call the Chat Endpoint https://codestral.mistral.ai/v1/chat/completions.
2. call_fim_endpoint — to call the Completion Endpoint https://codestral.mistral.ai/v1/fim/completions.

Here's how to do this in Python:

import requests
import json

api_key = 'INSERT YOUR API KEY HERE'

def call_chat_endpoint(data, api_key=api_key):
    url = "<https://codestral.mistral.ai/v1/chat/completions>"
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
        "Accept": "application/json"
    }

    response = requests.post(url, headers=headers, data=json.dumps(data))

    if response.status_code == 200:
        return response.json()
    else:
        return f"Error: {response.status_code}, {response.text}"

def call_fim_endpoint(data, api_key=api_key):
    url = "<https://codestral.mistral.ai/v1/fim/completions>"
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
        "Accept": "application/json"
    }

    response = requests.post(url, headers=headers, data=json.dumps(data))

    if response.status_code == 200:
        return response.json()
    else:
        return f"Error: {response.status_code}, {response.text}"

Understanding Codestral's API Endpoints

Now that we've obtained our API key and set up the authentication functions, let's explore how to use Codestral's two API endpoints for code generation. We'll begin with the fill-in-the-middle (FIM) endpoint.

Fill-in-the-middle endpoint

The fill-in-the-middle endpoint is designed to generate code that fits between a given starting point (prompt) and an optional ending point (suffix). This is particularly useful for tasks requiring a specific piece of code to be generated within a larger code structure.

API Endpoint URL: https://codestral.mistral.ai/v1/fim/completions

Parameters:

• prompt: The starting point of the code.
• suffix (optional): The ending point of the code.
• stop (optional): A sequence of tokens to stop generation.

Example:

prompt = "def fibonacci(n: int):"
suffix = "n = int(input('Enter a number: '))\\nprint(fibonacci(n))"
data = {
    "model": "codestral-latest",
    "prompt": prompt,
    "suffix": suffix,
    "temperature": 0
}

response = call_fim_endpoint(data)

Instruct endpoint

The instruct endpoint provides instructions to the model for generating code. It’s useful for more open-ended code-generation tasks.

API Endpoint URL: https://codestral.mistral.ai/v1/chat/completions

Parameters:

• prompt: The instruction for the code generation task.
• temperature (optional): Controls the randomness of the generated code.
• max_tokens (optional): Limits the length of the generated code.

Example:

prompt = "Please write me a function that adds up two numbers"
data = {
    "model": "codestral-latest",
    "messages": [
        {
            "role": "user",
            "content": prompt
        }
    ],
    "temperature": 0
}

response = call_chat_instruct_endpoint(data)

Advanced API Usage

Rate limits

Each endpoint has different rate limits:

• codestral.mistral.ai: 30 requests per minute and 2000 requests per day.
• api.mistral.ai: 200 requests per second per workspace.

To ensure smooth operation and avoid exceeding usage restrictions, managing rate limits is crucial. One effective strategy is to implement retry logic, which pauses and resubmits a request after a specified delay—we can use Python's time library to introduce this delay.

Alternatively, you can keep track of your API usage to ensure you stay within the allowed limits. You can log the number of requests made and compare them against the rate limits.

Error handling

Common error codes include:

• 401 Unauthorized: Invalid API key or missing authentication.
• 429 Too Many Requests: Rate limit exceeded.
• 500 Internal Server Error: Server issues on Mistral AI's side.

For a 401 Unauthorized error, check the API key and ensure it's correctly included in the request headers.

For a 429 Too Many Requests error, try to implement retry logic to wait and retry the request after a delay.

Retry logic is also useful to handle 500 Internal Server Error to try the request again later.

Customizing output

To control the output format and style, you can adjust parameters like prompt (making it more specific or general) and temperature (controlling the model’s creativity).

Experiment with these parameters to fine-tune the balance between creativity and predictability in the generated code.

Integrating Codestral API

Codestral doesn't just function as a standalone API—we can integrate it into our existing development workflows. Let's explore two primary ways to do this: through IDE and text editor integrations or by creating custom scripts.

IDEs and text editors

Codestral integrates seamlessly with popular IDEs and text editors through plugins or extensions. For example, you can set up Codestral with Continue.dev for VS Code or JetBrains:

1. Install the Continue extension for VS Code or JetBrains.
2. Select Mistral API as a provider and choose Codestral as the model.
3. Click Get API Key to get Codestral API key.
4. Click Add model, which will automatically populate the config.json.

Custom scripts

You can build custom scripts or applications that leverage the Codestral API for code generation tasks. Here’s a simple example of a script that generates test functions:

prompt="""Sure, here is a simple function in Python that adds up two numbers:

def add_two_numbers(num1, num2):
    return num1 + num2

You can use this function like this:
result = add_two_numbers(5, 3)
print(result)  # Outputs: 8

This function takes two arguments, num1 and num2, and returns their sum.\ndef test_add_two_numbers():""" 

suffix="" 

data = { "model": "codestral-latest", "prompt": prompt, "suffix": suffix, "temperature": 0 }

response = call_fim_endpoint(data)

Best Practices for Using the Codestral API

To get the most out of Codestral, let's explore some best practices for using the API effectively and responsibly.

Clear and concise prompts

When using the Codestral API, clarity is key. Ensure your prompts or instructions are well-defined and unambiguous to obtain the desired code output. You can guide the model towards generating code that aligns with your expectations by providing specific and contextual prompts.

Iterative refinement

Optimizing your interactions with the Codestral API involves an iterative process of refinement. Experiment with different parameters, prompts, and inputs to achieve the desired outcomes. Analyze the generated code outputs and use them to inform adjustments to your prompts. By continuously refining your approach, you can improve the quality and relevance of the generated code over time.

Responsible use

Responsible use of the Codestral API is important. Ensure that your use of the API aligns with ethical and legal standards. Avoid generating code that could be malicious or harmful. Adhere to best practices for secure and ethical programming, and respect the privacy and rights of others. Using the API responsibly contributes to a positive and sustainable development environment.

Conclusion

This tutorial provided a practical guide to using the Codestral API for code generation. We explored the different endpoints, best practices, and integration options.

I encourage you to experiment with the API and discover how it can enhance your own development workflow.

To learn more about Mistral, check out this Mistral 7B tutorial and this guide to working with the Mistral large model.