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

# Messages

UI completions are returned by the API when `stream=false` is set in the request.

## Request Headers

<ParamField path="Authorization" type="string" required>
  The API key to use for the request.
</ParamField>

<ParamField path="Content-Type" type="string" required>
  The content type of the request. Should be `application/json`.
</ParamField>

## Request Body

<ParamField path="messages" type="array" required>
  An array of messages of the conversation so far.

  <Expandable title="Message Properties">
    <ParamField path="message.role" type="string">
      The role of the message. Can be either `user`, `assistant`, or `tool`.
    </ParamField>

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

    <ParamField path="message.tool_call_id" type="string">
      The ID of the tool call. Only present if the role is `tool`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="model" type="string" required>
  The model to use for the UI completion. Should be one of the models listed in the [Models](/api-reference/models-and-compatibility) page.
</ParamField>

<ParamField path="temperature" type="number">
  The temperature to use for the UI completion. Should be between 0 and 1.
</ParamField>

<ParamField path="top_p" type="number">
  The top-p value to use for the UI completion. Should be between 0 and 1.
</ParamField>

<ParamField path="max_tokens" type="integer">
  The maximum number of tokens to use for the UI completion.
</ParamField>

<ParamField path="n" type="integer">
  The number of completions to generate.
</ParamField>

<ParamField path="stop" type="integer">
  Should be unset or set to 1.
</ParamField>

<ParamField path="stream" type="boolean">
  Whether to stream the response. Should be unset or `false`.
</ParamField>

<Note>
  The parameters above are commonly used with the Messages API. For a
  comprehensive list of all supported parameters and their compatibility across
  different model providers (OpenAI vs Anthropic), see the [Supported API
  Parameters](/api-reference/getting-started#supported-api-parameters) table.
</Note>

<RequestExample>
  ```sh curl theme={null}
  curl -X POST \
    -H "Authorization: Bearer <api_key>" \
    -H "Content-Type: application/json" \
    -d '{"model": "c1/anthropic/claude-sonnet-4/v-20251230", "messages": [{"role": "user", "content": "Hello, world!"}]}' \
    https://api.thesys.dev/v1/embed/chat/completions
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
        "id": "chatcmpl-1743157633416-cffw7tgswx",
        "object": "chat.completion",
        "created": 1743157633,
        "model": "c1/anthropic/claude-sonnet-4/v-20251230",
        "choices": [
            {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": {
                    ...
                }
            },
            "finish_reason": "stop"
            }
        ],
        "usage": {
            "prompt_tokens": 8,
            "completion_tokens": 439,
            "total_tokens": 447
        }
  }
  ```
</ResponseExample>

## Response

<ResponseField name="id" type="string">
  A unique identifier for the UI completion
</ResponseField>

<ResponseField name="choices" type="array">
  An array of completions. Will always contain exactly one object.

  <Expandable title="Properties">
    <ResponseField name="finish_reason" type="string">
      The reason the generation stopped. Can be either `stop` or `tool_calls`.
    </ResponseField>

    <ResponseField name="message" type="object">
      Completion message generated by the model.

      <Expandable title="Properties">
        <ResponseField name="message.role" type="string">
          The role of the message. Will always be `assistant` for generations.
        </ResponseField>

        <ResponseField name="message.content" type="string">
          A JSON object containing the UI completion.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created" type="string">
  The timestamp when the UI completion was created
</ResponseField>

<ResponseField name="model" type="string">
  The model used to generate the UI completion
</ResponseField>

<ResponseField name="object" type="string">
  The object type, which is always `chat.completion`
</ResponseField>

<ResponseField name="usage" type="object">
  An object containing the usage statistics for the UI completion

  <Expandable title="Properties">
    <ResponseField name="usage.prompt_tokens" type="integer">
      Number of tokens in the prompt
    </ResponseField>

    <ResponseField name="usage.completion_tokens" type="integer">
      Number of tokens in the generated UI completion
    </ResponseField>

    <ResponseField name="usage.total_tokens" type="integer">
      Total number of tokens: `prompt_tokens + completion_tokens`
    </ResponseField>
  </Expandable>
</ResponseField>