> 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/api-basics.md).

# API Basics

ApiSmart provides a unified API for accessing supported language, image, and video generation models.

This guide explains the API base URL, authentication method, common endpoints, request formats, and basic error handling.

For model-specific parameters, always follow the **Code Example** on the selected model’s details page.

***

### Before You Begin

Make sure you have:

* An active [ApiSmart account](/account-and-wallet/create-and-access-your-account.md#create-an-account)
* Sufficient **Current Balance**
* An enabled **API Token**
* Remaining API key usage allowance
* A valid [Model ID](/models-and-pricing/models-and-model-ids.md#find-the-model-id)

For help selecting a model and locating its Model ID, see [**Choose a Model and Find Its Model ID**](/models-and-pricing/models-and-model-ids.md).

***

### 🌐 API Base URL

Use the following API base URL:

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

When sending HTTP requests directly, append the required endpoint path.

Example:

```
Base URL: https://gw.apismart.ai/v1
Path:     /chat/completions

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

> ⚠️ **Important:** Do not add `/v1` twice when constructing the request URL.

***

### Common API Endpoints

Different model categories use different endpoints and request formats.

| Purpose             | Method | Endpoint                    |
| ------------------- | ------ | --------------------------- |
| Chat completions    | `POST` | `/v1/chat/completions`      |
| Image generation    | `POST` | `/v1/images/generations`    |
| Create a video task | `POST` | `/v1/video/tasks`           |
| Check a video task  | `GET`  | `/v1/video/tasks/{task_id}` |

Always use the endpoint shown in the selected model’s **Code Example**.

***

### 🔑 Authentication

ApiSmart uses Bearer authentication.

Include your **API Token** in the `Authorization` header:

```http
Authorization: Bearer YOUR_API_KEY
```

For requests containing JSON, also include:

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

Complete header example:

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

> 🔐 Keep your API Token in a secure server-side environment. For detailed security guidance, see **Secure Your API Tokens**.

***

### Send a Basic Request

The following cURL example sends a request to a supported language model:

```
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 in the selected model’s **Code Example** or **Quick Integration** section.

***

### Understand the Request

A basic Chat Completions request commonly includes:

| Field      | Description                                            |
| ---------- | ------------------------------------------------------ |
| `model`    | Exact Model ID of the model that processes the request |
| `messages` | Conversation messages sent to the language model       |

Example:

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

Model IDs may be case-sensitive. Do not replace the Model ID with the model’s display name or change its capitalization, underscores, hyphens, or periods.

Additional parameters vary by model.

***

### Request Formats Vary by Model

A unified API does not mean that every model uses the same request body.

| Model Type | Endpoint                 | Typical Request Structure                                                              |
| ---------- | ------------------------ | -------------------------------------------------------------------------------------- |
| Language   | `/v1/chat/completions`   | `messages`                                                                             |
| Image      | `/v1/images/generations` | `prompt` and model-specific fields                                                     |
| Video      | `/v1/video/tasks`        | Model-specific fields such as `content`, `prompt`, `duration`, `resolution`, or `size` |

Video generation uses an asynchronous task workflow. After creating a task, check its status with:

```
GET /v1/video/tasks/{task_id}
```

> ⚠️ **Important:** Always use the exact endpoint, Model ID, field names, and supported values shown in the selected model’s **Code Example**.

For complete request examples, see:

* **Chat Completions API**
* **Image Generation API**
* **Video Generation API**

***

### Read the Response

ApiSmart API responses are generally returned in JSON format.

A successful Chat Completions response may look similar to:

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

Depending on the model and request type, the response may also contain:

* Model information
* Usage information
* Request identifiers
* Generated image or video information
* Task status

The exact response structure varies by model.

When processing a response:

1. Check the HTTP status code.
2. Parse the JSON response.
3. Confirm that the expected result field exists.
4. Handle errors before reading generated content.
5. Save the **Request ID** when troubleshooting.

***

### 🛠️ Common Request Problems

| Problem                   | What to Check                                                         |
| ------------------------- | --------------------------------------------------------------------- |
| **Authentication failed** | API Token status, Bearer header, and complete Token value             |
| **Model not found**       | Exact Model ID, capitalization, punctuation, and model availability   |
| **Invalid request**       | Endpoint, required fields, JSON syntax, and model-specific parameters |
| **Insufficient balance**  | **Wallet → Current Balance** and **API Tokens → Used / Remaining**    |
| **Request timed out**     | Client timeout, temporary model delay, or asynchronous task status    |

Parameter values may also be model-specific. For example, `720p` and `720P` may not be interchangeable.

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 in application logs, screenshots, public repositories, or support messages.

***

### 🚀 Next Steps

Continue with:

* [**Chat Completions API**](/api-guides/chat-completions-api.md)
* [**Image Generation API**](/api-guides/image-generation-api.md)
* [**Video Generation API**](/api-guides/video-generation-api.md)
* [**Streaming Responses**](/api-guides/response-modes.md)
* [**Choose a Model and Find Its Model ID**](/models-and-pricing/models-and-model-ids.md)
* [**View API Usage Logs and Costs**](/api-usage/usage-logs-and-costs.md)