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

#  Chat request

## Overview

The Jamba API provides access to a set of instruction-following chat models. It describes the details for interacting with the chat model via the API endpoint and provides specifications for request and response structures.

***

## Request body

<ParamField body="model" type="string" required>
  The name of the model to use.\
  You can call our model without specifying a version by using the following model names:

  * `jamba-large`
  * `jamba-mini`

  For more information on the available model versions, [click here](/docs/jamba-foundation-models).
</ParamField>

<ParamField body="messages" type="object[]" required>
  A list of messages representing the conversation history. The structure of the message object depends on the type:

  <Expandable title="properties">
    <ParamField body="system message" type="object">
      An initial system message is optional but recommended to set the tone of the chat.

      <Expandable title="properties">
        <ParamField body="role" type="string" required>
          The role of the entity that is creating the message.
        </ParamField>

        <ParamField body="content" type="string" required>
          The content of the message.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="user message" type="object">
      Input provided by the user.

      <Expandable title="properties">
        <ParamField body="role" type="string" required>
          The role of the entity that is creating the message, in this case the user.
        </ParamField>

        <ParamField body="content" type="string" required>
          The content of the message.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="assistant message" type="object">
      Response generated by the model. Include this in your request to provide context for future answers.

      <Expandable title="properties">
        <ParamField body="role" type="string" required>
          The role of the entity that is creating the message, in this case the assistant.
        </ParamField>

        <ParamField body="content" type="string" required>
          The content of the message.
        </ParamField>

        <ParamField body="tool_calls" type="object[]">
          The function calls generated by the model, such as tool invocations.
        </ParamField>

        <ParamField body="id" type="string">
          The id of the tool call.
        </ParamField>

        <ParamField body="type" type="string">
          The type of tool.
        </ParamField>

        <ParamField body="function" type="object">
          The function invoked by the model.
        </ParamField>

        <ParamField body="name" type="string">
          The name of the function.
        </ParamField>

        <ParamField body="arguments" type="JSON string">
          The parameters of the function as a JSON schema.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="tool message" type="object">
      Contains the output of a tool. Add the function output for user-implemented tools to enable a user-friendly model response. If included, ensure an assistant message with a tool\_calls entry with a matching id exists.

      <Expandable title="properties">
        <ParamField body="role" type="string" required>
          The role of the entity that is creating the message, in this case the tool.
        </ParamField>

        <ParamField body="content" type="string" required>
          The content of the message.
        </ParamField>

        <ParamField body="tool_call_id" type="string" required>
          The message is a response to this tool call.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="tools" type="object[]">
  A list of tools that the model can use when generating a response.\
  Currently, the only function type tools are supported.

  <Expandable title="properties">
    <ParamField body="type" type="string" required>
      The type of tool. Currently, the only supported value is "function".
    </ParamField>

    <ParamField body="function" type="object" required>
      Describes a function to call. Currently, all functions must be described by the user; there are no built-in functions. An example function template is given below.

      <Expandable title="more">
        <ParamField body="name" type="string" required>
          The name of the function.
        </ParamField>

        <ParamField body="description" type="object" required>
          Provide a complete description of what the function does, what it returns, and any limitations.
        </ParamField>

        <ParamField body="parameter" type="object">
          Each function parameter has a name, a type ("string", "integer", "float", "array", "boolean", or "enum"), and a description.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="documents" type="object[]">
  The document parameter accepts a list of objects, each containing multiple fields.

  <Expandable title="properties">
    <ParamField body="content" type="string" required>
      The content of this "document".
    </ParamField>

    <ParamField body="metadata" type="object[]">
      Key-value pairs describing the document:

      <Expandable title="more">
        <ParamField body="key" type="string" required>
          Type of metadata, like 'author', 'date', 'url', etc. Should be things the model understands.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="value" type="string" required>
      Value of the metadata.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="response_format" type="object">
  An object defining the output format required from the model.\
  Setting it to `{ "type": "json_object" }` activates JSON mode, ensuring the generated message adheres to valid JSON structure.
</ParamField>

<ParamField body="max_tokens" type="integer">
  The maximum number of tokens the model can generate in its response.\
  For Jamba models, the maximum allowed value is 4096 tokens.
</ParamField>

