> 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/code-examples-and-migration/curl.md).

# cURL

Learn how to call ApiSmart APIs with cURL, including model discovery, text generation, image generation, local image uploads, streaming, and asynchronous video tasks.

cURL is a command-line tool for sending HTTP requests and is one of the fastest ways to test the ApiSmart API.

This guide shows how to authenticate requests, retrieve available models, and call text, image, and video APIs directly from your terminal.

### 🚀 Before You Start

Make sure you have:

* An ApiSmart account
* An active API Key
* Sufficient wallet balance for paid requests
* cURL installed on your system

You can verify that cURL is available with:

```bash
curl --version
```

### 🔑 Set Your API Key

ApiSmart uses Bearer authentication.

You can place your API Key directly in a request:

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

For local testing, you can also store the key in an environment variable instead of repeating it in every command.

#### macOS and Linux

```bash
export APISMART_API_KEY="your-api-key"
```

Then use:

```bash
-H "Authorization: Bearer $APISMART_API_KEY"
```

#### Windows PowerShell

```powershell
$env:APISMART_API_KEY="your-api-key"
```

Then use:

```powershell
-H "Authorization: Bearer $env:APISMART_API_KEY"
```

Keep your API Key private and do not include it in public repositories, screenshots, or shared command history.

### 🔗 API Base URL

The standard ApiSmart API Base URL is:

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

Most examples in this guide use the full endpoint URL so they can be copied and tested directly.

### 🧩 Get Available Models

Before sending a generation request, you can retrieve the latest model IDs with:

```bash
curl https://gw.apismart.ai/v1/models \
  -H "Authorization: Bearer $APISMART_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 returned `data[].id` value as the `model` parameter in supported requests.

> **Model IDs must match exactly.**\
> Periods (`.`), hyphens (`-`), and version numbers must be copied exactly as returned or documented.

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

### 💬 Chat Completions

Use:

```
POST /v1/chat/completions
```

Example:

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

For complete request behavior, see [**Chat Completions API**](/api-guides/chat-completions-api.md).

### 🌊 Stream a Text Response

Add:

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

to the request body:

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

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

### 🖼️ Generate an Image

Use:

```
POST /v1/images/generations
```

Example:

```bash
curl https://gw.apismart.ai/v1/images/generations \
  -H "Authorization: Bearer $APISMART_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 120 \
  -d '{
    "model": "doubao-seedream-5-0",
    "prompt": "A mountain village at sunrise, watercolor style",
    "size": "2K",
    "watermark": false
  }'
```

Image generation is synchronous by default and may take longer than a typical text request.

Set your client timeout to at least **90 seconds**. The example above uses `--max-time 120` to provide additional time for generation.

For image parameters and supported workflows, see [**Image Generation API**](/api-guides/image-generation-api.md).

### 🔄 Generate from a Reference Image

Pass a public image URL using `image`:

```bash
curl https://gw.apismart.ai/v1/images/generations \
  -H "Authorization: Bearer $APISMART_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 120 \
  -d '{
    "model": "doubao-seedream-5-0",
    "prompt": "Transform this image into a watercolor painting",
    "image": "https://example.com/input.jpg",
    "size": "2048x2048"
  }'
```

Multiple image URLs can also be provided as an array where supported.

### 📤 Upload a Local Image

To upload a local image file, use:

```
POST /v1/images/edits
```

This endpoint uses multipart form data instead of a JSON request body.

```bash
curl https://gw.apismart.ai/v1/images/edits \
  -H "Authorization: Bearer $APISMART_API_KEY" \
  -F model="doubao-seedream-5-0" \
  -F image="@character.png" \
  -F prompt="Place the character in a cyberpunk environment" \
  -F size="2K" \
  -F response_format="url"
