POSThttps://api.wylon.cn/v1/contents/generations/tasks
GEThttps://api.wylon.cn/v1/contents/generations/tasks/{task_id}
DELETEhttps://api.wylon.cn/v1/contents/generations/tasks/{task_id}
异步生成
创建文生视频任务,通过任务 ID 查询状态,并在生成成功后下载短时效 MP4 结果。
鉴权与请求格式
Authorizationstring · header必填
Bearer 令牌。可前往 控制台 创建 API 密钥,并将其保存为环境变量
$WYLON_API_KEY。Content-Typestring · header必填
创建任务时固定为
application/json。确认模型与当前限制
本文使用 lightx2v/LightWan2.2-A14B。可先调用列出模型确认当前 API 密钥能够访问该模型。
| 参数 | 支持值 | 默认值 | 说明 |
|---|---|---|---|
duration | 5 | 5 | 当前固定生成 5 秒视频 |
resolution | 480P、720P | 480P | 输出尺寸由分辨率和画幅共同决定 |
ratio | 16:9、9:16 | 16:9 | 支持横向和纵向画幅 |
negative_prompt | 支持 | 空 | 描述希望模型避开的画面元素或质量问题 |
运行时推理步数和帧率不是 V1 创建任务的公开请求字段。请勿传入 inference_steps 或 fps;实际帧率由成功响应的 framespersecond 返回。
创建视频任务
视频提示词通过 content 数组传递。当前只支持 type=text 的文本内容块。
创建任务
curl -sS --max-time 60 \
-X POST "https://api.wylon.cn/v1/contents/generations/tasks" \
-H "Authorization: Bearer ${WYLON_API_KEY}" \
-H "Content-Type: application/json" \
--data-binary '{
"type": "video",
"model": "lightx2v/LightWan2.2-A14B",
"content": [{
"type": "text",
"text": "一只黑白长毛小猫在阳光下走来,真实电影摄影。"
}],
"duration": 5,
"resolution": "480P",
"ratio": "16:9"
}' -o video-create-response.json
import os
import requests
response = requests.post(
"https://api.wylon.cn/v1/contents/generations/tasks",
headers={"Authorization": f"Bearer {os.environ['WYLON_API_KEY']}"},
json={
"type": "video",
"model": "lightx2v/LightWan2.2-A14B",
"content": [{
"type": "text",
"text": "一只黑白长毛小猫在阳光下走来,真实电影摄影。",
}],
"duration": 5,
"resolution": "480P",
"ratio": "16:9",
},
timeout=60,
)
response.raise_for_status()
task = response.json()
print(task["id"])
const response = await fetch(
"https://api.wylon.cn/v1/contents/generations/tasks",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.WYLON_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
type: "video",
model: "lightx2v/LightWan2.2-A14B",
content: [{ type: "text", text: "一只黑白长毛小猫在阳光下走来,真实电影摄影。" }],
duration: 5,
resolution: "480P",
ratio: "16:9",
}),
},
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const task = await response.json();
console.log(task.id);
创建参数
typestring可选
指定任务生成的内容类型。文生视频请求传入
video;省略时服务端按视频任务处理,建议显式传入以提高请求可读性。contentarray必填
视频生成输入内容块。
typestring必填
指定输入内容块的类型。文生视频请求传入
text。textstring必填
用于描述期望生成内容的文本提示词,可包含主体、动作、场景、镜头、光线和风格等信息。
durationinteger可选
期望生成的视频时长,单位为秒。省略时使用所选模型的默认值;支持的取值及默认值请以对应模型的能力说明为准。
resolutionstring可选
期望输出的分辨率档位。省略时使用所选模型的默认值;支持的取值及对应输出尺寸由模型决定。
ratiostring可选
期望输出的视频画幅比例。省略时使用所选模型的默认值;支持的取值由模型决定。
negative_promptstring可选
描述不希望出现在生成结果中的内容。是否支持及具体效果由所选模型决定。
seedinteger可选
用于控制生成随机性的种子。是否支持、合法取值范围及结果可复现程度由所选模型决定。
safety_identifierstring可选
用于安全追踪的稳定终端用户标识。不要传入姓名、邮箱等直接身份信息。
execution_expires_afterinteger可选
任务执行过期阈值,单位为秒。超过阈值后任务可能停止执行。
查询任务
使用创建响应中的 id 查询任务。设置 detail=true 时,响应包含实际生效的 video_parameters。
查询任务
VIDEO_TASK_ID=$(jq -r '.id' video-create-response.json)
curl -sS --get \
"https://api.wylon.cn/v1/contents/generations/tasks/${VIDEO_TASK_ID}" \
-H "Authorization: Bearer ${WYLON_API_KEY}" \
--data-urlencode "detail=true" \
-o video-task-response.json
import os
import requests
task_id = os.environ["VIDEO_TASK_ID"]
response = requests.get(
f"https://api.wylon.cn/v1/contents/generations/tasks/{task_id}",
headers={"Authorization": f"Bearer {os.environ['WYLON_API_KEY']}"},
params={"detail": "true"},
timeout=30,
)
response.raise_for_status()
task = response.json()
print(task["status"])
const taskId = process.env.VIDEO_TASK_ID;
const url = new URL(
`https://api.wylon.cn/v1/contents/generations/tasks/${taskId}`,
);
url.searchParams.set("detail", "true");
const response = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.WYLON_API_KEY}` },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const task = await response.json();
console.log(task.status);
| 状态 | 含义 | 建议操作 |
|---|---|---|
queued | 任务已受理,等待执行 | 稍后继续查询 |
running | 视频正在生成 | 稍后继续查询 |
succeeded | 任务成功 | 获取并下载视频 |
failed | 任务执行失败 | 读取 error |
cancelled | 排队任务已取消 | 停止轮询 |
expired | 任务或结果已过期 | 需要时重新创建任务 |
读取并下载结果
status=succeeded 且 file_status=available 时,视频地址位于 content.video_url。
成功结果
{
"id": "9065e7fd-2845-4e26-8850-1cf49a5d57c5",
"status": "succeeded",
"type": "video",
"content": {
"type": "video_url",
"video_url": "https://example.com/generated/output.mp4?signature=REDACTED",
"video_url_expires_at": 1788853117
},
"file_status": "available",
"model": "lightx2v/LightWan2.2-A14B",
"duration": 5,
"resolution": "480P",
"ratio": "16:9",
"framespersecond": 16,
"width": 832,
"height": 480,
"output_format": "mp4",
"watermark": true
}下载结果
VIDEO_URL=$(jq -r '.content.video_url // empty' video-task-response.json)
curl -L --fail --show-error "${VIDEO_URL}" -o generated-video.mp4
import json
import requests
with open("video-task-response.json", encoding="utf-8") as file:
video_url = json.load(file)["content"]["video_url"]
with requests.get(video_url, stream=True, timeout=300) as response:
response.raise_for_status()
with open("generated-video.mp4", "wb") as file:
for chunk in response.iter_content(1024 * 1024):
file.write(chunk)
import { readFile, writeFile } from "node:fs/promises";
const task = JSON.parse(
await readFile("video-task-response.json", "utf8"),
);
const response = await fetch(task.content.video_url);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
await writeFile(
"generated-video.mp4",
Buffer.from(await response.arrayBuffer()),
);
签名 URL 已包含短时效访问凭证,下载时通常不需要再次发送 wylon API Key。不要记录或公开完整签名 URL。
取消或删除任务
cURL:取消或删除
curl -sS -X DELETE \
"https://api.wylon.cn/v1/contents/generations/tasks/${VIDEO_TASK_ID}" \
-H "Authorization: Bearer ${WYLON_API_KEY}"queued:取消排队中的任务。running:运行中的任务不能取消。succeeded、failed、expired:删除任务记录。cancelled:不能再次操作。
删除任务记录或取消任务可能不可恢复。调用前应确认任务 ID 和当前状态。
错误处理与生产建议
| 状态码 | 常见原因 | 建议操作 |
|---|---|---|
400 | 字段类型错误或模型不支持指定参数 | 根据当前模型限制修正请求 |
401、403 | 密钥无效或没有模型、任务权限 | 检查鉴权与账户权限 |
404 | 模型或任务不存在 | 检查完整模型 ID、任务 ID 和调用环境 |
429 | 请求频率、并发或容量达到限制 | 降低请求频率并稍后重试 |
500、503 | 服务内部错误或模型暂不可用 | 创建成功后优先查询原任务 |
- 使用逐步增加并带随机抖动的轮询间隔。
- 为客户端轮询设置最大持续时间;停止轮询不会取消服务端任务。
- 创建任务已经返回
id后,不要重复提交 POST。 - 任务成功后及时下载视频,不把短时效 URL 当作长期业务资源地址。
