> ## Documentation Index
> Fetch the complete documentation index at: https://assemblyai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-turn Conversations

## Overview

Multi-turn conversations allow you to maintain context across multiple exchanges by including conversation history in your API requests. This enables the model to understand and reference previous messages, creating natural, coherent dialogues.

### Why use multi-turn conversations?

With conversation history, you can:

* **Ask follow-up questions** - Ask "What's the population?" and the model knows you're referring to Paris from the previous message
* **Build on previous responses** - Request clarifications, expansions, or corrections without repeating context
* **Create interactive experiences** - Build chatbots, assistants, and conversational interfaces that feel natural

### How it works

Each API request includes an array of previous messages. The model uses this history to understand context and maintain coherence across the conversation:

```python theme={null}
# First exchange
messages = [
    {"role": "user", "content": "What is the capital of France?"}
]
# Response: "The capital of France is Paris."

# Second exchange - model remembers Paris
messages = [
    {"role": "user", "content": "What is the capital of France?"},
    {"role": "assistant", "content": "The capital of France is Paris."},
    {"role": "user", "content": "What's the population?"}
]
# Response: "As of the latest estimates, the population of Paris is approximately 2.2 million..."
```

**Note:** You're responsible for managing conversation history. Each request must include all relevant previous messages - the API doesn't store history between requests.

## Getting started

Maintain context by including conversation history:

<Tabs>
  <Tab title="Python" language="python">
    ```python expandable theme={null}
    import requests

    headers = {
      "authorization": "<YOUR_API_KEY>"
    }

    conversation_history = [
        {"role": "user", "content": "What is the capital of France?"},
        {"role": "assistant", "content": "The capital of France is Paris."},
        {"role": "user", "content": "What's the population?"}
    ]

    response = requests.post(
        "https://llm-gateway.assemblyai.com/v1/chat/completions",
        headers = headers,
        json = {
            "model": "claude-sonnet-4-6",
            "messages": conversation_history,
            "max_tokens": 1000
        }
    )

    result = response.json()
    agent_response = result["choices"][0]["message"]["content"]
    print(agent_response)

    # Append the assistant's response to conversation history
    conversation_history.append({"role": "assistant", "content": agent_response})
    ```
  </Tab>

  <Tab title="JavaScript" language="javascript">
    ```javascript expandable theme={null}
    const headers = {
      authorization: "<YOUR_API_KEY>",
      "Content-Type": "application/json",
    };

    const conversation_history = [
      { role: "user", content: "What is the capital of France?" },
      { role: "assistant", content: "The capital of France is Paris." },
      { role: "user", content: "What's the population?" },
    ];

    fetch("https://llm-gateway.assemblyai.com/v1/chat/completions", {
      method: "POST",
      headers: headers,
      body: JSON.stringify({
        model: "claude-sonnet-4-6",
        messages: conversation_history,
        max_tokens: 1000,
      }),
    })
      .then((response) => response.json())
      .then((result) => {
        const agent_response = result.choices[0].message.content;
        console.log(agent_response);

        // Append the assistant's response to conversation history
        conversation_history.push({ role: "assistant", content: agent_response });
      })
      .catch((error) => {
        console.error("Error:", error);
      });
    ```
  </Tab>
</Tabs>

## Message types

When building conversation history, you can use the following message types:

* **user** - Messages from the user
* **assistant** - Messages from the AI model
* **system** - System instructions or context

Structure your conversation history with these message types to track the complete interaction flow between the user and model.

## API reference

### Request

The LLM Gateway accepts POST requests to `https://llm-gateway.assemblyai.com/v1/chat/completions` with the following parameters:

```bash expandable theme={null}
curl -X POST \
  "https://llm-gateway.assemblyai.com/v1/chat/completions" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [
      {
        "role": "user",
        "content": "What is the capital of France?"
      },
      {
        "role": "assistant",
        "content": "The capital of France is Paris."
      },
      {
        "role": "user",
        "content": "What'\''s the population?"
      }
    ],
    "max_tokens": 1000
  }'
```

#### Request parameters

