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}
异步视频生成
同一异步任务接口支持文生视频、首帧/尾帧/首尾帧图生音视频(FL2VA)和全模态参考生音视频(Ref2VA)。创建后通过任务 ID 查询状态并下载 MP4 结果。
鉴权与请求格式
Authorizationstring · header必填
Bearer 令牌。可前往 控制台 创建 API 密钥,并将其保存为环境变量
$WYLON_API_KEY。Content-Typestring · header必填
创建任务时固定为
application/json。确认模型能力
FL2VA 与 Ref2VA 使用独立模型。可先调用列出模型确认当前 API 密钥能够访问目标模型。
| 模型 ID | 生成能力 | 支持输入 |
|---|---|---|
MiniMaxAI/MiniMax-H3 | 文生视频,首帧、尾帧或首尾帧图生音视频 | 文本、0~2 张图片 |
MiniMaxAI/MiniMax-H3-Ref2VA | 全模态参考生音视频 | 文本 + 至少一张参考图片或一段参考视频;可同时添加参考音频 |
| 参数 | FL2VA | Ref2VA | 默认值 |
|---|---|---|---|
duration | 5~15 秒 | 5~15 秒 | 5 |
resolution | 768P | 768P | 768P |
ratio | 21:9、16:9、4:3、1:1、3:4、9:16、自适应 | 21:9、16:9、4:3、1:1、3:4、9:16 | 16:9;FL2VA 带图片时自适应 |
创建视频任务
提示词和参考媒体统一通过 content 数组传递。每次请求必须且只能包含一个非空 type=text 内容块。以下示例使用一张首帧图片创建 FL2VA 任务。
创建任务
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": "MiniMaxAI/MiniMax-H3",
"content": [
{"type": "text", "text": "镜头缓慢向前推进,人物在微风中自然回头,画面保持电影感。"},
{"type": "image_url", "image_url": {"url": "https://example.com/first-frame.jpg"}, "role": "first_frame"}
],
"duration": 5,
"resolution": "768p",
"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": "MiniMaxAI/MiniMax-H3",
"content": [
{"type": "text", "text": "镜头缓慢向前推进,人物在微风中自然回头,画面保持电影感。"},
{"type": "image_url", "image_url": {"url": "https://example.com/first-frame.jpg"}, "role": "first_frame"},
],
"duration": 5,
"resolution": "768p",
"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: "MiniMaxAI/MiniMax-H3",
content: [
{ type: "text", text: "镜头缓慢向前推进,人物在微风中自然回头,画面保持电影感。" },
{ type: "image_url", image_url: { url: "https://example.com/first-frame.jpg" }, role: "first_frame" },
],
duration: 5,
resolution: "768p",
ratio: "16:9",
}),
},
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const task = await response.json();
console.log(task.id);
创建参数
typestring可选
视频生成请求传入
video;省略时服务端按视频任务处理。modelstring必填
contentarray必填
视频生成输入内容块。
typestring必填
可选
text、image_url、video_url 或 audio_url。textstring文本块必填
用于描述期望生成内容的提示词。每次请求必须且只能包含一个非空文本块。
image_url.urlstring图片块必填
图片公网 HTTPS URL 或
data:image/<format>;base64,<data>。video_url.urlstring视频块必填
视频公网 HTTPS URL;不支持 Base64。
audio_url.urlstring音频块必填
音频公网 HTTPS URL 或
data:audio/<format>;base64,<data>。rolestring媒体块必填
图片支持
first_frame、last_frame、reference_image;视频支持 reference_video;音频支持 reference_audio。单张首帧图片可省略 role。durationinteger可选
期望生成的视频时长,单位为秒。省略时使用所选模型的默认值;支持的取值及默认值请以对应模型的能力说明为准。
resolutionstring可选
期望输出的分辨率档位。省略时使用所选模型的默认值;支持的取值及对应输出尺寸由模型决定。
ratiostring可选
期望输出的视频画幅比例。省略时使用所选模型的默认值;支持的取值由模型决定。
negative_promptstring可选
描述不希望出现在生成结果中的内容。是否支持及具体效果由所选模型决定。
seedinteger可选
用于控制生成随机性的种子。是否支持、合法取值范围及结果可复现程度由所选模型决定。
safety_identifierstring可选
用于安全追踪的稳定终端用户标识。不要传入姓名、邮箱等直接身份信息。
execution_expires_afterinteger可选
任务执行过期阈值,单位为秒。超过阈值后任务可能停止执行。
输入组合与限制
| 生成方式 | content 组合 |
|---|---|
| 文生视频 | text |
| 首帧图生音视频 | text + 1 个 image_url,role=first_frame 或省略 role |
| 尾帧图生音视频 | text + 1 个 image_url,role=last_frame |
| 首尾帧图生音视频 | text + 2 个 image_url,角色分别为 first_frame 和 last_frame |
| 全模态参考生音视频 | text + 参考图片和/或参考视频;可同时添加参考音频 |
输入角色需与生成模式匹配
- FL2VA:
first_frame/last_frame不可与 Ref2VA 的reference_*角色混用;双图请求需分别标记首帧与尾帧。 - Ref2VA:
reference_audio不能单独使用,必须搭配至少一个reference_image或reference_video。
Ref2VA 请求示例
{
"type": "video",
"model": "MiniMaxAI/MiniMax-H3-Ref2VA",
"content": [
{"type": "text", "text": "沿用参考画面的角色与运镜,按音频节奏生成街头短片。"},
{"type": "image_url", "image_url": {"url": "https://example.com/character.jpg"}, "role": "reference_image"},
{"type": "video_url", "video_url": {"url": "https://example.com/camera-motion.mp4"}, "role": "reference_video"},
{"type": "audio_url", "audio_url": {"url": "https://example.com/music.mp3"}, "role": "reference_audio"}
],
"duration": 8,
"resolution": "768p",
"ratio": "16:9"
}输入媒体限制
| 类型 | 格式 | 单文件限制 | 数量/时长 |
|---|---|---|---|
| 图片 | JPEG、PNG、WebP、BMP、TIFF、GIF、HEIC、HEIF | 最大 30 MB;宽高 300~5760 px;宽高比 0.4~2.5 | FL2VA 最多 2 张;Ref2VA 最多 9 张 |
| 视频 | MP4、MOV;H.264/AVC、H.265/HEVC;音轨支持 AAC、MP3,MOV 额外支持 PCM | 最大 50 MB;单段 2~15 秒;宽高 300~5760 px;宽高比 0.4~2.5;帧率 23.976~60 | Ref2VA 最多 3 段,MiniMax H3 总时长最多 15 秒 |
| 音频 | WAV、MP3 | 最大 15 MB;单段 2~15 秒 | Ref2VA 最多 3 段,MiniMax H3 总时长最多 15 秒 |
输入图片按实际有效张数计量,输入视频和音频按实际有效时长计量;输出按成功生成的视频时长和分辨率计量。实际单价以官网价格页和账单为准。
查询任务
使用创建响应中的 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。任务仅输出一个 MP4;如生成原生音频,音轨将封装在同一文件中,不单独返回音频文件或元数据。
成功结果
{
"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": "MiniMaxAI/MiniMax-H3",
"duration": 5,
"resolution": "768p",
"ratio": "16:9",
"framespersecond": 24,
"width": 1344,
"height": 768,
"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 | 服务内部错误或模型暂不可用 | 创建成功后优先查询原任务 |
