> 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

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

Specify the exact **Model ID**, send a list of conversation messages, and receive the generated response in JSON format.

For the API Base URL, authentication, and general request rules, see [**API Basics**](/api-guides/api-basics.md).

***

### API Endpoint

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

Required headers:

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

> ⚠️ **Important:** Always use the exact Model ID and supported request fields shown in the selected model’s **Code Example**.

***

### Send a Basic Request

The following cURL example sends a simple user message:

```bash
curl https://gw.apismart.ai/v1/chat/completions \
  -H "Authorization: Bearer $APISMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "Explain ApiSmart in one sentence."
      }
    ]
  }'
```

Replace `YOUR_MODEL_ID` with the exact Model ID shown on the selected model’s details page.

***

### Understand the Request

A basic request commonly contains:

| Field      | Description                             |
| ---------- | --------------------------------------- |
| `model`    | Exact Model ID to use                   |
| `messages` | Conversation messages sent to the model |

Example:

```json
{
  "model": "YOUR_MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "Hello!"
    }
  ]
}
```

Each message normally includes:

* `role` — identifies the message sender
* `content` — contains the message sent to the model

Common roles may include:

```
system
user
assistant
```

Available roles and message formats may vary by model.

***

### Optional Parameters

Some models may support additional fields such as:

```json
{
  "temperature": 0.7,
  "max_tokens": 500
}
```

Models may also provide model-specific reasoning, multimodal, or generation parameters.

Do not assume that every language model supports the same fields or values. Review the selected model’s **Code Example** before adding optional parameters.

***

### Read the Response

A successful response may look similar to:

```json
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Generated response"
      }
    }
  ]
}
```

The generated text is commonly available under:

```
choices[0].message.content
```

Depending on the model, the response may also include:

* Model information
* Usage information
* Finish reason
* Request identifiers

The exact response structure may vary.

***

### Python Example

```python
import os
import requests

api_key = os.getenv("APISMART_API_KEY")

if not api_key:
    raise RuntimeError("APISMART_API_KEY is not set.")

response = requests.post(
    "https://gw.apismart.ai/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "model": "YOUR_MODEL_ID",
        "messages": [
            {
                "role": "user",
                "content": "Explain ApiSmart in one sentence.",
            }
        ],
    },
    timeout=120,
)

response.raise_for_status()

result = response.json()
print(result["choices"][0]["message"]["content"])
```

***

### Streaming Responses

Supported models may allow responses to be returned incrementally by adding:

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

Streaming support varies by model.

For implementation details, see [**Streaming Responses**](/api-guides/streaming-responses.md).

***

### 🛠️ Common Problems

| Problem                   | What to Check                                     |
| ------------------------- | ------------------------------------------------- |
| **Authentication failed** | API Token status and Bearer header                |
| **Model not found**       | Exact Model ID and capitalization                 |
| **Invalid request**       | Required fields and model-specific parameters     |
| **Insufficient balance**  | Current Balance and API Token remaining allowance |
| **Unsupported parameter** | Whether the selected model supports the field     |

When troubleshooting, review the related request in [**Usage Logs and Costs**](/api-usage/usage-logs-and-costs.md) and save the **Request ID** when available.

> 🔐 Never provide your full API Token to support.

***

### 🚀 Next Steps

Continue with:

* [**Streaming Responses**](/api-guides/streaming-responses.md)
* [**Choose a Model and Find Its Model ID**](/models-and-pricing/choose-a-model-and-find-its-model-id.md)
* [**Understand Model Pricing and Billing**](/models-and-pricing/understand-model-pricing-and-billing.md)
* [**Usage Logs and Costs**](/api-usage/usage-logs-and-costs.md)