> 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

Learn the core ApiSmart API conventions, including base URLs, API Key authentication, request formats, model IDs, response patterns, and HTTP status codes.

This guide covers the common conventions used across the ApiSmart API, including authentication, request formats, model selection, response patterns, and error handling.

For endpoint-specific parameters and examples, refer to the corresponding API guide.

### 🔗 API Base URL

The standard ApiSmart API Base URL is:

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

Most standard API endpoints are available under the `/v1` path.

For example:

| API              | Full Endpoint                                  |
| ---------------- | ---------------------------------------------- |
| Models           | `https://gw.apismart.ai/v1/models`             |
| Chat Completions | `https://gw.apismart.ai/v1/chat/completions`   |
| Image Generation | `https://gw.apismart.ai/v1/images/generations` |
| Image Edits      | `https://gw.apismart.ai/v1/images/edits`       |
| Video Generation | `https://gw.apismart.ai/v1/video/tasks`        |

Some specialized workflows may use different paths. Always use the endpoint documented in the relevant API guide.

### 🔑 Authentication

ApiSmart uses API Keys to authenticate API requests.

Include your API Key in the `Authorization` header:

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

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

For example:

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

Keep your API Key private and never expose it in public repositories, browser-side code, logs, screenshots, or other publicly accessible locations.

For key management and security recommendations, see [**Create and Manage API Keys**](/welcome-to-apismart/api-keys/create-and-manage-api-keys.md) and [**Secure Your API Keys**](/welcome-to-apismart/api-keys/secure-your-api-keys.md).

### 📦 Request Formats

Most ApiSmart API requests use JSON.

For JSON requests, include:

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

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": "Hello!"
      }
    ]
  }'
```

#### File Uploads

Endpoints that upload local files may use `multipart/form-data` instead of JSON.

For example, the Image Edits API accepts local image files:

```bash
curl https://gw.apismart.ai/v1/images/edits \
  -H "Authorization: Bearer <your-api-key>" \
  -F model="doubao-seedream-5-0" \
  -F image="@image.png" \
  -F prompt="Transform this image into a watercolor painting" \
  -F size="2K" \
  -F response_format="url"