```

With `-F`, cURL automatically creates the multipart request.

Each uploaded image file must meet the limits documented in [**Image Generation API**](/api-guides/image-generation-api.md).

### 🌊 Stream Image Generation

Supported image workflows can use SSE streaming.

When using cURL, add `-N` to prevent output buffering:

```bash
curl https://gw.apismart.ai/v1/images/generations \
  -H "Authorization: Bearer $APISMART_API_KEY" \
  -H "Content-Type: application/json" \
  -N \
  --max-time 120 \
  -d '{
    "model": "doubao-seedream-5-0",
    "prompt": "Create a minimalist product design sequence",
    "size": "2K",
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": {
      "max_images": 4
    },
    "stream": true
  }'
```

For supported streaming workflows, see [**Image Generation API**](/api-guides/image-generation-api.md) and [**Response Modes**](/api-guides/response-modes.md).

### 🎬 Create a Video Task

Video generation is asynchronous.

Create a task with:

```
POST /v1/video/tasks
```

Example:

```bash
curl https://gw.apismart.ai/v1/video/tasks \
  -H "Authorization: Bearer $APISMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0",
    "prompt": "A miniature city at night with a train moving through the streets",
    "duration": 5,
    "size": "720p"
  }'
```

The response returns a task ID that you can use to check generation status.

> For video models where `resolution` and `duration` affect billing, specify them explicitly rather than relying on default values.

### 🔄 Check Video Task Status

After creating a task, query it with:

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

Example:

```bash
curl https://gw.apismart.ai/v1/video/tasks/<task_id> \
  -H "Authorization: Bearer $APISMART_API_KEY"
```

Common task statuses include:

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

Continue polling while the task is `queued` or `running`.

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

### 🕘 Retrieve Recent Generated Media

You can also use cURL to retrieve recent generated media.

#### Images

```bash
curl "https://gw.apismart.ai/v1/images?page=1&page_size=20" \
  -H "Authorization: Bearer $APISMART_API_KEY"
```

#### Videos

```bash
curl "https://gw.apismart.ai/v1/videos?page=1&page_size=20" \
  -H "Authorization: Bearer $APISMART_API_KEY"
```

For field definitions and history limits, see [**Generated Media History**](/api-usage/generated-media-history.md).

### 🛠️ Common cURL Options

| Option       | Purpose                                       |
| ------------ | --------------------------------------------- |
| `-H`         | Add an HTTP request header                    |
| `-d`         | Send a request body                           |
| `-F`         | Send multipart form data or upload files      |
| `-N`         | Disable output buffering for streaming        |
| `--max-time` | Set the maximum request duration              |
| `-X`         | Explicitly specify an HTTP method when needed |

For most JSON `POST` requests using `-d`, cURL automatically sends a POST request, so `-X POST` is usually optional.

### ⚠️ Common Errors

#### `401 invalid_api_key`

Check that the API Key is valid and that the request includes:

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

#### `402 insufficient_quota`

Your account does not have sufficient available balance.

#### `403 model_not_allowed`

The selected model is not currently available to your API Key or account.

#### `400 unsupported_resolution`

The requested resolution is not supported by the selected video model.

#### `503`

A `503` can indicate a temporary service issue.

If it occurs after selecting a model, also verify that the model ID is written exactly as documented.

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

### ✅ Quick cURL Checklist

Before sending a request, verify that:

* Your API Key is active
* The `Authorization` header uses `Bearer`
* The endpoint is correct
* JSON requests include `Content-Type: application/json`
* The model ID is copied exactly
* File uploads use `-F` instead of a JSON body
* Image requests use an appropriate timeout
* Video workflows poll the returned task ID
* Your wallet has sufficient balance

### ➡️ Next Steps

Continue with:

* [**API Basics**](/api-guides/api-basics.md) — Learn common API conventions
* [**Models and Model IDs**](/models-and-pricing/models-and-model-ids.md) — Find valid model IDs
* [**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 asynchronous video tasks
* [**Response Modes**](/api-guides/response-modes.md) — Understand standard, streaming, and asynchronous behavior
* [**Generated Media History**](/api-usage/generated-media-history.md) — Retrieve recent generated images and videos