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

# Video Generation API

Use the Video Generation API to create videos with supported ApiSmart video models.

Video generation is asynchronous: create a task first, then use the returned **task ID** to check its status until generation succeeds or fails.

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

***

### API Endpoints

#### Create a Video Task

```
POST https://gw.apismart.ai/v1/video/tasks
```

#### Check Task Status

```
GET https://gw.apismart.ai/v1/video/tasks/{task_id}
```

Required headers:

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

> ⚠️ **Important:** Video models may use different request fields and supported values. Always follow the selected model’s **Code Example**.

***

### How Video Generation Works

A typical workflow is:

```
Create Video Task
       ↓
Receive Task ID
       ↓
Check Task Status
       ↓
Retrieve Generated Video
```

The initial request normally creates the task rather than returning the completed video immediately.

***

### Create a Video Task

Request structures vary by model.

Some models may use a `content` array:

```json
{
  "model": "YOUR_MODEL_ID",
  "content": [
    {
      "type": "text",
      "text": "A cat running on the beach at sunset"
    }
  ],
  "duration": 4,
  "resolution": "720p"
}
```

Other models may use fields such as `prompt`, `duration`, and `size`:

```json
{
  "model": "YOUR_MODEL_ID",
  "prompt": "A miniature city at night",
  "duration": 5,
  "size": "720P"
}
```

Do not assume that fields such as `content` and `prompt`, or `resolution` and `size`, are interchangeable.

***

### Common Request Fields

Available parameters depend on the selected model.

| Field                 | Description                                        |
| --------------------- | -------------------------------------------------- |
| `model`               | Exact Model ID to use                              |
| `prompt`              | Text prompt used by some video models              |
| `content`             | Structured text or media input used by some models |
| `duration`            | Requested video duration                           |
| `resolution` / `size` | Output resolution or size                          |
| `ratio`               | Aspect ratio, where supported                      |
| `watermark`           | Watermark setting, where supported                 |

Models may also support image, video, audio, or other reference inputs.

Use only the fields and values shown in the model’s **Code Example**.

***

### Check the Task Status

After creating a task, save the returned task ID:

```python
task_id = result["id"]
```

Then check its status:

```python
import requests

response = requests.get(
    f"https://gw.apismart.ai/v1/video/tasks/{task_id}",
    headers={
        "Authorization": f"Bearer {api_key}"
    },
    timeout=60,
)

response.raise_for_status()
result = response.json()

print(result.get("status"))
```

A task may return a status such as:

```
processing
succeeded
failed
```

Continue checking at a reasonable interval until the task reaches a final status.

A successful response may include the generated video URL in a model-specific response field.

***

### Understand Video Billing

Video pricing may depend on:

* Generated duration
* Resolution
* Input type
* Model version
* Other model-specific settings

For example:

```
720P:  $0.145/s
1080P: $0.24/s
```

Always review the selected model’s **Price Configuration** before creating a high-volume workload.

For details, see **Understand Model Pricing and Billing**.

***

### 🛠️ 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 parameter names              |
| **Unsupported value**       | Duration, resolution, ratio, or other supported options         |
| **Task remains processing** | Wait and continue checking at a reasonable interval             |
| **Task failed**             | Error message, request fields, balance, and API Token allowance |

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

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

> 🔐 Never provide your full API Token to support.

***

### 🚀 Next Steps

Continue with:

* [**Choose a Model and Find Its Model ID**](/models-and-pricing/models-and-model-ids.md)
* [**Understand Model Pricing and Billing**](/models-and-pricing/model-pricing-and-billing.md)
* [**Image Generation API**](/api-guides/image-generation-api.md)
* [**Usage Logs and Costs**](/api-usage/usage-logs-and-costs.md)