Skip to main content

Chat

Given a list of messages comprising a conversation, the model will return a response. The Chat API can call built-in tools such as Code Interpreter and Browsing without any configuration needed on the client.

This API is not currently compatible with the OpenAI client libraries due to its ability to return multiple messages. We will soon make available a Chat Completions endpoint that is compatible with the OpenAI specification.

Chat​

POST /v1/chat/messages

Request body json​

  • messages array required

    A list of messages comprising the conversation so far.

    [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "What's the weather in Sydney?"
        },
        {
            "role": "assistant",
            "content": "",
            "function_call": {
                "name": "get_weather",
                "arguments": "{\"location\": \"Sydney\"}"
            }
        },
        {
            "role": "function",
            "name": "get_weather",
            "content": "{\"location\": \"Sydney\", \"temperature\": \"20C\"}"
        },
         {
            "role": "assistant",
            "content": "It's currently 20 degrees celsius in Sydney, Australia. Is there anything else I can help you with?",
        },
    ]

  • model string required

    ID of the model to use. Currently, the following models are supported: gpt-4-turbo-tools, gpt-3.5-turbo-tools, gpt-4-turbo, gpt-3.5-turbo

  • stream boolean

    If set to true, responses will be streamed through server-sent events. Due to server-side tool calls, multiple messages may be streamed back to the client. Each message is terminated with data: [DONE], and the stream is terminated with data: [END] when it is complete.

    To debug errors, temporarily disable streaming to receive error messages in the response.

  • tools array

    An array of tools that can be used by the model. Tool calls are run on the server-side, and do not require any action on the client. The following tools are currently available: code_interpreter, browsing.

    Tools require a compatible model, identifiable by tools in the model ID.

  • custom_tools array

    An array of custom tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. Custom tools require action on the developer's end. Learn more about tool calling in OpenAI's guide.

    [
         {
             "type": "function",
             "function": {
                 "name": "get_current_weather",
                 "description": "Get the current weather in a given location",
                 "parameters": {
                     "type": "object",
                     "properties": {
                         "location": {
                             "type": "string",
                             "description": "The city and state, e.g. San Francisco, CA",
                         },
                     "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                     },
                     "required": ["location"],
                 }
             }
         }
    ]

    Tool calls are included in the message object as an array in the following format:

     [
         {
             "id": "call_NhGNTLCkZm46pKmTzirhrneT",
             "type": "function",
             "function": {
                 "name": "browsing",
                 "arguments": "{\"query\":\"hello world\"}"
             }
         }
     ]

    To respond to a tool call, append a message with the following format to the messages:

     {
         "tool_call_id": "call_NhGNTLCkZm46pKmTzirhrneT",
         "role": "tool",
         "content": "[TOOL OUTPUT]"
     }

  • functions (deprecated) array

    A list of functions the model may generate JSON inputs for. Learn more about functions in OpenAI's guide. Function calls require action on the developer's end.

  • files array

    Array of file objects (to obtain a file ID, upload first using the Files API):

    {
    	"file_id": "[FILE ID]",
    	"name": "[FILE NAME]"
    	"type": "[FILE MIME TYPE]"
    }

    Files require a tool that is able to access them. Currently, this is only code_interpreter.

Additionally, all standard OpenAI Chat Completions parameters such as temperature, top_p, and max_tokens are available. Learn more about these parameters in the OpenAI Chat Completions API reference.

Returns​

Non-streaming​

{
  "messages": [
    {
      "role": "assistant",
      "content": "Hello there, how may I assist you today?",
    }
  ]
}

Streaming​

data: {"role":"assistant","content":""}

data: {"content":"Hello"}

....

data: {}

data: [DONE]

data: [END]