视频生成任务

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

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

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

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

运行示例前准备

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

python -m pip install requests

如果你的系统使用 python3，安装和运行时都使用 python3。Windows 也可以对应使用 py -m pip install requests 与 py example.py。使用虚拟环境时，先激活环境。在 API 密钥页创建密钥，从当前 Key 可用的模型列表复制支持视频生成的模型 ID，然后在运行脚本的终端设置变量。下面的大写值是占位符，需要替换。

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"

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

1. 查询模型参数

curl https://api.apione.ai/v1/models/YOUR_VIDEO_MODEL/params \
  -H "Authorization: Bearer YOUR_APIONE_API_KEY"

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

2. 创建任务

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. 查询状态

curl https://api.apione.ai/v1/videos/YOUR_VIDEO_TASK_ID \
  -H "Authorization: Bearer YOUR_APIONE_API_KEY"

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

4. 获取结果

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

失败处理

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

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

任务生命周期

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

Python 创建示例

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。

export APIONE_VIDEO_TASK_ID="YOUR_VIDEO_TASK_ID"

$env:APIONE_VIDEO_TASK_ID = "YOUR_VIDEO_TASK_ID"

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

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 和状态机。
限制账户级并发，避免媒体任务挤占文本请求。
记录每个任务的模型、参数摘要、费用和结果路径。
对失败任务分类统计：参数、内容审核、上游、超时、下载失败。

下一步：媒体参数与计费、请求跟踪、超时与重试、错误码与排查。

地址与鉴权

模型接口

输出与进阶用法

图像 API

视频 API

视频生成任务

运行示例前准备

1. 查询模型参数

2. 创建任务

3. 查询状态

4. 获取结果

失败处理

任务生命周期

Python 创建示例

Node.js 查询示例

轮询策略

结果下载

批量生成建议