# Using the Cohere Chat API for Text Generation

> How to use the Chat API endpoint with Cohere LLMs to generate text responses in a conversational interface

The Chat API endpoint is used to generate text with Cohere LLMs. This endpoint facilitates a conversational interface, allowing users to send messages to the model and receive text responses.

Every message comes with a `content` field and an associated `role`, which indicates who that message is sent from. Roles can be `user`, `assistant`, `system` and `tool`.

<CodeBlocks>
  ```python PYTHON
  import cohere

  co = cohere.ClientV2(api_key="<YOUR API KEY>")

  res = co.chat(
      model="command-a-03-2025",
      messages=[
          {
              "role": "user",
              "content": "Write a title for a blog post about API design. Only output the title text.",
          }
      ],
  )

  print(res.message.content[0].text)
  # "The Ultimate Guide to API Design: Best Practices for Building Robust and Scalable APIs"
  ```

  ```java JAVA
  package chatv2post;

  import com.cohere.api.Cohere;
  import com.cohere.api.resources.v2.requests.V2ChatRequest;
  import com.cohere.api.types.*;
  import java.util.List;

  public class Default {
      public static void main(String[] args) {
          Cohere cohere = Cohere.builder().token("<<apiKey>>").clientName("snippet").build();

          ChatResponse response =
                  cohere.v2()
                          .chat(
                                  V2ChatRequest.builder()
                                      .model("command-a-03-2025")
                                      .messages(
                                          List.of(
                                              ChatMessageV2.user(
                                                  UserMessage.builder()
                                                      .content(
                                                          UserMessageContent
                                                                  .of("Hello world!"))
                                                      .build())))
                                      .build());

          System.out.println(response);
      }
  }

  ```

  ```typescript TYPESCRIPT
  const { CohereClientV2 } = require('cohere-ai');

  const cohere = new CohereClientV2({
    token: '<<apiKey>>',
  });

  (async () => {
    const response = await cohere.chat({
      model: 'command-a-03-2025',
      messages: [
        {
          role: 'user',
          content: 'hello world!',
        },
      ],
    });

    console.log(response);
  })();

  ```

  ```bash cURL
  curl --request POST \
    --url https://api.cohere.ai/v2/chat \
    --header 'accept: application/json' \
    --header 'content-type: application/json' \
    --header "Authorization: bearer $CO_API_KEY" \
    --data '{
      "model": "command-a-03-2025",
      "messages": [
        {
          "role": "user",
          "content": "Write a title for a blog post about API design. Only output the title text."
        }
      ]
    }'
  ```
</CodeBlocks>

## Response Structure

Below is a sample response from the Chat API. Here, the `role` of the `message` is going to be `assistant`.

```json JSON
{
    "id": "5a50480a-cf52-46f0-af01-53d18539bd31",
    "message": {
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "The Art of API Design: Crafting Elegant and Powerful Interfaces",
            }
        ],
    },
    "finish_reason": "COMPLETE",
    "meta": {
        "api_version": {"version": "2", "is_experimental": True},
        "warnings": [
            "You are using an experimental version, for more information please refer to https://docs.cohere.com/versioning-reference"
        ],
        "billed_units": {"input_tokens": 17, "output_tokens": 12},
        "tokens": {"input_tokens": 215, "output_tokens": 12},
    },
}
```

Every response contains the following fields:

* `message` the generated message from the model.
* `id` the ID corresponding to this response.
* `finish_reason` can be one of the following:
  * `COMPLETE` the model successfully finished generating the message
  * `MAX_TOKENS` the model's context limit was reached before the generation could be completed
* `meta` contains information with token counts, billing etc.

## System Message

Developers can adjust the LLMs behavior by including a system message in the `messages` list
with the role set to `system`.

The system message contains instructions that the model will respect over any instructions sent in messages sent from other roles. It is often used by developers to control the style in which the model communicates and to provide guidelines for how to handle various topics.

It is recommended to send the system message as the first element in the messages list.

<CodeBlocks>
  ```python PYTHON
  import cohere

  co = cohere.ClientV2(api_key="<YOUR API KEY>")

  system_message = "You respond concisely, in about 5 words or less"

  res = co.chat(
      model="command-a-03-2025",
      messages=[
          {"role": "system", "content": system_message},
          {
              "role": "user",
              "content": "Write a title for a blog post about API design. Only output the title text.",
          },
      ],  # "Designing Perfect APIs"
  )

  print(res.message.content[0].text)
  ```

  ```bash Curl
  curl --request POST \
    --url https://api.cohere.ai/v2/chat \
    --header 'accept: application/json' \
    --header 'content-type: application/json' \
    --header "Authorization: bearer $CO_API_KEY" \
    --data '{
      "model": "command-a-03-2025",
      "messages": [
        {
          "role": "system",
          "content": "You respond concisely, in about 5 words or less"
        },
        {
          "role": "user",
          "content": "Write a title for a blog post about API design. Only output the title text."
        }
      ]
    }'
  ```
</CodeBlocks>

## Multi-Turn Conversations

A single Chat request can encapsulate multiple turns of a conversation, where each message in the `messages` list appears in the order it was sent. Sending multiple messages can give the model context for generating a response.

<CodeBlocks>
  ```python PYTHON
  import cohere

  co = cohere.ClientV2(api_key="<YOUR API KEY>")

  system_message = "You respond concisely, in about 5 words or less"

  res = co.chat(
      model="command-a-03-2025",
      messages=[
          {"role": "system", "content": system_message},
          {
              "role": "user",
              "content": "Write a title for a blog post about API design. Only output the title text.",
          },
          {"role": "assistant", "content": "Designing Perfect APIs"},
          {
              "role": "user",
              "content": "Another one about generative AI.",
          },
      ],
  )

  # "AI: The Generative Age"
  print(res.message.content[0].text)
  ```

  ```bash Curl
  curl --request POST \
    --url https://api.cohere.ai/v2/chat \
    --header 'accept: application/json' \
    --header 'content-type: application/json' \
    --header "Authorization: bearer $CO_API_KEY" \
    --data '{
      "model": "command-a-03-2025",
      "messages": [
        {
          "role": "system",
          "content": "You respond concisely, in about 5 words or less"
        },
        {
          "role": "user",
          "content": "Write a title for a blog post about API design. Only output the title text."
        },
        {
          "role": "assistant",
          "content": "Designing Perfect APIs"
        },
        {
          "role": "user",
          "content": "Another one about generative AI."
        }
      ]
    }'
  ```
</CodeBlocks>