wylon
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全模态参考生音视频文本 + 至少一张参考图片或一段参考视频;可同时添加参考音频
参数FL2VARef2VA默认值
duration5~15 秒5~15 秒5
resolution768P768P768P
ratio21:9、16:9、4:3、1:1、3:4、9:16、自适应21:9、16:9、4:3、1:1、3:4、9:1616: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

创建参数

typestring可选
视频生成请求传入 video;省略时服务端按视频任务处理。
modelstring必填
wylon 提供的完整模型 ID,例如 MiniMaxAI/MiniMax-H3 或 MiniMaxAI/MiniMax-H3-Ref2VA。可前往 模型广场 或通过 列出模型 确认访问权限。
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.5FL2VA 最多 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~60Ref2VA 最多 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
状态含义建议操作
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

签名 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}"

删除任务记录或取消任务可能不可恢复。调用前应确认任务 ID 和当前状态。

错误处理与生产建议

状态码常见原因建议操作
400文本、媒体类型、角色、数量、文件规格或模型能力不合法根据错误码和当前模型限制修正请求
401、403密钥无效或没有模型、任务权限检查鉴权与账户权限
404模型或任务不存在检查完整模型 ID、任务 ID 和调用环境
429请求频率、并发或容量达到限制降低请求频率并稍后重试
500、503服务内部错误或模型暂不可用创建成功后优先查询原任务
沪ICP备2026010432号-1沪公网安备31010402336632号