> ## Documentation Index
> Fetch the complete documentation index at: https://apione.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Video generation tasks

> Create an asynchronous video task, poll status, and store the result.

Video generation uses asynchronous tasks: first create a task, then query progress using the task ID.

![APIONE web video generation page](https://mintcdn.com/apione/pAFvFGkbmcRZirTZ/images/ui/video-generation.png?fit=max\&auto=format\&n=pAFvFGkbmcRZirTZ\&q=85\&s=01c9b361e3ef5f277714db390eaf454b)

APIONE web video generation settings for generation mode, model, aspect ratio, resolution, and duration.

![APIONE model marketplace video model list](https://mintcdn.com/apione/Vq80XJbufibzxH8S/images/ui/video-models.png?fit=max\&auto=format\&n=Vq80XJbufibzxH8S\&q=85\&s=aa78153e9c538a0c208b543ba975fb3f)

The video category in the model marketplace shows available video models, billing units, input/output types, and channels.

Before submitting, query `/v1/models` with your current key and confirm that the list contains the target video model. Also verify the model's create, status, and result fields. If no video model is listed, first check the key group and permissions in the console; do not use another gateway's model ID or response format as a substitute.

## Before running examples

Install Python 3, then install the dependency with the same interpreter that will run the example:

```bash theme={null}
python -m pip install requests
```

If your system uses `python3`, use `python3` for both installation and execution. Windows users can use `py -m pip install requests` and `py example.py`. Activate your virtual environment first, if applicable.

Create a key on the [API Keys page](https://apione.ai/en/app/api-keys), copy a model ID that supports video generation from the [available model list](https://apione.ai/docs/en/models/catalog.md), then set the variables in the terminal where you will run the script. The uppercase values below are placeholders to replace.

> [tab] macOS / Linux
>
> ```bash theme={null}
> export APIONE_API_KEY="YOUR_APIONE_API_KEY"
> export APIONE_VIDEO_MODEL="YOUR_VIDEO_MODEL"
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={null}
> $env:APIONE_API_KEY = "YOUR_APIONE_API_KEY"
> $env:APIONE_VIDEO_MODEL = "YOUR_VIDEO_MODEL"
> ```

Variables only apply to the current terminal and child processes it starts. Run the examples in the same terminal; IDEs, containers, and new terminals need separate configuration. Do not commit real keys to source control.

## 1. Query model parameters

```bash theme={null}
curl https://api.apione.ai/v1/models/YOUR_VIDEO_MODEL/params \
  -H "Authorization: Bearer YOUR_APIONE_API_KEY"
```

Confirm the generation modes supported by the model, as well as fields for duration, aspect ratio, resolution, reference material, etc.

## 2. Create a task

```bash theme={null}
curl https://api.apione.ai/v1/videos \
  -H "Authorization: Bearer YOUR_APIONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_VIDEO_MODEL",
    "prompt": "A city street after rain, camera moving slowly forward"
  }'
```

Save the task ID from the response. A successful create response only means the task was accepted, not that the video has already been generated.

## 3. Query status

```bash theme={null}
curl https://api.apione.ai/v1/videos/YOUR_VIDEO_TASK_ID \
  -H "Authorization: Bearer YOUR_APIONE_API_KEY"
```

Continue waiting, read the result, or handle failure according to the response status. Polling should use intervals and a total deadline; do not make high-frequency continuous requests.

## 4. Get the result

After the task completes, read the result address or result object from the status response. Download and save it to your own storage; the validity period of result addresses depends on the actual response and model rules.

## Failure handling

* Parameter error: query model parameters, correct fields, and recreate.
* Content rejection: adjust prompt or reference material.
* Upstream failure: record task ID and request ID, retry a limited number of times after reasonable waiting.
* Status unchanged for a long time: stop high-frequency polling and contact support with the task ID.

> [!WARNING]
>
> Do not directly repeat creation while the task status is unknown, to avoid duplicate videos and duplicate charges.

## Task lifecycle

| Stage | What the application should do | What it should not do |
| - | - | - |
| Before submit | Validate model, parameters, balance, and material | Submit using another model's parameters directly |
| Create success | Save task ID, request ID, and creation time | Display "accepted" as "completed" |
| Waiting | Query at intervals, show "processing" to the user | Millisecond-level high-frequency polling |
| Success | Download result and save to your own storage | Rely on temporary result addresses long-term |
| Failed | Show actionable reason, determine whether retryable | Auto-retry infinitely for parameter errors |
| Timeout | Stop polling, retain task information for inquiry | Immediately create multiple duplicate tasks |

## Python create example

```python theme={null}
import os
import requests

response = requests.post(
    "https://api.apione.ai/v1/videos",
    headers={
        "Authorization": f"Bearer {os.environ['APIONE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": os.environ["APIONE_VIDEO_MODEL"],
        "prompt": "A city street after rain, camera moving slowly forward",
    },
    timeout=120,
)
print("status:", response.status_code)
print("request-id:", {name: response.headers[name] for name in ("X-Request-ID", "X-Maxx-Trace-Id", "X-Maxx-Request-ID") if name in response.headers})
print(response.text)
response.raise_for_status()
```

Find the task ID from the actual response after creation. Different models or interface versions may have different wrapper layers; when integrating for the first time, save the full response first, then determine the parsing path.

## Node.js query example

Use Node.js 18 or higher (built-in `fetch`). Find the actual task ID from the create response, set `APIONE_VIDEO_TASK_ID`, then query; it is different from the model ID and request trace ID. Use the same API Key that created the task when querying.

```bash macOS / Linux theme={null}
export APIONE_VIDEO_TASK_ID="YOUR_VIDEO_TASK_ID"
```

```powershell Windows PowerShell theme={null}
$env:APIONE_VIDEO_TASK_ID = "YOUR_VIDEO_TASK_ID"
```

Save the JavaScript below as `example.mjs`. Run `node example.mjs` in the same terminal where this page's environment variables are set. Node.js 18 or higher with built-in `fetch` requires no extra dependencies.

```javascript theme={null}
const taskId = process.env.APIONE_VIDEO_TASK_ID;
const response = await fetch(`https://api.apione.ai/v1/videos/${encodeURIComponent(taskId)}`, {
  headers: { Authorization: `Bearer ${process.env.APIONE_API_KEY}` },
});

console.log("status:", response.status);
console.log("request-id:", Object.fromEntries(["X-Request-ID", "X-Maxx-Trace-Id", "X-Maxx-Request-ID"].map(name => [name, response.headers.get(name)]).filter(([, value]) => value)));
const task = await response.json();
if (!response.ok) throw new Error(JSON.stringify(task));
console.log(task);
```

## Polling strategy

The application should set fixed or gradually increasing intervals, and a maximum wait time. For example, wait a few seconds first, then reduce query frequency according to task duration. If the status response provides a suggested wait time, prefer that value.

Polling code needs to handle: network failures, 429, 5xx, unknown statuses, user cancellation, page refresh, and service restart. Task IDs should be persisted; do not keep them only in browser memory.

## Result download

After the task completes, first check whether the result object exists, then download the file. After downloading, verify HTTP status, file size, media type, actual duration, and decodability. If MOV is needed but the model only returns MP4, transcode in your own processing pipeline rather than just changing the extension.

## Batch generation suggestions

* Validate with a single request first, then gradually increase concurrency.
* Use your own local ID and state machine for each business task.
* Limit account-level concurrency to avoid media tasks crowding out text requests.
* Record the model, parameter summary, cost, and result path for each task.
* Classify failed tasks: parameters, content moderation, upstream, timeout, download failure.

Next: [Media parameters](https://apione.ai/docs/en/api/media-parameters.md), [Request reliability](https://apione.ai/docs/en/api/request-reliability.md), [Troubleshooting](https://apione.ai/docs/en/support/errors.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.