> For the complete documentation index, see [llms.txt](https://docs.apismart.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apismart.ai/api-guides/chat-completions-api.md).

# Chat Completions API

Learn how to send text generation requests with ApiSmart's OpenAI-compatible Chat Completions API and enable streaming responses.

Use the Chat Completions API to generate text with supported ApiSmart text models.

ApiSmart provides an **OpenAI-compatible Chat Completions interface**, making it easier to connect applications that already use the familiar `messages` request format.

### 💬 Endpoint

**Method:** `POST`

**Endpoint:** `/v1/chat/completions`

**Full URL:**

`https://gw.apismart.ai/v1/chat/completions`

### 🔑 Authentication

Include your ApiSmart API Key in the `Authorization` header:

```http
Authorization: Bearer <your-api-key>
```

For JSON requests, also include:

```http
Content-Type: application/json
```

Replace `<your-api-key>` with your actual API Key.

### 🚀 Basic Request

A basic request includes a valid model ID and a `messages` array.

```bash
curl https://gw.apismart.ai/v1/chat/completions \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {
        "role": "user",
        "content": "Hello! Please introduce yourself."
      }
    ]
  }'
```

In this example:

* `model` specifies the model that processes the request.
* `messages` contains the conversation input.
* `role` identifies the message role.
* `content` contains the text sent to the model.

### 🧩 Choose a Model

The `model` parameter must use a valid ApiSmart model ID.

For example:

```json
{
  "model": "deepseek-v4-flash"
}
```

To retrieve the latest model list, use:

```bash
curl https://gw.apismart.ai/v1/models \
  -H "Authorization: Bearer <your-api-key>"
```

Use the returned `data[].id` value as the `model` parameter in your request.

For available text models and model ID rules, see [**Models and Model IDs**](/models-and-pricing/models-and-model-ids.md).

> **Model IDs must match exactly.**\
> Periods (`.`), hyphens (`-`), version numbers, and other characters must be entered exactly as documented.

### 📨 Messages

The `messages` field contains the conversation input sent to the selected model.

A simple request can contain a single user message:

```json
{
  "model": "deepseek-v4-flash",
  "messages": [
    {
      "role": "user",
      "content": "Explain API gateways in simple terms."
    }
  ]
}
```

For longer conversations, include the relevant conversation messages in the `messages` array.

### 🌊 Streaming

Chat Completions also supports streaming output.

To enable streaming, add:

```json
{
  "stream": true
}
```

Example:

```bash
curl https://gw.apismart.ai/v1/chat/completions \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {
        "role": "user",
        "content": "Write a short story."
      }
    ],
    "stream": true
  }'
```

With streaming enabled, the response is returned incrementally instead of waiting for the complete generation.

For an overview of standard, streaming, and asynchronous API behavior, see [**Response Modes**](/api-guides/response-modes.md).

### 🔄 Standard vs. Streaming

| Mode          | Configuration    | Typical Use                                     |
| ------------- | ---------------- | ----------------------------------------------- |
| **Standard**  | Default          | Short responses and simple integrations         |
| **Streaming** | `"stream": true` | Interactive applications and longer generations |

Use standard responses when you want to wait for the complete result.

Use streaming when you want generated content to arrive progressively.

### ⚠️ Common Issues

#### Invalid API Key

If authentication fails, the API may return:

`401 invalid_api_key`

Check that:

* The API Key is correct
* The key is enabled
* The `Authorization` header uses the `Bearer` scheme
* There are no missing characters or extra spaces

#### Model Not Available

If the selected model is not available to your API Key, the API may return:

`403 model_not_allowed`

Choose another available model or contact [**ApiSmart Support**](/help-and-resources/contact-support.md) if you need access.

#### Unexpected 503

If you receive an unexpected `503`, first verify the model ID.

ApiSmart model IDs are matched exactly, so an incorrect period, hyphen, or version number can cause the request to fail.

For complete error information, see [**HTTP Status Codes and API Errors**](/troubleshooting/http-status-codes-and-api-errors.md).

### ✅ Before Sending a Request

Before making a Chat Completions request, verify that:

* Your API Key is valid and enabled
* Your account has sufficient balance
* The endpoint is `/v1/chat/completions`
* `Content-Type` is `application/json`
* The model ID is correct
* The request includes a `messages` array
* `"stream": true` is included only when streaming is required

### ➡️ Next Steps

Continue with:

* [**Models and Model IDs**](/models-and-pricing/models-and-model-ids.md) — Find supported text model IDs
* [**Model Pricing and Billing**](/models-and-pricing/model-pricing-and-billing.md) — Understand model-specific billing
* [**Response Modes**](/api-guides/response-modes.md) — Understand standard, streaming, and asynchronous responses
* [**Usage Logs and Costs**](/api-usage/usage-logs-and-costs.md) — Review request usage and costs
* [**HTTP Status Codes and API Errors**](/troubleshooting/http-status-codes-and-api-errors.md) — Troubleshoot API failures