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

# 视频生成任务

> 创建异步视频任务，轮询状态并读取生成结果。

视频生成使用异步任务：先创建任务，再使用任务 ID 查询进度。

![APIONE 网页端视频生成页面](https://mintcdn.com/apione/pAFvFGkbmcRZirTZ/images/ui/video-generation.png?fit=max\&auto=format\&n=pAFvFGkbmcRZirTZ\&q=85\&s=01c9b361e3ef5f277714db390eaf454b)

网页端视频生成集中设置生成模式、模型、画幅、分辨率和时长。

![APIONE 模型广场视频模型列表](https://mintcdn.com/apione/Vq80XJbufibzxH8S/images/ui/video-models.png?fit=max\&auto=format\&n=Vq80XJbufibzxH8S\&q=85\&s=aa78153e9c538a0c208b543ba975fb3f)

模型广场的视频分类展示可用视频模型、计费单位、输入输出类型和渠道。

提交前先查询当前 Key 的 `/v1/models`，确认列表包含目标视频模型，并核对该模型的创建、状态和结果字段。列表没有视频模型时，先在控制台检查 Key 分组与权限，不要使用其他渠道的模型 ID 或响应格式代替。

## 运行示例前准备

安装 Python 3，并在运行脚本的同一个 Python 环境安装依赖：

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

如果你的系统使用 `python3`，安装和运行时都使用 `python3`。Windows 也可以对应使用 `py -m pip install requests` 与 `py example.py`。使用虚拟环境时，先激活环境。

在 [API 密钥页](https://apione.ai/zh/app/api-keys)创建密钥，从[当前 Key 可用的模型列表](https://apione.ai/docs/models/catalog.md)复制支持视频生成的模型 ID，然后在运行脚本的终端设置变量。下面的大写值是占位符，需要替换。

> [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"
> ```

变量只对当前终端及其启动的子进程生效。在同一终端运行后面的示例；IDE、容器或新终端需要另行配置。不要把真实密钥提交到代码仓库。

## 1. 查询模型参数

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

确认模型支持的生成模式，以及时长、画幅、分辨率、参考素材等字段。

## 2. 创建任务

```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": "雨后的城市街道，镜头缓慢向前移动"
  }'
```

保存响应中的任务 ID。创建接口成功只表示任务已接收，不表示视频已经生成。

## 3. 查询状态

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

根据响应状态继续等待、读取结果或处理失败。轮询应设置间隔和总时限，不要高频连续请求。

## 4. 获取结果

任务完成后，从状态响应读取结果地址或结果对象。下载后在自己的存储中保存；结果地址的有效期以实际响应和模型规则为准。

## 失败处理

* 参数错误：查询模型参数，修正字段后重新创建。
* 内容拒绝：调整提示词或参考素材。
* 上游失败：记录任务 ID 与请求 ID，在合理等待后有限次数重试。
* 状态长期不变：停止高频轮询，携带任务 ID 联系支持。

> [!WARNING]
>
> 任务状态未知时不要直接重复创建，避免产生重复视频和重复费用。

## 任务生命周期

| 阶段 | 应用要做什么 | 不应做什么 |
| - | - | - |
| 提交前 | 校验模型、参数、余额与素材 | 用其他模型的参数直接提交 |
| 创建成功 | 保存任务 ID、请求 ID 和创建时间 | 把“已接收”展示成“已完成” |
| 等待中 | 按间隔查询，向用户显示处理中 | 毫秒级高频轮询 |
| 成功 | 下载结果并保存到自己的存储 | 长期依赖临时结果地址 |
| 失败 | 展示可操作原因，判断是否可重试 | 对参数错误自动无限重试 |
| 超时 | 停止轮询，保留任务信息供查询 | 立即重复创建多个任务 |

## Python 创建示例

```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": "雨后的城市街道，镜头缓慢向前移动",
    },
    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()
```

创建后从实际响应中找到任务 ID。不同模型或接口版本的包装层可能不同，第一次接入时先保存完整响应，再确定解析路径。

## Node.js 查询示例

使用 Node.js 18 或更高版本（内置 `fetch`）。在创建请求的响应中找到实际任务 ID，设置 `APIONE_VIDEO_TASK_ID` 后再查询；它与模型 ID、请求跟踪 ID 不同。查询时沿用创建任务使用的 API Key。

```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"
```

将下面的 JavaScript 代码保存为 `example.mjs`。在已设置本页所需环境变量的同一终端运行 `node example.mjs`。使用 Node.js 18 或更高版本，内置 `fetch` 无需额外依赖。

```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);
```

## 轮询策略

应用应设置固定或逐步增加的间隔，并设置最大等待时间。例如首次等待数秒，再根据任务耗时逐步降低查询频率。若状态响应提供建议等待时间，优先采用响应值。

轮询代码需要处理：网络失败、429、5xx、未知状态、用户取消、页面刷新和服务重启。任务 ID 应持久化，不能只放在浏览器内存中。

## 结果下载

任务完成后先检查结果对象是否存在，再下载文件。下载完成后验证 HTTP 状态、文件大小、媒体类型、实际时长和能否解码。需要 MOV 时，如果模型只返回 MP4，应在自己的处理链中转码，而不是只修改扩展名。

## 批量生成建议

* 先单条验证，再逐步增加并发。
* 每个业务任务使用自己的本地 ID 和状态机。
* 限制账户级并发，避免媒体任务挤占文本请求。
* 记录每个任务的模型、参数摘要、费用和结果路径。
* 对失败任务分类统计：参数、内容审核、上游、超时、下载失败。

下一步：[媒体参数与计费](https://apione.ai/docs/api/media-parameters.md)、[请求跟踪、超时与重试](https://apione.ai/docs/api/request-reliability.md)、[错误码与排查](https://apione.ai/docs/support/errors.md)。


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