Video generation tasks

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

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

APIONE model marketplace video model list — 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:

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, copy a model ID that supports video generation from the available model list, then set the variables in the terminal where you will run the script. The uppercase values below are placeholders to replace.

macOS / Linux
Windows PowerShell

export APIONE_API_KEY="YOUR_APIONE_API_KEY"
export APIONE_VIDEO_MODEL="YOUR_VIDEO_MODEL"

$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

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

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

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.

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

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.

export APIONE_VIDEO_TASK_ID="YOUR_VIDEO_TASK_ID"

$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.

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, Request reliability, Troubleshooting.

Addresses and authentication

Model APIs

Output and advanced usage

Image APIs

Video APIs

Video generation tasks

Before running examples

1. Query model parameters

2. Create a task

3. Query status

4. Get the result

Failure handling

Task lifecycle

Python create example

Node.js query example

Polling strategy

Result download

Batch generation suggestions