| Key           | Type   | Required? | Description                                                                                                          |
| ------------- | ------ | --------- | -------------------------------------------------------------------------------------------------------------------- |
| `model`       | string | Yes       | The model to use for completion. See [Available models](/llm-gateway#available-models) section for supported values. |
| `messages`    | array  | Yes       | An array of message objects representing the conversation history.                                                   |
| `max_tokens`  | number | No        | The maximum number of tokens to generate. Default: 1000. Range: \[1, context\_length).                               |
| `temperature` | number | No        | Controls randomness in the output. Higher values make output more random. Range: \[0, 2].                            |

#### Message object

| Key       | Type            | Required? | Description                                                                                                    |
| --------- | --------------- | --------- | -------------------------------------------------------------------------------------------------------------- |
| `role`    | string          | Yes       | The role of the message sender. Valid values: `"user"`, `"assistant"`, `"system"`, or `"tool"`.                |
| `content` | string or array | Yes       | The message content. Can be a string or an array of content parts for the `"user"` role.                       |
| `name`    | string          | No        | An optional name for the message sender. For non-OpenAI models, this will be prepended as `{name}: {content}`. |

#### Content part object

| Key    | Type   | Required? | Description                                                |
| ------ | ------ | --------- | ---------------------------------------------------------- |
| `type` | string | Yes       | The type of content. Currently only `"text"` is supported. |
| `text` | string | Yes       | The text content.                                          |

### Response

The API returns a JSON response with the model's completion:

```json expandable theme={null}
{
  "request_id": "abc123",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "As of the latest estimates, the population of Paris is approximately 2.2 million people within the city proper, and around 12 million in the greater metropolitan area."
      },
      "finish_reason": "stop"
    }
  ],
  "request": {
    "model": "claude-sonnet-4-6",
    "max_tokens": 1000
  },
  "usage": {
    "input_tokens": 45,
    "output_tokens": 35,
    "total_tokens": 80
  }
}
```

#### Response fields

| Key                          | Type   | Description                                                                   |
| ---------------------------- | ------ | ----------------------------------------------------------------------------- |
| `request_id`                 | string | A unique identifier for the request.                                          |
| `choices`                    | array  | An array of completion choices. Typically contains one choice.                |
| `choices[i].message`         | object | The message object containing the model's response.                           |
| `choices[i].message.role`    | string | The role of the message, typically `"assistant"`.                             |
| `choices[i].message.content` | string | The text content of the model's response.                                     |
| `choices[i].finish_reason`   | string | The reason the model stopped generating. Common values: `"stop"`, `"length"`. |
| `request`                    | object | Echo of the request parameters (excluding `messages`).                        |
| `usage`                      | object | Token usage statistics for the request.                                       |
| `usage.input_tokens`         | number | Number of tokens in the prompt.                                               |
| `usage.output_tokens`        | number | Number of tokens in the completion.                                           |
| `usage.total_tokens`         | number | Total tokens used (prompt + completion).                                      |

### Error response

If an error occurs, the API returns an error response:

```json theme={null}
{
  "code": 400,
  "message": "invalid request body",
  "request_id": "2a9adf03-c73e-4333-a42d-54b515e6afbd",
  "metadata": {
    "errors": [
      "one of messages or prompt required"
    ]
  }
}
```

| Key               | Type   | Description                                                              |
| ----------------- | ------ | ------------------------------------------------------------------------ |
| `code`            | number | HTTP status code for the error.                                          |
| `message`         | string | A human-readable description of the error.                               |
| `request_id`      | string | Unique identifier for the request. Include this when contacting support. |
| `metadata`        | object | Optional. Present on 400 responses with per-field validation details.    |
| `metadata.errors` | array  | List of specific validation failure messages.                            |

#### Common error codes

| Code | Description                               |
| ---- | ----------------------------------------- |
| 400  | Bad Request - Invalid request parameters  |
| 401  | Unauthorized - Invalid or missing API key |
| 403  | Forbidden - Insufficient permissions      |
| 404  | Not Found - Invalid endpoint or model     |
| 429  | Too Many Requests - Rate limit exceeded   |
| 500  | Internal Server Error - Server-side error |