<ParamField body="temperature" type="float">
  Controls the variety of responses provided—a higher value results in more diverse answers.\
  **Default:** 0.4, **Range:** 0.0–2.0\
  [More information](https://ai21-demo.mintlify.app/v4.2/docs/large-language-models)
</ParamField>

<ParamField body="top_p" type="float">
  Limit the pool of next tokens in each step to the top N percentile of possible tokens, where 1.0 means the pool of all possible tokens, and 0.01 means the pool of only the most likely next tokens. \
  **Default**: 1.0, **Range**: 0 \<= value \<=1.0\
  [More information](/v4.2/docs/large-language-models)
</ParamField>

<ParamField body="stop" type="string[]">
  End the message when the model generates one of these strings. The stop sequence is not included in the generated message. Each sequence can be up to 64K long, and can contain newlines as `n` characters.

  <Accordion title="Show more">
    * **Single stop string with a word and a period**: "monkeys."
    * **Multiple stop strings and a newline**: \["cat", "dog", " .", "####", "\n"]
  </Accordion>
</ParamField>

<ParamField body="n" type="integer">
  How many chat responses to generate. *Default:1, Range: 1 – 16.*  \
  **Notes**:

  * If `n > 1`, setting `temperature = 0` will fail because all answers are guaranteed to be duplicates.
  * `n` must be 1 when `stream = True`
</ParamField>

<ParamField body="stream" type="boolean">
  Stream results one token at a time using server-sent events. Useful for long results to avoid long wait times. If `True`, `n` must be 1. Must be `False` if using `tools`.

  <RequestExample>
    ```python Python theme={"system"}
    from ai21 import AI21Client
    from ai21.models.chat import ChatMessage

    messages = [
        ChatMessage(role="user", content="Hello how are you?"),
    ]

    client = AI21Client()

    client.chat.completions.create(
        messages=messages,
        model="jamba-large",
        max_tokens=1024,
    )
    ```

    ```javascript JavaScript theme={"system"}
    import { AI21 } from 'ai21';

    const client = new AI21({
      apiKey: process.env.AI21_API_KEY, // You can also hardcode your API key here
    });

    const response = await client.chat.completions.create({
      model: 'jamba-large',
      messages: [
        { role: 'user', content: 'Hello how are you?' }
      ],
      max_tokens: 1024
    });

    console.log(response);
    ```

    ```php PHP theme={"system"}
    <?php

    $curl = curl_init();

    curl_setopt_array($curl, [
      CURLOPT_URL => "https://api.ai21.com/studio/v1/chat/completions",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_ENCODING => "",
      CURLOPT_MAXREDIRS => 10,
      CURLOPT_TIMEOUT => 30,
      CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
      CURLOPT_CUSTOMREQUEST => "POST",
      CURLOPT_POSTFIELDS => "{\n"
        . "  \"model\": \"jamba-large\",\n"
        . "  \"messages\": [\n"
        . "    {\n"
        . "      \"role\": \"user\",\n"
        . "      \"content\": \"Hello how are you?\"\n"
        . "    }\n"
        . "  ],\n"
        . "  \"max_tokens\": 1024\n"
        . "}",
      CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "Authorization: Bearer YOUR_API_KEY"
      ],
    ]);

    $response = curl_exec($curl);
    $err = curl_error($curl);

    curl_close($curl);

    if ($err) {
      echo "cURL Error #:" . $err;
    } else {
      echo $response;
    ```

    ```bash cURL theme={"system"}
    curl https://api.ai21.com/studio/v1/chat/completions \
         --header "Authorization: Bearer $AI21_API_KEY" \
         --header "Content-Type: application/json" \
         --data '{
           "model": "jamba-large",
           "max_tokens": 1024,
           "messages": [
             {"role": "user", "content": "Hello, how are you?"}
           ]
         }'
    ```

    ```go Go theme={"system"}
    package main

    import (
            "fmt"
            "strings"
            "net/http"
            "io/ioutil"
    )

    func main() {
            url := "https://api.ai21.com/studio/v1/chat/completions"

            payload := strings.NewReader("{\n" +
                    "  \"model\": \"jamba-large\",\n" +
                    "  \"messages\": [\n" +
                    "    {\n" +
                    "      \"role\": \"user\",\n" +
                    "      \"content\": \"Hello how are you?\"\n" +
                    "    }\n" +
                    "  ],\n" +
                    "  \"max_tokens\": 1024\n" +
                    "}")

            req, _ := http.NewRequest("POST", url, payload)

            req.Header.Add("Content-Type", "application/json")
            req.Header.Add("Authorization", "Bearer YOUR_API_KEY")

            res, err := http.DefaultClient.Do(req)
            if err != nil {
                    panic(err)
            }
            defer res.Body.Close()

            body, _ := ioutil.ReadAll(res.Body)

            fmt.Println(res)
    ```

    ```java Java theme={"system"}
    import kong.unirest.HttpResponse;
    import kong.unirest.Unirest;

    public class AI21Chat {
        public static void main(String[] args) {
            HttpResponse<String> response = Unirest.post("https://api.ai21.com/studio/v1/chat/completions")
                .header("Content-Type", "application/json")
                .header("Authorization", "Bearer YOUR_API_KEY")
                .body("{\n" +
                      "  \"max_tokens\": 1024,\n" +
                      "  \"messages\": [\n" +
                      "    {\n" +
                      "      \"role\": \"user\",\n" +
                      "      \"content\": \"Hello, how are you?\"\n" +
                      "    }\n" +
                      "  ],\n" +
                      "  \"model\": \"jamba-large\"\n" +
                      "}")
                .asString();

            System.out.println(response.getStatus());
            System.out.println(response.getBody());
        }
    }
    ```

    ```json JSON theme={"system"}
    {
      "model": "jamba-large",
      "messages": [
        {
          "role": "user",
          "content": "Hello how are you?"
        }
      ],
      "max_tokens": 1024
    }
    ```
  </RequestExample>
</ParamField>