# Chat Completions

### Overview

This documentation provides instructions on how to use the Chat Completions API endpoint. The API allows you to generate chat completions based on provided messages and parameters.

### Base URL

```
https://www.upchatty.com/api/v1
```

### Endpoint

```
POST /chat/completions
```

### Authentication

The API uses Bearer Token authentication. You must include your API key in the `Authorization` header of each request.

```
Authorization: Bearer YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Request Format

The request should be sent as a POST request with a JSON body.

#### Headers

* `Content-Type: application/json`
* `Authorization: Bearer YOUR_API_KEY`

#### Body Parameters

| Parameter   | Type    | Required | Description                                                                                                                               |
| ----------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| model       | string  | Yes      | The ID of the model to use for generating completions.                                                                                    |
| messages    | array   | Yes      | An array of message objects representing the conversation history.                                                                        |
| temperature | float   | No       | Controls randomness in the output. Higher values make the output more random, lower values make it more deterministic. Range: 0.0 to 1.0. |
| stream      | boolean | No       | If set to `true`, the response will be streamed as it's generated. Default is `false`.                                                    |

**Message Object**

Each message in the `messages` array should have the following structure:

| Field   | Type   | Description                                                                                    |
| ------- | ------ | ---------------------------------------------------------------------------------------------- |
| role    | string | The role of the message sender. Use "user" for user messages and "assistant" for AI responses. |
| content | string | The content of the message.                                                                    |

#### Example Request

```json
{
  "model": "YOUR_CHATBOT_ID",
  "messages": [
    {"role": "user", "content": "How are you?"}
  ],
  "temperature": 0.7
}
```

### Response Format

The API returns a JSON response with the generated completion.

#### Response Fields

| Field   | Type   | Description                                            |
| ------- | ------ | ------------------------------------------------------ |
| id      | string | A unique identifier for the completion.                |
| object  | string | The object type, always "chat.completion".             |
| created | number | The Unix timestamp of when the completion was created. |
| model   | string | The ID of the model used for the completion.           |
| choices | array  | An array containing the completion choices.            |
| usage   | object | An object containing token usage information.          |

**Choice Object**

| Field          | Type   | Description                                  |
| -------------- | ------ | -------------------------------------------- |
| index          | number | The index of the choice.                     |
| message        | object | An object containing the completion message. |
| finish\_reason | string | The reason why the completion finished.      |

**Message Object**

| Field   | Type   | Description                                                  |
| ------- | ------ | ------------------------------------------------------------ |
| role    | string | The role of the message, always "assistant" for completions. |
| content | string | The content of the completion message.                       |

**Usage Object**

| Field              | Type   | Description                             |
| ------------------ | ------ | --------------------------------------- |
| prompt\_tokens     | number | The number of tokens in the prompt.     |
| completion\_tokens | number | The number of tokens in the completion. |
| total\_tokens      | number | The total number of tokens used.        |

#### Example Response

```json
{
  "id": "chatcmpl-1234567890",
  "object": "chat.completion",
  "created": 1678048331,
  "model": "YOUR_CHATBOT_ID",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "As an AI language model, I don't have feelings, but I'm functioning well and ready to assist you with any questions or tasks you may have. How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 41,
    "total_tokens": 50
  }
}
```

### Error Responses

The API may return error responses in the following format:

```json
{
  "error": "Error message"
}
```

Common error status codes:

* 400: Bad Request - Invalid input parameters
* 401: Unauthorized - Invalid or missing API key
* 500: Internal Server Error

### Example cURL Request

Here's an example of how to make a request using cURL:

```bash
curl --location 'https://www.upchatty.com/api/v1/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
    "model": "YOUR_CHATBOT_ID",
    "messages": [{"role": "user", "content": "How are you?"}],
    "temperature": 0.7
  }'
```

Replace `YOUR_API_KEY` with your actual API key.

### Support

If you encounter any issues or have questions about the API, please contact our support team at <support@upchatty.com>.