```

When using `curl -F`, curl automatically creates the appropriate multipart request.

Always follow the request format documented for the endpoint you are using.

### 🧩 Model IDs

API requests use the `model` parameter to identify the model that should process the request.

For example:

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

Model IDs must match exactly.

Periods (`.`), hyphens (`-`), version numbers, and other characters must be entered exactly as documented.

For example:

Correct:

`gpt-5.6-sol`

Incorrect:

`gpt-5-6-sol`

Correct:

`doubao-seedance-2-0-fast`

Incorrect:

`doubao_seedance_2_0_fast`

An incorrectly formatted model ID may result in a `503` response.

For the current model list and detailed model ID rules, see [**Models and Model IDs**](/models-and-pricing/models-and-model-ids.md).

### 🔍 Retrieve Available Models

You can retrieve the latest model list with:

`GET /v1/models`

Example:

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

Example response:

```json
{
  "object": "list",
  "data": [
    {
      "id": "doubao-seedream-5-0",
      "object": "model",
      "owned_by": "api-gateway"
    },
    {
      "id": "deepseek-v4-flash",
      "object": "model",
      "owned_by": "api-gateway"
    }
  ]
}
```

Use the value in `data[].id` as the `model` value in supported API requests.

The Models API can return models supported by the platform, but not every model is necessarily enabled for every API Key.

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

`403 model_not_allowed`

For more information, see [**Models and Model IDs**](/models-and-pricing/models-and-model-ids.md).

### 🌐 HTTP Methods

ApiSmart endpoints use standard HTTP methods according to the operation being performed.

Common methods include:

| Method | Typical Use                                   |
| ------ | --------------------------------------------- |
| `GET`  | Retrieve models, task status, or history      |
| `POST` | Create generations, tasks, or other resources |

For example:

`GET /v1/models`

retrieves the available model list, while:

`POST /v1/chat/completions`

creates a Chat Completions request.

Always use the HTTP method specified in the corresponding API guide.

### ↩️ Response Patterns

Different ApiSmart APIs use different response patterns.

| API              | Typical Response Pattern     |
| ---------------- | ---------------------------- |
| Chat Completions | Standard or streaming        |
| Image Generation | Synchronous or SSE streaming |
| Video Generation | Asynchronous task            |

#### Chat Completions

Chat Completions can return a standard response or stream results when:

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

#### Image Generation

Image generation is synchronous by default, meaning the request remains open until generation completes.

Streaming is also available for supported image generation workflows.

#### Video Generation

Video generation is asynchronous.

Creating a video request returns a task ID. Use that ID to query the task until it reaches a final status.

For detailed implementation guidance, see [**Response Modes**](/api-guides/response-modes.md).

### 🎬 Asynchronous Video Tasks

Create a video task with:

`POST /v1/video/tasks`

After the task is created, use:

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

to check its status.

Common task states include:

* `queued`
* `running`
* `succeeded`
* `failed`
* `cancelled`
* `expired`

A successful task can include a generated video URL in the response.

For complete request parameters and video workflows, see [**Video Generation API**](/api-guides/video-generation-api.md).

### ⚠️ HTTP Status Codes

ApiSmart uses standard HTTP status codes together with API-specific error codes.

Common responses include:

| HTTP Status   | Meaning                                               |
| ------------- | ----------------------------------------------------- |
| `400`         | Invalid request or unsupported parameter              |
| `401`         | Invalid API Key                                       |
| `402`         | Insufficient balance                                  |
| `403`         | Access or model permission issue                      |
| `404`         | Requested task or resource not found                  |
| `429`         | Rate limit exceeded                                   |
| `500`         | Internal server error                                 |
| `502` / `504` | Upstream or gateway error                             |
| `503`         | Provider or dependent service temporarily unavailable |

For example:

`401 invalid_api_key`

indicates an authentication issue.

`402 insufficient_quota`

indicates that the account does not have sufficient available balance.

`403 model_not_allowed`

indicates that the selected model is not currently enabled for the API Key or account.

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

### 🔄 Handling Temporary Errors

Some `5xx` responses can indicate temporary upstream, provider, gateway, or dependent-service problems.

Applications should be prepared to handle temporary failures gracefully.

For retryable failures:

* Avoid retrying requests continuously without delay
* Use a reasonable retry strategy such as exponential backoff
* Follow the `Retry-After` header when one is provided
* Keep appropriate logs for troubleshooting

Do not automatically retry requests that fail because of invalid parameters or authentication errors without correcting the underlying issue first.

### 💰 Billing and Usage

Billable API requests are charged according to the pricing rules of the selected model.

Different models can use different billing units, including:

* Tokens
* Generated images
* Video duration
* Generated video tokens
* Resolution-dependent pricing

Do not assume that every ApiSmart API request is billed using the same method.

For model-specific billing rules, see [**Model Pricing and Billing**](/models-and-pricing/model-pricing-and-billing.md).

Use **Usage Logs and Costs** to review actual request consumption and costs.

### ✅ Before Sending a Request

Before making an API request, verify that:

* Your API Key is valid and enabled
* The `Authorization` header is correctly formatted
* The endpoint and HTTP method are correct
* The request uses the required content type
* The model ID is copied exactly
* Your account has sufficient balance
* Your application uses an appropriate timeout for the API being called

These checks can prevent many common API integration issues.

### ➡️ Next Steps

Continue with:

* [**Models and Model IDs**](/models-and-pricing/models-and-model-ids.md) — Find valid model IDs
* [**Model Pricing and Billing**](/models-and-pricing/model-pricing-and-billing.md) — Understand model-specific billing
* [**Chat Completions API**](/api-guides/chat-completions-api.md) — Build with text models
* [**Image Generation API**](/api-guides/image-generation-api.md) — Generate and edit images
* [**Video Generation API**](/api-guides/video-generation-api.md) — Create video workflows
* [**Response Modes**](/api-guides/response-modes.md) — Learn about standard, streaming, and asynchronous responses
* [**HTTP Status Codes and API Errors**](/troubleshooting/http-status-codes-and-api-errors.md) — Troubleshoot API failures